From 21b634873199374c9150a5054aee5429a61febe7 Mon Sep 17 00:00:00 2001 From: Heitor Ramon Ribeiro Date: Thu, 5 Nov 2026 16:31:50 -0300 Subject: [PATCH 1/3] fix(schedule): reject interval multiplication overflow --- crates/cli/src/schedule.rs | 12 ++++++++---- docs/architecture/bots.md | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/crates/cli/src/schedule.rs b/crates/cli/src/schedule.rs index dc4ca666..a22933a8 100644 --- a/crates/cli/src/schedule.rs +++ b/crates/cli/src/schedule.rs @@ -89,12 +89,13 @@ fn parse_every(rest: &str) -> Result { (amount, unit) } }; - let secs = match unit { - "m" | "min" | "mins" | "minute" | "minutes" => amount * 60, - "h" | "hr" | "hrs" | "hour" | "hours" => amount * 3600, - "d" | "day" | "days" => amount * 86_400, + let multiplier = match unit { + "m" | "min" | "mins" | "minute" | "minutes" => 60, + "h" | "hr" | "hrs" | "hour" | "hours" => 3600, + "d" | "day" | "days" => 86_400, _ => return Err(format!("Could not read the interval {rest:?}. Use every 30m, every 2h, or every 1d.")), }; + let secs = amount.checked_mul(multiplier).ok_or("That interval is longer than a year.")?; if secs < MIN_INTERVAL_SECS { return Err("That runs too often. A routine runs at most every five minutes.".into()); } @@ -366,6 +367,9 @@ mod tests { assert_eq!(parse("every 120m").unwrap().canonical(), "every 2h"); assert!(parse("every 2m").unwrap_err().contains("too often")); assert!(parse("every fortnight").is_err()); + for unit in ["m", "h", "d"] { + assert!(parse(&format!("every {}{unit}", i64::MAX)).unwrap_err().contains("longer than a year")); + } assert_eq!(parse("every 30m").unwrap().next_after(1000), Some(2800)); } diff --git a/docs/architecture/bots.md b/docs/architecture/bots.md index 50d723e7..61921c41 100644 --- a/docs/architecture/bots.md +++ b/docs/architecture/bots.md @@ -47,7 +47,7 @@ A routine is a task a bot runs on a schedule in its direct chat with the user, a The roster also carries Auto-review (see [Plugins](plugins.md#plugins)). Routines live in the roster (`Routine { id, bot_id, name, prompt, schedule, is_enabled, enabled_at, last_run_at?, last_outcome?, paused_reason?, check?, created_at }`), so every paired Device lists them and can pause, resume, run, or delete one (`routines.create` / `routines.update` / `routines.delete` / `routines.run`, and `routines.describe` to read a schedule back). The bot's Runner runs them (`crates/cli/src/routines.rs`): every half minute it starts the routines of its bots whose next run is due, or their checks, and starts none while a run or check of the routine is going on. -A schedule (`crates/cli/src/schedule.rs`) is `every 30m`, `every 2h`, `every 1d`, or five cron fields read in the Runner's local time (`0 9 * * 1-5`), never more often than every five minutes. An interval counts from the last run, or from when the routine was created or resumed; a cron fires at the next matching minute after that. The CLI says a schedule in words on the wire (`schedule_text`: "Weekdays at 9:00 AM", "Every 2 hours", "On the 1st of every month at 8:30 AM", else "Cron 5 4 * * 1-3") and gives `next_run_at` and `is_running` beside every routine. +A schedule (`crates/cli/src/schedule.rs`) is an interval (`every 30m`, `every 2h`, `every 1d`) or five cron fields in the Runner's local time (`0 9 * * 1-5`), at most every five minutes. Intervals use checked arithmetic and range from five minutes to 366 days. They count from the last run, creation or resume; cron fires at the next matching minute. The wire provides `schedule_text` ("Weekdays at 9:00 AM", "Every 2 hours", "On the 1st of every month at 8:30 AM", else "Cron 5 4 * * 1-3"), `next_run_at` and `is_running` for each routine. A run is a `routine` Job in the bot's DM. It opens with a "Routine · Name" marker (a system notice carrying the routine id), then the turn runs with the routine's prompt as the task and a system prompt that says nobody is typing: the bot does the work, replies with what the user should know, or answers `PASS`, which leaves only the marker. Later turns rebuild the marker as `[Routine "Name" ran on its schedule. Task: …]`; the daily log names the routine as the turn's source. `job.started` / `job.finished` carry `routine_id`, so the apps show the routine as running and the bot at work. A run's outcome (`sent`, `pass`, `error`) is kept on the routine. Run Now from a Device that is not the Runner seals the job to the Runner like any turn. From df9b8fde1e84cbd221580d01ab4cfb2d8905e2cd Mon Sep 17 00:00:00 2001 From: Heitor Ramon Ribeiro Date: Thu, 5 Nov 2026 22:47:49 -0300 Subject: [PATCH 2/3] fix(schedule): bound the next interval firing timestamp --- crates/cli/src/schedule.rs | 25 +++++++++++++++++++++++-- docs/architecture/bots.md | 2 +- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/crates/cli/src/schedule.rs b/crates/cli/src/schedule.rs index a22933a8..77bffe69 100644 --- a/crates/cli/src/schedule.rs +++ b/crates/cli/src/schedule.rs @@ -155,10 +155,11 @@ fn parse_value(text: &str, min: u32, max: u32, names: &[&str]) -> Result Option { match self { - Schedule::Every(secs) => Some(after + secs), + Schedule::Every(secs) => after.checked_add(*secs), Schedule::Cron(cron) => cron.next_after(after), } } @@ -354,6 +355,26 @@ mod tests { local_unix(date, Some(clock)).unwrap() } + #[test] + fn oversized_intervals_reject_without_overflow_or_wraparound() { + for input in [ + "every 9223372036854775807m", "every 9223372036854775807h", + "every 9223372036854775807d", "every 144115188075855873d", + ] { + assert!(parse(input).is_err(), "accepted {input}"); + } + assert_eq!(parse("every 366d").unwrap(), Schedule::Every(366 * 86_400)); + assert!(parse("every 367d").is_err()); + } + + #[test] + fn interval_next_firing_does_not_wrap_timestamp() { + let schedule = parse("every 5m").unwrap(); + assert_eq!(schedule.next_after(i64::MAX - 300), Some(i64::MAX)); + assert_eq!(schedule.next_after(i64::MAX - 299), None); + assert_eq!(schedule.next_after(i64::MIN), Some(i64::MIN + 300)); + } + #[test] fn intervals_parse_and_read_back() { assert_eq!(parse("every 30m").unwrap(), Schedule::Every(1800)); diff --git a/docs/architecture/bots.md b/docs/architecture/bots.md index 61921c41..41754582 100644 --- a/docs/architecture/bots.md +++ b/docs/architecture/bots.md @@ -47,7 +47,7 @@ A routine is a task a bot runs on a schedule in its direct chat with the user, a The roster also carries Auto-review (see [Plugins](plugins.md#plugins)). Routines live in the roster (`Routine { id, bot_id, name, prompt, schedule, is_enabled, enabled_at, last_run_at?, last_outcome?, paused_reason?, check?, created_at }`), so every paired Device lists them and can pause, resume, run, or delete one (`routines.create` / `routines.update` / `routines.delete` / `routines.run`, and `routines.describe` to read a schedule back). The bot's Runner runs them (`crates/cli/src/routines.rs`): every half minute it starts the routines of its bots whose next run is due, or their checks, and starts none while a run or check of the routine is going on. -A schedule (`crates/cli/src/schedule.rs`) is an interval (`every 30m`, `every 2h`, `every 1d`) or five cron fields in the Runner's local time (`0 9 * * 1-5`), at most every five minutes. Intervals use checked arithmetic and range from five minutes to 366 days. They count from the last run, creation or resume; cron fires at the next matching minute. The wire provides `schedule_text` ("Weekdays at 9:00 AM", "Every 2 hours", "On the 1st of every month at 8:30 AM", else "Cron 5 4 * * 1-3"), `next_run_at` and `is_running` for each routine. +A schedule (`crates/cli/src/schedule.rs`) is an interval (`every 30m`, `every 2h`, `every 1d`) or five cron fields in the Runner's local time (`0 9 * * 1-5`), at most every five minutes. Intervals use checked arithmetic and range from five minutes to 366 days. They count from the last run, creation or resume; an overflowing next timestamp returns no firing. Cron fires at the next matching minute. The wire provides `schedule_text` ("Weekdays at 9:00 AM", "Every 2 hours", "On the 1st of every month at 8:30 AM", else "Cron 5 4 * * 1-3"), `next_run_at` and `is_running` for each routine. A run is a `routine` Job in the bot's DM. It opens with a "Routine · Name" marker (a system notice carrying the routine id), then the turn runs with the routine's prompt as the task and a system prompt that says nobody is typing: the bot does the work, replies with what the user should know, or answers `PASS`, which leaves only the marker. Later turns rebuild the marker as `[Routine "Name" ran on its schedule. Task: …]`; the daily log names the routine as the turn's source. `job.started` / `job.finished` carry `routine_id`, so the apps show the routine as running and the bot at work. A run's outcome (`sent`, `pass`, `error`) is kept on the routine. Run Now from a Device that is not the Runner seals the job to the Runner like any turn. From d926ace1b5f81771ec40ee41e987d170526c47cf Mon Sep 17 00:00:00 2001 From: Heitor Ramon Ribeiro Date: Fri, 6 Nov 2026 11:51:58 +0000 Subject: [PATCH 3/3] chore(tooling): propagate reviewed Beans AI tooling --- .codegraph-version | 1 + .codegraph/.gitignore | 5 +++ AGENTS.md | 2 + docs/ai-tooling.md | 86 +++++++++++++++++++++++++++++++++++++++++++ scripts/codegraph.sh | 17 +++++++++ 5 files changed, 111 insertions(+) create mode 100644 .codegraph-version create mode 100644 .codegraph/.gitignore create mode 100644 docs/ai-tooling.md create mode 100755 scripts/codegraph.sh diff --git a/.codegraph-version b/.codegraph-version new file mode 100644 index 00000000..fdd3be6d --- /dev/null +++ b/.codegraph-version @@ -0,0 +1 @@ +1.6.2 diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore new file mode 100644 index 00000000..d20c0fe4 --- /dev/null +++ b/.codegraph/.gitignore @@ -0,0 +1,5 @@ +# CodeGraph data files — local to each machine, not for committing. +# Ignore everything in .codegraph/ except this file itself, so transient +# files (the database, daemon.pid, sockets, logs) never show up in git. +* +!.gitignore diff --git a/AGENTS.md b/AGENTS.md index a6f3edd8..e4ffb564 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # Beans +For T3 onboarding, retrieval, command output and model reservations, follow [AI tooling](docs/ai-tooling.md). Product work remains HOLD until Heitor explicitly says OK. + Read [ARCHITECTURE.md](./ARCHITECTURE.md) before writing code, then the subject docs it lists for the parts you change. Identity is a local key pair. Paired Devices sync through an E2E relay. Provider credentials belong to the account: they sync to every paired Device as a blob encrypted with the account key. The AppKit app talks to the local CLI. diff --git a/docs/ai-tooling.md b/docs/ai-tooling.md new file mode 100644 index 00000000..b781f692 --- /dev/null +++ b/docs/ai-tooling.md @@ -0,0 +1,86 @@ +# Prepare and use AI tooling + +Read [AGENTS.md](../AGENTS.md), [BEANS.md](../BEANS.md) and [ARCHITECTURE.md](../ARCHITECTURE.md) before changing Beans. `CLAUDE.md` points to `AGENTS.md`; preserve that link and all existing instructions. + +## Keep product work on HOLD + +This preparation permits onboarding, tooling installation, independently reviewed tooling PRs, normal tooling merges and branch propagation. Product work remains HOLD until Heitor explicitly says OK. Green checks, a tooling merge and completed propagation do not release product work. Do not merge product PRs during this rollout. + +The central coordinator owns global settings and routing. Read `/Users/heitor/.config/ai-tooling/COORDINATION.md` and the current `GLOBAL-ROLLOUT.md` linked there. Report global configuration gaps to that coordinator. Keep one external rollout REPORT with commands, exit codes, receipt hashes, exact heads, resources and blockers. + +Target `bloodf/beans` explicitly for GitHub operations. `origin` is the Beans repository; `upstream` is `egoist/lorca`. T3's upstream canonical identity does not authorize upstream publication or integration. Confirm remotes, branch, HEAD, current base, worktrees and dirty state before writing. Similar source content does not prove ancestry. + +Preserve all refs with a verified Git bundle before propagation. Save staged and unstaged patches, untracked files and their hashes separately. Use an isolated tooling checkout. Preserve existing worktrees and previous work. Do not use automatic stash, `reset --hard`, force push or shared cleanup. + +## Retrieve source with CodeGraph 1.6.2 + +The standalone CLI is pinned by `.codegraph-version`. `scripts/codegraph.sh` checks the installed version, disables telemetry for its process and runs from this checkout's root. Keep CodeGraph outside application dependencies. + +Use the existing installation when it matches the pin. For workstation installation, inspect the installer at `https://raw.githubusercontent.com/colbymchenry/codegraph/f72c9d2efb14454ff4f9fd7b8460abd82f19a287/install.sh`, then run the inspected file with `CODEGRAPH_VERSION=v1.6.2`. Installation and user-specific MCP configuration belong to the central coordinator. + +Run these commands from the repository root: + +```sh +sh scripts/codegraph.sh init --yes +sh scripts/codegraph.sh sync +sh scripts/codegraph.sh status --json +sh scripts/codegraph.sh query dispatch --limit 5 --json +sh scripts/codegraph.sh callers dispatch --file crates/cli/src/api.rs --limit 5 --json +sh scripts/codegraph.sh explore --max-files 3 'api dispatch websocket serve' +``` + +Start with a bounded query before broad source reads. For exact text, missing results or unsupported syntax, use bounded `rg` and exact file ranges. Inspect the actual definition and caller before changing a flow. A graph relationship does not prove runtime behavior or complete dynamic call coverage. + +Each worktree has its own `.codegraph/` index. Do not copy databases between checkouts. Run `sync` and inspect `status --json` after checkout or edits. Check indexed languages, file/node counts, pending changes, worktree mismatch and index completion. Rebuild with `index` after changing include/exclude/extension rules. Version 1.6.2 has no `--strict` flag. + +Track only `.codegraph/.gitignore` inside `.codegraph/`. The ignore file excludes databases, logs, sockets, locks and daemon state. Never commit generated graphs or index data. With a configured CodeGraph MCP, keep the default single `codegraph_explore` tool; otherwise use the same bounded CLI commands. + +## Preserve command status with RTK 1.0.1 + +Read `/Users/heitor/.codex/RTK.md` when present. With a native RTK PreToolUse hook, run normal commands and do not wrap them twice. Without a native hook, use supported explicit commands such as `rtk git status` and `rtk gh pr list --repo bloodf/beans`. MiniMax uses this CLI route. Do not assume one harness's hooks apply to another. + +Preserve the actual exit code and first failure receipt. If condensed output is empty, contradictory or unusable, recover it with `rtk bypass ` or the stored raw receipt. Diagnose the first failure before another attempt. Do not weaken a check, timeout, baseline, security boundary or review requirement to obtain green results. + +## Use Caveman and Ponytail + +Use concise, complete Portuguese sentences with the user. Keep errors, identifiers, numbers and negations exact. Write code, persisted documents and critical instructions in complete language. + +Inspect the affected flow and callers, reuse existing code and standard libraries, and make the smallest complete change. Verify behavior at the relevant boundary. Preserve security, accessibility, approval, encryption and data-loss controls. Installation, synthetic probes, local checks, hosted checks and live behavior are separate evidence. + +## Verify TokenEconomizer per harness + +Reuse the central installation. Preserve the mode without auxiliary paid model calls: `microskills=envfacts`, `loopguard=off`, `repomap=off` and `toolprune=propose`. Do not set a paid model or enable paid proposers. Keep orchestration, review, device and required verification tools available; proposals cannot override project policy. + +From the checkout, inspect effective state without a model call: + +```sh +"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$PWD" status +"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$PWD" config show +"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$PWD" repos list +``` + +Confirm the repository identity is the Beans origin and verify a worktree maps to that same repository. Record the installed adapter's supported events for each harness actually used. Codex's installed hook file declares `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop` and `SessionEnd`; declaration alone does not prove delivery through T3. + +Separate configuration present from fresh-session runtime proof. Loading a skill, starting a process or seeing a zero-session status does not prove the full lifecycle. Record unproved events as UNKNOWN. Do not invent adapters or hook support for Antigravity, MiniMax or another harness. TokenEconomizer learns repository facts and proposes tool pruning; it is not a generic output compressor. No local token savings are claimed without measurement. + +## Reserve every worker through the central dispatcher + +Before each tooling worker, reserve a route: + +```sh +t3-model-route reserve --project beans --purpose tooling --task '' +``` + +Launch only the exact returned provider, model and options through the applicable T3 delegation mechanism. Antigravity accepts Google models only. MiniMax M3.1 Flash requires `m:minimax:MiniMax-M3.1-Flash:v:thinking`. Quota UNKNOWN is not proof of capacity. Never substitute another project, provider or model, retry quota blindly, edit the global helper or implement a local round robin. + +Give each worker exact scope and file ownership. State that concurrent work must be preserved. Record the lease, task/run, provider, model and terminal outcome. Release only the exact lease after terminal evidence. Start no top-level thread for a worker. Use a fresh independent reviewer for each review or re-check, with the exact base/head and applicable risk requirements. No author approves their own change. + +## Verify and propagate tooling + +Keep the existing Beans gates. `bun run check:docs`, `bun run check:catalog` and the same-repository PR test matrix remain applicable. Inspect the current workflow definitions before execution; a local tooling smoke does not replace hosted checks. Product homes, accounts, relays, signing inputs and deployments are not tooling fixtures. + +Create one tooling PR against current Beans `main` and link it immediately to T3. Merge only after independent exact-head review and the real required checks pass. When waiting for hosted checks, use T3's PR watch and end the run; do not poll CI. + +Before propagation, prepare a per-ref plan with original head, target payload, old-head ancestry proof and recovery instructions. Append only tooling to every existing local and origin branch, including historical branches and open PR heads. Preserve each branch's existing instruction and ignore bytes. Do not merge unrelated product history, silently resolve divergence or recreate a branch absent from the server. Push fast-forward with explicit refspecs. Stop on the first remote write failure, re-read remote state and report to central before retry or a strategy change. + +Recheck current remote and PR heads, rescan for new refs, validate indexes in used checkouts and settle owned processes and leases. Record any uncovered ref as BLOCKED with a concrete reason. Product work still waits for Heitor's explicit OK. diff --git a/scripts/codegraph.sh b/scripts/codegraph.sh new file mode 100755 index 00000000..d6aa27fb --- /dev/null +++ b/scripts/codegraph.sh @@ -0,0 +1,17 @@ +#!/bin/sh +# Run from any directory with the repository's reviewed CodeGraph version. +set -eu +codegraph_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd) +cd "$codegraph_root" +codegraph_expected=$(cat .codegraph-version) +if ! command -v codegraph >/dev/null 2>&1; then + echo "CodeGraph $codegraph_expected required. See docs/ai-tooling.md." >&2 + exit 1 +fi +codegraph_actual=$(codegraph --version) +if [ "$codegraph_actual" != "$codegraph_expected" ]; then + echo "CodeGraph $codegraph_expected required; found $codegraph_actual. See docs/ai-tooling.md." >&2 + exit 1 +fi +export CODEGRAPH_TELEMETRY=0 +exec codegraph "$@"