diff --git a/docs/README.md b/docs/README.md index c569a492..03a7b247 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,11 @@ | Where | What lives there | |---|---| +| [`prompt-design.md`](prompt-design.md) | How the subagent prompts are designed | +| [`plans/`](plans/README.md) | Where `/planx` writes execution plans, and their layout | + +The user documentation for the CLI lives with the package, in +[`packages/aitm/docs/`](../packages/aitm/docs/). The brain itself is the repo root's [`CLAUDE.md`](../CLAUDE.md); the commands are `bin/{setup,dev,check,stop}`. diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/01-coding-style-distillation.md b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/01-coding-style-distillation.md deleted file mode 100644 index 9fcdb81b..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/01-coding-style-distillation.md +++ /dev/null @@ -1,29 +0,0 @@ -# 01 — Coding-style distillation - -> Part of [`overview.md`](overview.md). Depends on: none. - -Claudetm distills a cached `coding-style.md` (workflow, code style, **testing paths/commands/example files**, project-specific rules) from CLAUDE.md + test globs + config, then injects that *digest* into every planning and work prompt. aitm currently injects raw CLAUDE.md contents (`AgentConfigDetector` → orchestrator system prefix). Add the distillation step; keep raw contents as the distiller's input. - -Source ref: `core/planner.py:18` (`ensure_coding_style`), `core/prompts_coding_style.py:18` (prompt + `CODING_STYLE_COMPLETE` marker), `core/state_file_ops.py:138` (load/cache). - -## Files to change -- `src/agent-config/coding-style.ts` — **new**. `StyleDistiller`: input `AgentConfig` (+ repoRoot), output a compact markdown digest. One responsibility: turn raw style signals into a digest. -- `src/agent-config/coding-style.test.ts` — **new** (see `05`). -- `src/state/state-store.ts:10` — add `coding-style.md` to the managed file set; add `writeCodingStyle(md)` / `readCodingStyle()` (mirror `writeContext`/`readContext` at `state-store.ts:79`). -- `src/subagents/factory.ts` / `composeSystemPrompt` (used by `planner.ts:43`, `worker.ts:114`, `reviewer.ts:78`) — feed the digest as the style prefix instead of, or in addition to, raw `AgentConfig.contents`. -- `src/cli/commands.ts:135` (`runStart`) — after detecting `AgentConfig`, distill once and cache to state dir; reuse cache on resume. - -## Steps -1. Define `StyleDistiller` with a `distill(input): Promise` method. Input: `{ config: AgentConfig | null, repoRoot: string }`. It runs a one-shot LLM call (model via `Credentials.modelFor('planner')` — smart capability) with a prompt mirroring `prompts_coding_style.py`: analyze CLAUDE.md/AGENTS.md/CONTRIBUTING + test file globs (`**/*.test.ts`, `test/integration/**`) + config (`biome.json`, `tsconfig*.json`, `package.json` scripts). Output sections: Workflow, Code Style, Testing (paths/naming/commands/example files — mark CRITICAL), Project-Specific. -2. Cache: `runStart` calls `StateStore.readCodingStyle()`; if absent, `distill()` then `writeCodingStyle()`. Resume reuses the cached digest (claudetm regenerates only if missing). -3. Inject: replace the raw-contents prefix in `composeSystemPrompt` with the digest. If distillation fails or no `AgentConfig` exists, fall back to raw `AgentConfig.contents` (or empty) — never block the run on style. -4. Keep `AgentConfigDetector` unchanged; it remains the raw-signal source. Distiller is a separate module (SRP). - -## Tests -- Unit `coding-style.test.ts`: stub model (`MockLanguageModelV3` from `ai/test`), assert prompt includes CLAUDE.md contents + test globs; assert digest passed through; assert fallback-to-raw on model error. -- Unit `state-store.test.ts`: `writeCodingStyle`/`readCodingStyle` round-trip; `readCodingStyle` returns null on ENOENT (mirror existing context test). -- Commands: `bun test`, `bun run typecheck`, `bun run lint`, `bun run test:node`. - -## Done when -- `aitm start` produces `.ai-task-master/coding-style.md` on first run, reuses it on resume, and subagent system prompts carry the digest (verify via planner/worker prompt assembly test). -- No regression: runs with no CLAUDE.md still work (empty/raw fallback). diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/02-task-subtask-model.md b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/02-task-subtask-model.md deleted file mode 100644 index 92b9a14d..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/02-task-subtask-model.md +++ /dev/null @@ -1,33 +0,0 @@ -# 02 — Task / subtask execution model - -> Part of [`overview.md`](overview.md). Depends on: 01 (digest available to prompts). - -Claudetm executes a PR group task-by-task: each task carries a complexity marker, a checkbox in `plan.md`, and is marked `[x]` when done; `pr_per_task` decides PR-per-task vs PR-per-group. aitm's `PrGroup.tasks` is a flat `string[]` with no per-task state — a group is one Worker pass. Add per-task structure + completion tracking, keeping aitm's group-as-PR default. - -Source ref: `core/task_runner.py:140` (group context), `:481` (task regex `^- \[[ x]\] (\[.*?\] )?(.*)$`), `:217` (run_work_session per task), `mark_task_complete`; `core/task_group.py` (`ParsedTask`/`TaskGroup`). - -## Files to change -- `src/plan/schema.ts` / `src/state/schema.ts:15` (`PrGroup`) — change `tasks: string[]` → `tasks: Task[]` where `Task = { id, text, complexity: 'simple'|'normal'|'complex', done: boolean, subtasks?: string[] }`. Keep `Plan` schema (`plan/schema.ts:25`) in sync. -- `src/plan/plan-markdown.ts` — **new**. Parse/render `plan.md` checkbox+complexity format (`## Group: ` + `- [ ] [NORMAL] `). Round-trips `Plan` ↔ markdown. SRP: markdown only. -- `src/plan/plan-markdown.test.ts` — **new**. -- `src/subagents/planner.ts:28` — planner output schema emits structured `Task[]` per group (complexity + optional subtasks), not bare strings. Update `PLANNER_SYSTEM_PREFIX` to ask for complexity tags. -- `src/subagents/worker.ts:80` — Worker input takes the current `Task` (or task slice) instead of the whole group when running per-task; manifest/editor phase unchanged. -- `src/loop/work-loop.ts:135` (`runGroup`) — iterate the group's tasks: run Worker per task, mark `task.done`, persist, render `plan.md` via `plan-markdown`. Open PR when last task in group completes (default) or per task if `prPerTask` set. -- `src/state/state-store.ts:69` (`writePlan`) — render via `plan-markdown` so `plan.md` carries checkbox state (claudetm parity). -- `src/cli/args.ts:61` (`parseStart`) — add `--pr-per-task` flag → `RunState.options.prPerTask`. - -## Steps -1. Extend schemas (Zod) for `Task` + `prPerTask` option. Migrate any existing-state reads defensively (treat `string[]` as `[{text, complexity:'normal', done:false}]`) — there's no migration framework, so coerce on read in `StateStore.read` (`state-store.ts:33`). -2. Implement `plan-markdown` parse/render mirroring the claudetm regex; complexity tag optional → defaults `normal`. No checkboxes anywhere except `plan.md` itself. -3. Planner: emit `Task[]` with complexity. Reuse `Credentials` role→capability (`credentials.ts:13`) — complexity is metadata for ordering/reporting, not new model wiring unless trivial. -4. `runGroup`: loop tasks in order; per task → Worker → commit → mark `done` → re-render `plan.md` + persist `RunState`. Decide PR trigger by `prPerTask || isLastTaskInGroup`. Keep worktree acquisition + `StateWriteAfterSuccess` guard intact. -5. Resume: skip tasks already `done`. - -## Tests -- Unit `plan-markdown.test.ts`: parse↔render round-trip incl. complexity tags + `[x]` state; tolerates missing complexity. -- Unit `schema.test.ts`: `Task` validation; legacy `string[]` coercion. -- Unit `work-loop.test.ts`: per-task loop marks tasks done in order; PR opens on last task (group mode) and each task (`prPerTask`); resume skips done tasks. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- A multi-task group executes task-by-task, `plan.md` shows `[x]` per completed task, and PR-open timing respects `--pr-per-task`. Resume continues from the first undone task. diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/03-pr-lifecycle-stages.md b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/03-pr-lifecycle-stages.md deleted file mode 100644 index bfa29502..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/03-pr-lifecycle-stages.md +++ /dev/null @@ -1,29 +0,0 @@ -# 03 — PR-lifecycle stage machine - -> Part of [`overview.md`](overview.md). Depends on: 02 (per-group/per-task execution). - -Claudetm persists a `workflow_stage` so a crashed/paused run resumes mid-PR (e.g. re-enter `waiting_ci` without re-doing work). aitm's `WorkLoop.runGroup` does work→PR→CI-wait→review→merge inline (`work-loop.ts:135`), so an interrupt mid-lifecycle loses position. Add a **per-group** persisted stage and drive `runGroup` off it. - -Source ref: `core/orchestrator.py:1034` (`_run_workflow_cycle`), `core/workflow_stages.py` (per-stage handlers), `state.py` (`workflow_stage` field + transitions). - -## Files to change -- `src/state/schema.ts:15` (`PrGroup`) — add `stage: GroupStage` where `GroupStage = 'pending'|'working'|'pr-open'|'waiting-ci'|'ci-failed'|'waiting-reviews'|'addressing-reviews'|'ready-to-merge'|'merged'|'blocked'`. (Per-group, not global — aitm runs groups concurrently; see overview risk.) Keep existing `status` for coarse reporting or fold into `stage`. -- `src/loop/work-loop.ts:135` (`runGroup`) — refactor into a stage dispatcher: a `switch (group.stage)` advancing one transition per iteration, persisting after each. Mirror claudetm's `_run_workflow_cycle`. Keep concurrency batching (`work-loop.ts:113`) and `StateWriteAfterSuccess` (`work-loop.ts:94`). -- `src/loop/stage-handlers.ts` — **new**. One pure-ish handler per stage (`handleWorking`, `handlePrOpen`, `handleWaitingCi`, `handleCiFailed`, `handleWaitingReviews`, `handleAddressingReviews`, `handleReadyToMerge`). Each takes deps (github, state, subagents, prContext) + group, returns next stage. SRP: one stage per function. `ci-failed`/`addressing-reviews` bodies live in slice `04`. -- `src/loop/stage-handlers.test.ts` — **new**. -- `src/state/state-store.ts` — persist group stage transitions via existing `update(mutator)` (`state-store.ts:46`). - -## Steps -1. Add `stage` to `PrGroup` (default `pending`); coerce legacy state on read (`state-store.ts:33`) — missing stage → infer from `status`/`pr` (`merged`→`merged`, `pr!=null`→`waiting-ci`, else `pending`). -2. Extract current inline `runGroup` body into the stage handlers; `runGroup` becomes: load group, loop `handler[stage]`, persist new stage, until terminal (`merged`/`blocked`) or a stage yields (e.g. `waiting-ci` returns to let the batch breathe — keep polling inside `waitForChecks` but persist stage before/after). -3. Map transitions exactly to claudetm: `working→pr-open→waiting-ci→(ci-failed→waiting-ci | waiting-reviews)→(addressing-reviews→waiting-reviews | ready-to-merge)→merged`. `ci-failed`/`addressing-reviews` delegate to slice `04`. -4. Resume: `WorkLoop.run` (`work-loop.ts:113`) picks each group up at its persisted stage instead of restarting. PR-take-over path in `runMergePr` reuses the same handlers from `waiting-ci`. - -## Tests -- Unit `stage-handlers.test.ts`: each handler returns the correct next stage given stubbed github/state; terminal stages don't advance. -- Unit `work-loop.test.ts`: a group resumed at `waiting-ci` does NOT re-run Worker; full happy-path walks `pending→merged`; a blocked group stops. -- Integration `resume-flow.test.ts` (extend): interrupt after PR open, resume → continues at `waiting-ci` (stubbed gh). -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Each `PrGroup` carries a persisted `stage`; `WorkLoop` resumes any group mid-lifecycle without redoing prior stages; transition map matches claudetm. Existing happy-path integration tests stay green. diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/04-ci-fix-loop.md b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/04-ci-fix-loop.md deleted file mode 100644 index ae902d6a..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/04-ci-fix-loop.md +++ /dev/null @@ -1,35 +0,0 @@ -# 04 — CI-fix loop (download failed logs + comments → fix → re-poll → merge) - -> Part of [`overview.md`](overview.md). Depends on: 03 (stage machine provides `ci-failed`/`addressing-reviews` slots). - -The headline feature. Claudetm: on CI failure, download failed-run logs + unresolved review comments to `debugging/pr//{ci,comments}/`, run a fix session (strongest model) instructed to read those dirs, **rebase onto base then `git push --force-with-lease`**, wait `CI_START_WAIT`, re-poll, loop to a cap. Same loop powers `merge-pr `. aitm has all the primitives but `waitForChecks` (`github-client.ts:161`) throws `CiFailed` instead of entering a fix loop. - -Source ref: `cli_commands/fix_pr.py:168` (merge-pr loop, 30 iters), `ci_helpers.py:54` (`wait_for_ci_complete`, poll 10s / timeout 90m), `fix_session.py:31`, `workflow_stages.py:463` (`handle_ci_failed_stage`), `:798` (`handle_addressing_reviews_stage`), `core/pr_context.py` (`save_ci_failures`/`save_pr_comments`/`post_comment_replies`). - -## Files to change -- `src/github/github-client.ts:161` (`waitForChecks`) — split: keep the backoff poll, but return a structured `CiResult { state: 'success'|'failure'|'pending', failedChecks: [...] }` instead of throwing on failure. Callers decide. (Keep `CiFailed` for the terminal/timeout case.) Add `getFailedCiLogs` usage downstream (already exists, `:190`). -- `src/state/pr-context-store.ts` — confirm/extend `saveCiFailures(pr, logs)` and `saveComments(pr, threads)` write `debugging/pr//ci/failed_.txt` and `comments/__.txt` (claudetm layout). Add `addressedThreads` tracking (`debugging/pr//addressed_threads.json`) to avoid re-processing. -- `src/loop/stage-handlers.ts` (from `03`) — implement: - - `handleCiFailed`: `getFailedCiLogs` + `listUnresolvedThreads` → `prContext.saveCiFailures`/`saveComments` → run **fix session** (Worker with a fix prompt pointing at the `debugging/` dirs, `push_only` semantics) → rebase+force-push → set stage `waiting-ci`. - - `handleAddressingReviews`: `listUnresolvedThreads` minus `addressedThreads` → `Reviewer` (already loops threads, `reviewer.ts:125`) → `replyToThread`/`resolveThread` → record addressed → stage `waiting-reviews`. -- `src/loop/ci-fix.ts` — **new**. Shared helper: `runFixSession({github, prContext, subagents, group, pr})` used by both `handleCiFailed` and `merge-pr`. Encapsulates download→fix→rebase→force-push. SRP. -- `src/loop/ci-fix.test.ts` — **new**. -- `src/cli/commands.ts:262` (`runMergePr`) — wrap the existing take-over+merge in the iteration loop: `for i in 1..maxIterations { waitForChecks; if failure||unresolved||conflict → runFixSession + sleep(startWait); else break } → mergePr`. Add `--max-iterations` to `args.ts:137` (`parseMergePr`), default 30. -- `src/loop/constants.ts` — **new** or extend: `CI_POLL_INTERVAL` (10s), `CI_START_WAIT` (60s), `CI_POLL_TIMEOUT` (claudetm uses 600s in-loop / 5400s in merge-pr — pick 600s for WorkLoop stage, configurable), `MERGE_STATE_WAIT` (60s), `DEFAULT_MAX_ITERATIONS` (30). - -## Steps -1. Make `waitForChecks` return `CiResult` (keep backoff `:162-183`). Update existing callers in `work-loop.ts` to branch on `state`. -2. Implement `runFixSession` (`ci-fix.ts`): download failed logs (`getFailedCiLogs`) + comments (`listUnresolvedThreads`) → persist to `PrContextStore` → build fix prompt: "Read `.ai-task-master/debugging/pr//ci/` and `/comments/`, fix ALL failures, then: `git fetch origin `, `git rebase origin/`, resolve conflicts, `git push --force-with-lease`." Run via Worker on the group's worktree/branch. Use `Credentials` coding capability (`credentials.ts:13`) — no hardcoded model. -3. Wire `handleCiFailed`/`handleAddressingReviews` (slice `03` handlers) to `runFixSession`/`Reviewer`; persist stage after each. -4. `runMergePr`: implement the bounded loop with `DEFAULT_MAX_ITERATIONS`, `CI_START_WAIT` between iterations, `MERGE_STATE_WAIT` for `mergeable==UNKNOWN`, then `mergePr` (existing `:414`). Exit codes: 0 merged, 1 cap-exhausted/conflict, 2 cancelled. -5. Always `--force-with-lease`; never plain force. Rebase before every push. Don't resolve threads the agent didn't address. - -## Tests -- Unit `ci-fix.test.ts`: given a `CiResult: failure`, asserts logs+comments saved to the right paths, fix prompt references the debugging dirs, rebase+`--force-with-lease` invoked (stub `RunCmd`). -- Unit `stage-handlers.test.ts` (extend): `handleCiFailed`→`waiting-ci`; `handleAddressingReviews` skips already-addressed threads. -- Unit `github-client.test.ts`: `waitForChecks` returns structured `CiResult` for success/failure/pending; timeout still throws. -- Integration (new `test/integration/ci-fix-loop.test.ts`): temp git repo + stubbed `gh` scripted to fail CI once then pass → loop downloads logs, runs (stubbed-model) fix, re-polls, merges. Mirror `test/integration/start-flow.test.ts` setup (`testing/temp-repo.ts`, `MockLanguageModelV3`). -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- On CI failure, a run downloads failed logs + unresolved comments to `.ai-task-master/debugging/pr//`, runs a fix session, rebases + force-with-lease pushes, re-polls, and merges when green — capped, resumable, in both `start` (WorkLoop) and `merge-pr`. Integration test proves the fail→fix→green→merge cycle. diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/05-tests.md b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/05-tests.md deleted file mode 100644 index c8e715ec..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/05-tests.md +++ /dev/null @@ -1,34 +0,0 @@ -# 05 — Tests - -> Part of [`overview.md`](overview.md). Depends on: 01–04 (each slice ships its own tests; this is the cross-cutting bar + integration coverage). - -House rule: **no test, no merge.** Every new module has a paired `*.test.ts`; tests pass under both `bun test` and `node --test` (`bun run test:node`). Integration tests run a real temp git repo with a stubbed `gh` and `MockLanguageModelV3` — no real network, no real GitHub. - -## Files to change / add -- Paired units (created in their slices, listed here for the gate): - - `src/agent-config/coding-style.test.ts` (01) - - `src/plan/plan-markdown.test.ts`, `src/state/schema.test.ts` (02) - - `src/loop/stage-handlers.test.ts` (03) - - `src/loop/ci-fix.test.ts`, `src/github/github-client.test.ts` (extend, 04) - - `src/loop/work-loop.test.ts` (extend, 02+03) - - `src/state/state-store.test.ts` (extend, 01+02+03) -- Integration: - - `test/integration/ci-fix-loop.test.ts` — **new** (04): fail-once-then-pass CI → download→fix→re-poll→merge. - - `test/integration/resume-flow.test.ts` — **extend** (03): resume mid-lifecycle at `waiting-ci`. - - `test/integration/start-flow.test.ts` — **extend** (02): multi-task group writes `[x]` per task to `plan.md`. - -## Steps -1. Reuse `testing/temp-repo.ts` (`makeTempRepo({ withClaudeMd: true })`) and the stubbed-gh pattern from existing integration tests. Script the gh stub to return a failing `gh pr checks` once, then success, to exercise the loop. -2. Stub the model with `MockLanguageModelV3` (`ai/test`) — assert prompts contain the coding-style digest (01) and reference `debugging/` dirs (04); return canned tool-call sequences for manifest/editor/fix. -3. Cover legacy-state coercion (02/03): a `state.json` with `tasks: string[]` and no `stage` loads and runs. -4. Cover failure modes: CI-fix loop hits iteration cap → exit 1; merge conflict → exit 1; cancellation → exit 2. -5. Ensure no Bun-only APIs leak into shipped code (CI runs `test:node`); keep `Bun.*` only in dev/test guarded by `process.versions.bun`. - -## Tests (commands) -- `bun test` — full suite (unit + integration). -- `bun run test:node` — Node ≥20 portability. -- `bun run typecheck` — `tsc --noEmit`, strict, no `any`. -- `bun run lint` — Biome. - -## Done when -- Every new module has a green paired test under both runners; the `ci-fix-loop` integration test proves fail→fix→green→merge end to end; resume + legacy-coercion + cap/conflict/cancel paths covered. `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint` all pass. diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/overview.md b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/overview.md deleted file mode 100644 index 1939e1f9..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/overview.md +++ /dev/null @@ -1,37 +0,0 @@ -# Port claudetm `start` / `merge-pr` behavior to aitm - -## Goal -Bring claude-task-master's strongest behaviors into `aitm`: distilled coding-style planning, task/subtask-driven PR execution, the `.ai-task-master` lifecycle state, and the CI-wait → download-failed-logs+comments → fix → re-poll → merge loop. Close the gaps between aitm's existing scaffolding and claudetm's proven workflow — **without** porting claudetm's out-of-scope features. - -## Context -- **Source**: `../claude-task-master` (Python). Reference behavior only — do not copy code. Key files: `src/claude_task_master/cli_commands/{workflow.py,fix_pr.py,ci_helpers.py,fix_session.py}`, `core/{orchestrator.py,task_runner.py,planner.py,pr_context.py,state.py,workflow_stages.py}`, `github/client_pr.py`. -- **Target**: `packages/aitm` (TypeScript, Bun/Node≥20/Deno≥1.40). Stack: `ai` package `experimental_Agent` subagents-as-tools; OpenRouter-only via `Credentials`; `gh` CLI via `GitHubClient`. -- **aitm already has** (do not rebuild — extend): `GitHubClient` with `waitForChecks`/`getFailedCiLogs`/`listUnresolvedThreads`/`replyToThread`/`resolveThread`/`mergePr` (`src/github/github-client.ts`); `PrContextStore` (`src/state/pr-context-store.ts`); `StateStore` + `RunState`/`PrGroup` (`src/state/{state-store.ts,schema.ts}`); `WorkLoop` (`src/loop/work-loop.ts`); `Planner`/`Worker`/`Reviewer` (`src/subagents/*`); `AgentConfigDetector` (`src/agent-config/`); CLI `start`/`merge-pr` (`src/cli/{cli.ts,commands.ts,args.ts}`). -- **State dir**: aitm uses `.ai-task-master/` (claudetm uses `.claude-task-master/`). Keep aitm's name. `debugging/pr//{ci,comments}/` layout is shared. -- Reference patterns to follow: `src/subagents/planner.ts:60` (agent creation), `src/github/github-client.ts:161` (CI wait backoff), `src/loop/work-loop.ts:135` (per-group execution). - -## The real gaps (what this plan delivers) -1. **Coding-style distillation** — claudetm generates a cached `coding-style.md` from CLAUDE.md + test patterns + config, then injects the *distilled* digest into every prompt. aitm injects raw CLAUDE.md. → `01`. -2. **Task/subtask execution** — claudetm parses `[SIMPLE|NORMAL|COMPLEX]` checkbox tasks per PR group, executes per-task, marks `[x]` complete, supports PR-per-task vs PR-per-group. aitm's `PrGroup.tasks` is a flat `string[]` with no per-task state. → `02`. -3. **PR-lifecycle stage machine** — claudetm persists `workflow_stage` (`working→pr_created→waiting_ci→ci_failed→waiting_reviews→addressing_reviews→ready_to_merge→merged`) so a run resumes mid-lifecycle. aitm's WorkLoop does CI-wait→review→merge inline, no granular persisted stage. → `03`. -4. **CI-fix loop** — claudetm downloads failed CI logs + review comments to `debugging/`, feeds them to a fix session, rebases + force-pushes, re-polls, loops to a cap. aitm has the pieces (`getFailedCiLogs`, `PrContextStore`, `Reviewer`) but `waitForChecks` just throws `CiFailed` — the loop isn't wired. → `04`. -5. **`merge-pr` full loop** — claudetm `merge-pr ` is a standalone wait→fix→comments→merge loop (default 30 iterations). aitm `runMergePr` is a thinner take-over+merge. Wire the same fix loop in. → `04`. - -## Plan files (execute in order) -1. [`01-coding-style-distillation.md`](01-coding-style-distillation.md) — generate + cache distilled `coding-style.md`; inject digest into subagent prompts. -2. [`02-task-subtask-model.md`](02-task-subtask-model.md) — `Task`/subtask shape on `PrGroup`, plan.md checkbox parse/render, per-task execution + PR-per-task option. -3. [`03-pr-lifecycle-stages.md`](03-pr-lifecycle-stages.md) — persisted `workflowStage` on `RunState`; stage handlers so runs resume mid-PR. -4. [`04-ci-fix-loop.md`](04-ci-fix-loop.md) — CI-fail → download logs+comments → fix session → rebase/force-push → re-poll loop, in both WorkLoop and `merge-pr` (iteration cap). -5. [`05-tests.md`](05-tests.md) — unit + integration coverage for every new module/seam. - -## Done when -- `aitm start ""` plans with a distilled coding-style digest, executes each PR group task-by-task (marking `plan.md` checkboxes), and on CI failure downloads logs+comments, runs a fix session, rebases/force-pushes, re-polls, and merges when green — resumable at any stage. -- `aitm merge-pr ` runs the wait→fix→comments→merge loop to completion with an iteration cap. -- All new modules have paired `*.test.ts`; integration tests cover the CI-fix loop against a temp git repo + stubbed `gh`. `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint` all green. - -## Risks / open questions -- **Scope discipline**: claudetm ships webhooks, a mailbox/inbox, budget tracking, and a verification/release phase. Webhooks + mailbox are **out of scope per `CLAUDE.md`** — do NOT port. Budget/verification/release are optional and excluded from v1 of this plan unless the user asks. -- **Stage machine vs current inline WorkLoop**: slice `03` refactors `WorkLoop.runGroup` (`work-loop.ts:135`) to drive stages. Keep the `StateWriteAfterSuccess` guard (`work-loop.ts:94`) — losing a real PR-open/merge outcome to a failed state write is the main hazard. -- **Concurrency × stages**: aitm runs groups concurrently (DAG); claudetm is single-stream. Persisted per-group stage must be keyed by group id, not a single global `workflowStage`. Decide: per-group stage field on `PrGroup` (preferred) vs global. Plan assumes **per-group**. -- **Force-push safety**: always `git push --force-with-lease`, rebase onto `origin/` before push (claudetm `fix_pr.py`). -- **Model routing by complexity**: claudetm forces its strongest model for CI-fix/review sessions. aitm maps role→capability in `Credentials` (`credentials.ts:13`); reuse that (worker→coding, reviewer→smart) rather than hardcoding model ids. diff --git a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/status.yml b/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/status.yml deleted file mode 100644 index 8b29e66b..00000000 --- a/docs/plans/2026/06/28/101-claudetm-start-mergepr-port/status.yml +++ /dev/null @@ -1,27 +0,0 @@ -plan: 101-claudetm-start-mergepr-port -title: Port claudetm start / merge-pr behavior to aitm -status: not_started # not_started | in_progress | blocked | complete | superseded -created_by: plan-author -worked_by: "" -owner: plan-owner -percent: 0 -current_focus: "" -slices: - - file: 01-coding-style-distillation.md - status: not_started - percent: 0 - - file: 02-task-subtask-model.md - status: not_started - percent: 0 - - file: 03-pr-lifecycle-stages.md - status: not_started - percent: 0 - - file: 04-ci-fix-loop.md - status: not_started - percent: 0 - - file: 05-tests.md - status: not_started - percent: 0 -evidence: [] -notes: "claudetm webhooks + mailbox are OUT OF SCOPE per CLAUDE.md — excluded. Budget/verification/release phases excluded from v1 unless requested. State dir stays .ai-task-master/. Per-group stage (not global) because aitm runs groups concurrently." -last_updated: 2026-06-28 diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/01-untrusted-repo-trust-boundary.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/01-untrusted-repo-trust-boundary.md deleted file mode 100644 index fa5d7bca..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/01-untrusted-repo-trust-boundary.md +++ /dev/null @@ -1,36 +0,0 @@ -# 01 — Untrusted-repo trust boundary - -> Part of [`overview.md`](overview.md). Depends on: none. - -Autonomous runs point at arbitrary repos. Everything shipped *in* the target repo (`.ai-task-master/config.json`, `./.mcp.json`, `CLAUDE.md`/`AGENTS.md`, and GitHub review-comment bodies) is attacker-controlled input. Today parts of it steer inference, spawn processes, and enter tool-holding subagent prompts. The trust primitive already exists — `config-loader.ts:165` strips `hooks` from project config — extend it to every other execution-bearing field. - -## Files to change -| `file:line` | Problem | Fix | -| --- | --- | --- | -| `config/config-loader.ts:139-144, 346-377` + `credentials/credentials.ts:77-82` | Project `config.json` can set `baseURL`/`openrouterApiKey`; `providerSettings` then sends the user's env `OPENROUTER_API_KEY` as Bearer to an attacker host (inference-redirect + key exfil). | Accept `baseURL`/`openrouterApiKey` **only** from user-owned global config; warn+ignore from project scope, same as `hooks`. | -| `config/config-loader.ts:299-301, 358-363` + `mcp/mcp-client.ts:61-88` | `./.mcp.json` and project `mcpServers` feed `connectAll`, spawning stdio servers with attacker `command`/`args`/`env` — arbitrary code execution. | Gate stdio MCP from project scope behind the user-owned trust boundary (or explicit opt-in). HTTP/SSE-only from project, if any. | -| `config/config-writer.ts:138-168` (`splitKey`) | Missing the `FORBIDDEN_KEY_SEGMENTS` guard that `config/profiles.ts:210-228` has → `config set models.__proto__.polluted …` pollutes `Object.prototype` before schema validation. | Reuse profiles.ts's forbidden-segment rejection in `ConfigWriter`. | -| `config/config-loader.ts:312-319` (`writeSnapshot`) | Snapshot redacts only `openrouterApiKey`; serializes `mcpServers[*].env` + `headers` (bearer tokens) verbatim into `config.snapshot.json`, which the comment calls "safe to inspect." | Redact `mcpServers[*].headers` and `[*].env` in the snapshot. | -| `tools/web-fetch.ts:242-246` + `tools/fetch-html.ts:98-109` | `assertSafeUrl` checks only the initial URL; `fetch(redirect:'follow')` / `curl -L` follow 3xx to `169.254.169.254`/`localhost` unchecked (SSRF). curl also re-resolves DNS (TOCTOU). | `redirect:'manual'`, re-run `assertSafeUrl` per hop; curl `--max-redirs 0` (or resolve+pin+revalidate). | -| `agent-config/expand-imports.ts:166-168` | Per-branch `new Set(visited)` copy → diamond `@`-imports re-inline along every path (~B^depth), each a fresh `readFile`; no aggregate output cap. Hostile CLAUDE.md → memory/CPU blowup. | Global memoized visited set (inline each file once) + cumulative output-byte budget across the whole expansion. | -| `subagents/reviewer.ts:201` (`buildThreadPrompt`) | External reviewer comment bodies interpolated verbatim under "Conversation:"; Reviewer holds `bash`/`writeFile`/`editFile`/`github` → comment can command the agent. | Wrap external bodies in a labeled untrusted-data envelope (fenced ``) + explicit "data not instructions" directive. | -| `subagents/specialist-registry.ts:149` (`composeSpecialistGuidance`) | Target repo's `.claude/agents/*.md` `systemPrompt` concatenated verbatim into a bash/write-tool Worker prompt. Intentional style signal, but unframed. | Frame as advisory guidance placed **below** the immutable contract; note the trust assumption. | - -## Steps -1. Extract one trust helper (e.g. `isProjectScoped`/`stripUntrustedProjectFields`) so `baseURL`, `openrouterApiKey`, `mcpServers` (stdio), and existing `hooks` share **one** strip point in `config-loader`. Warn once per ignored field. -2. Resolve the env-vs-file precedence contradiction (finding auth#6, header `config-loader.ts:3` vs impl `:434-473`) as part of #1 — pick user-config-wins, env-fallback, and correct the header to match. -3. Add the forbidden-segment guard to `ConfigWriter.splitKey`; share the constant with `profiles.ts` (no duplication). -4. Redact MCP `env`/`headers` in `writeSnapshot`. -5. SSRF: switch both fetch paths to manual-redirect + per-hop revalidation; cap curl redirects. -6. `expand-imports`: global visited memo + shared byte budget; keep existing containment checks. -7. Reviewer + specialist prompt: untrusted-data envelope / advisory framing via `buildRolePrompt` (coordinate with slice `05`). - -## Tests -- Unit: project `config.json` with `baseURL`/`apiKey`/stdio `mcpServers` → resolved config ignores them, warns; global config with same → honored. `config set …__proto__…` throws, `Object.prototype` unpolluted. `writeSnapshot` output contains no MCP secret. `assertSafeUrl` on a public→internal redirect chain rejects. `expand-imports` on a diamond/hostile fixture stays within byte+time budget. Reviewer prompt fixture shows comment body fenced. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Project-scoped `baseURL`/`apiKey`/stdio-MCP are inert (warn+ignore); only user-owned config sets them. -- Prototype pollution via `config set` is rejected; snapshot carries no secrets. -- Redirect-based SSRF is blocked on both fetch paths; hostile import graphs are bounded. -- External comment/specialist text enters subagent prompts as clearly-delimited data, never as bare instructions. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/02-parallel-team-shared-checkout.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/02-parallel-team-shared-checkout.md deleted file mode 100644 index 8fedc88b..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/02-parallel-team-shared-checkout.md +++ /dev/null @@ -1,38 +0,0 @@ -# 02 — Parallel team on a shared checkout + shared state dir - -> Part of [`overview.md`](overview.md). Depends on: none for the state-write fixes; the **checkout-serialization decision** gates the git-isolation fixes (see overview Risks). - -Worktrees were removed (commit 7572a96) — all subagents share one working tree and one `.ai-task-master/`. `PlanGraph.ready()` can return several groups; editors already fan out via `Promise.all`. Nothing today prevents two Workers from `git checkout -B` + editing the same tree simultaneously, and several state writes are non-atomic read-modify-writes. This slice makes concurrency safe. - -## Decision gate (resolve first) -Pick one, confirm with owner: -- **(a) Serialize editing** — one group holds the checkout at a time; planning/review may still parallelize. Simplest given no worktrees. Assumed default. -- **(b) Restore isolation** — per-group scratch checkout. Contradicts the worktree-removal decision; larger change. -Everything below assumes **(a)** for git; the **state-write fixes apply under either**. - -## Files to change -| `file:line` | Problem | Fix | -| --- | --- | --- | -| `subagents/worker.ts:340` + `plan/plan-graph.ts:16` (`ready()`) | Concurrent Workers `git checkout -B` + edit the same tree → clobber each other's branch/diff. | Enforce a single-checkout lock: only one group in the edit/commit critical section at a time (mutex/promise-chain around checkout→edit→commit). | -| `subagents/worker.ts` `runWorker` (editor fanout runs `planAndEdit` **before** `checkout -B`) | Edits land on whatever branch is currently checked out. | Create/switch the group branch **before** the editor fanout writes any file. | -| `subagents/reviewer.ts:210-224` (`commitFix`) | `git add -A && commit` on whatever branch is checked out; input has `pr` but no branch → review fixes may commit to wrong branch. | Check out the PR head branch (or assert current branch == PR head) before committing. | -| `workspace/in-place-checkout.ts:63-66, 84-85` (`acquire`/`resetToBase`) | Never clean the tree; a crashed/blocked Worker's uncommitted edits get carried onto the next group's branch (contamination) or block the checkout. | Assert clean tree before switching; `git reset --hard` / stash-and-drop stale changes at group boundary. | -| `state/pr-context-store.ts:107-116` (`recordAddressedThreads`) | Plain `writeFile` + unserialized read-modify-write → lost updates + non-durable review-loop termination guard. | Route through `atomicWrite`; serialize appends on a per-store promise chain (copy `StateStore.update`, `state-store.ts:52`). | -| `state/state-store.ts:82-85` (`appendProgress`) | Bare `appendFile` from concurrent groups; large multi-line entries can interleave. | Serialize progress appends on the per-store chain. | -| `state/transcript-store.ts:156-171` (`nextOrdinal`) | `readdir`→`max+1` check-then-create race → two `begin`s pick the same ordinal, interleave one JSONL. | `open(...,'wx')` + retry-increment on `EEXIST`, or serialize `begin` per subdir. | - -## Steps -1. Land the **state-write fixes** first (`pr-context-store`, `state-store`, `transcript-store`) — independent of the git decision, and the highest-value concurrency wins for a shared state dir. -2. Resolve the decision gate. If (a): add a checkout mutex owned by the driver (`loop/work-loop.ts` / `run-loop-adapter.ts`) wrapping the edit/commit section; have `ready()` consumers acquire it. Ensure branch create/switch precedes editor writes in `runWorker`. -3. Reviewer: check out PR head before `commitFix`. -4. `in-place-checkout`: clean-tree assertion + reset/stash at `acquire`/`resetToBase`. - -## Tests -- Integration (temp git repo): two ready groups driven concurrently → each commits only its own files to its own branch; working tree never carries group A's edits into group B. Reviewer fix lands on the PR head branch. A dirty tree left before `acquire` is cleaned, not carried forward. -- Unit: concurrent `recordAddressedThreads` calls → union preserved, no lost ids, file readable after simulated mid-write. Concurrent `begin` → distinct ordinals, no shared JSONL. Concurrent `appendProgress` → no interleaved lines. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- No interleaving of branches, working-tree edits, or state files under concurrent groups. -- Review/CI fixes always commit to the intended PR branch on a clean tree. -- `addressed_threads`, progress, and transcript ordinals survive concurrent writers without lost updates. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/03-pr-ci-review-loop-correctness.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/03-pr-ci-review-loop-correctness.md deleted file mode 100644 index 10a7fae4..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/03-pr-ci-review-loop-correctness.md +++ /dev/null @@ -1,40 +0,0 @@ -# 03 — PR / CI / review loop correctness - -> Part of [`overview.md`](overview.md). Depends on: none (coordinate branch/push helpers with `02`). - -Unattended, the PR lifecycle must never lose a fix, merge a red head, or spin forever. These are the loop-integrity bugs. - -## Files to change -| `file:line` | Sev | Problem | Fix | -| --- | --- | --- | --- | -| `loop/work-loop.ts:746-783` (`autoMergeFlow`) | HIGH | prPerTask+autoMerge commits CI/Reviewer fixes locally (`--amend`, `orchestrator.ts:286`) but **never pushes** before `waitForChecks`/`mergePr` → fix never reaches remote; re-polls stale CI; merges un-updated head; `--amend` diverges local from pushed remote. | Route through `runFixSession`/`rebaseAndForcePush` (`loop/ci-fix.ts`); force-with-lease push before recheck/merge. Mirror the stage-machine path. | -| `github/github-client.ts:189-216` + `aggregateChecks:561-571` | MED-HIGH | `aggregateChecks` returns `success` on `rows.length===0`; `waitForChecks` checks before any delay → a fresh PR whose Actions haven't registered "succeeds" instantly and merges before CI runs. | Wait `CI_START_WAIT` before the first poll; treat empty rows as pending for a bounded grace. | -| `loop/resume-normalize.ts:30-38` × `loop/work-loop.ts:454-464` | MED | `normalizeResumeStatus` resets `blocked`→`pending`; `ctx.fixAttempts` is in-memory per run (#128). An unfixable red PR re-runs the full coding-tier CI-fix budget on **every** `aitm start` — no durable "needs human" stop. | Persist a durable attempt count / `human-needed` flag on `RunState` that survives resume; stop rescheduling once exceeded. | -| `github/github-client.ts:331-364, 366-399` | LOW-MED | `paginateReviewThreads` (`while(true)`) / `paginateThreadComments` (`while(cursor)`) advance only on server `endCursor`; a stuck-cursor `hasNextPage=true` loops forever. | Bound page count; break on non-advancing cursor. | -| `subagents/reviewer.ts:222-224` + `130-152` | HIGH | `kind:"fixed"` unconditionally `git add -A && commit`; empty diff → non-zero exit → `runBash` throws → `runReviewer` returns `{kind:'error'}` **discarding every resolution accumulated this pass**. Contradicts "one bad thread doesn't abort the rest." | Check `git diff --cached --quiet` before commit; downgrade empty to `replied`/`wontfix`. Catch per-thread. | -| `subagents/planner.ts:150-163` (`capGroups`) | MED | Drops overflow groups but never rewrites `dependsOn`; a kept group can `dependsOn` a dropped id → `PlanGraph.validate` throws "depends on unknown group", rejecting an otherwise-good plan. | After capping, strip/remap dangling `dependsOn` (redirect to merged last-kept group). | -| `plan/plan-graph.ts:25-40` (`blocked`/`isComplete`) | MED | A `pending` group whose dep becomes `blocked` is never `ready()` and never transitions to terminal → `isComplete()` can stay false forever. | Compute transitive block (any blocked/failed ancestor ⇒ terminal); feed `isComplete`/drive loop. | -| `orchestrator/orchestrator.ts:269` | MED | `stopWhen:[stepCountIs, hasToolCall('done')]` but there is no `done` tool → the explicit-completion signal can never fire; only `stepCountIs` backstops. | Register a `done`/`finish` tool, or remove the dead condition. | -| `orchestrator/orchestrator.ts:221-227, 269` (`resolveMaxSteps`) | LOW | `maxSessions` (a PR/session count) fed directly into `stepCountIs()` as the LLM step budget — conflates two concerns. | Separate `maxSteps` (loop cap) from any session count. | -| `loop/run-loop-adapter.ts:1231` (`addressReviews`) | LOW | Plain `git push` after Reviewer commit; if an earlier ci-fix force-pushed a rebase, this non-ff push fails and blocks the group. | Route through `rebaseAndForcePush` / handle non-ff. | -| `loop/constants.ts:12-15` | LOW | `CI_START_WAIT`/`CI_POLL_*`/`MERGE_STATE_WAIT` defined + tested but unused; `github-client.ts` uses its own `CHECKS_*`. Masks bug row 2. | Wire them (they fix row 2) or delete. | - -## Steps -1. Fix `autoMergeFlow` push gap first (data-loss) — reuse `rebaseAndForcePush`; align with the stage-machine path. -2. Add CI start-wait grace (wire `CI_START_WAIT`); empty-rows ⇒ pending until grace elapses. -3. Persist durable fix-attempt / human-needed state; `normalizeResumeStatus` must not resurrect a human-needed group. -4. Bound both paginators. -5. Reviewer: empty-index guard + per-thread error isolation. -6. Planner `capGroups`: remap dangling deps. PlanGraph: transitive-block terminality. -7. Orchestrator: real `done` tool (or drop dead condition) + separate `maxSteps` from `maxSessions`. -8. `addressReviews`: force-with-lease path. - -## Tests -- Integration (temp repo + stubbed `gh`): autoMerge path — a CI fix is visible on the remote branch before merge; merging a red head is impossible. Fresh PR with no checks yet waits the grace, doesn't insta-merge. An unfixable PR stops after `maxCiFixAttempts` and stays stopped across a simulated resume. Reviewer with one empty-diff "fixed" thread still returns the other resolutions. -- Unit: `capGroups` over a plan with cross-group deps → no dangling `dependsOn`, `PlanGraph.validate` passes. Transitively-blocked graph → `isComplete()` true. Paginator with a stuck cursor terminates. `resolveMaxSteps` decouples the two counts. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Every CI/review fix is pushed before recheck/merge; no red-head merge; no diverging `--amend`. -- No premature merge on an unregistered-CI PR; no forever-loop on pagination or transitive blocks; no infinite budget burn on an unfixable PR. -- Planner output with dropped overflow groups still validates. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/04-persistence-durability.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/04-persistence-durability.md deleted file mode 100644 index 6068c7d0..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/04-persistence-durability.md +++ /dev/null @@ -1,27 +0,0 @@ -# 04 — Persistence durability - -> Part of [`overview.md`](overview.md). Depends on: none. Coordinate `atomicWrite` changes with `02` (which routes more writers through it). - -The whole resume contract is "survive a crash and continue." The durability primitive and the reload path have gaps that break that promise. - -## Files to change -| `file:line` | Problem | Fix | -| --- | --- | --- | -| `fs/atomic-write.ts:21` | Data file is fsynced, but after `rename(tmp,path)` the **parent directory is never fsynced** → on power-loss the rename can vanish though the module promises crash-durability. | After rename, `open` parent dir + `fh.sync()`; tolerate EISDIR/EINVAL on platforms that reject dir-fsync. | -| `fs/atomic-write.ts:13-19` | If `writeFile`/`sync` throws, the orphan `${path}..tmp` is never removed (cleanup only in the rename catch) → stale temp files accumulate in the state dir. | Wrap write/sync in a try that `rm(tmp,{force:true})`s before rethrow. | -| `state/transcript-store.ts:93,98` | `record.messages as ModelMessage[]` validates only `Array.isArray`; a structurally-valid-but-wrong on-disk line is trusted and fed back into the resumed agent loop. | Validate each element against a Zod `ModelMessage` shape; drop/skip on mismatch. | -| `compaction/compactor.ts:80-91` | Empty summarizer output → `compact` returns `''` → `compaction-step.ts:113` emits a header-only summary, silently dropping the older prefix instead of passing it through. | Treat empty/whitespace summary as a compaction failure; return `undefined` (passthrough), like the other error paths. | - -## Steps -1. Harden `atomicWrite`: dir-fsync after rename + temp cleanup on write/sync failure. This is the base primitive — do it first; `02` depends on it being solid. -2. Add a minimal Zod `ModelMessage` guard in `transcript-store` reload; skip invalid lines with a warning (don't abort the whole transcript). -3. `compactor`: empty-summary ⇒ passthrough, not header-only replacement. - -## Tests -- Unit: `atomicWrite` leaves no `.tmp` after a simulated write failure; (where observable) dir-fsync path is exercised. Transcript reload with a corrupt/mistyped line skips it and keeps valid ones. Compactor returning empty text ⇒ messages pass through uncompacted, no context lost. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- A mid-write crash never loses a completed rename or leaves orphan temp files. -- A corrupt transcript line degrades to a skip+warn, never silently poisons the resumed loop. -- An empty summary never silently discards context. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/05-subagent-wiring.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/05-subagent-wiring.md deleted file mode 100644 index 1e24a2eb..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/05-subagent-wiring.md +++ /dev/null @@ -1,28 +0,0 @@ -# 05 — Subagent wiring integrity - -> Part of [`overview.md`](overview.md). Depends on: none. Coordinate the prompt envelope with `01` (untrusted-data framing). - -Every path that spawns a subagent must carry the same contract blocks. One path also silently drops config the editing needs, and one path reports edits that never happened. - -> **Design note (owner-clarified):** aitm does **not** verify before every commit — that's intentional, it's what makes it faster than a per-commit-gated tool; CI is the safety net after the PR, and self-review runs **before the PR opens**, not per-commit. So the fix below is **not** "add a verify gate to every commit." The invariant to protect is: the pre-PR verify/self-review + the Worker's `formatCommand`/`providerOptions`/`timeout`/`onUsage` config are carried on **whichever path does the editing** — don't let the orchestrator-tool path silently run a differently-configured Worker. Do not reintroduce per-commit verification. - -## Files to change -| `file:line` | Problem | Fix | -| --- | --- | --- | -| `orchestrator/subagent-tools.ts:98,120,143` | Planner/Worker/Reviewer tool wrappers build the system prompt by naive `styleContents + *_SYSTEM_PREFIX` concat, bypassing `buildRolePrompt` (`role-prompt.ts`) — the single place the mandatory contract blocks (faithful-reporting, autonomy), the `` block, and the step-budget reminder are injected. On the orchestrator-tool path subagents run **without any of them**. | Route all three through `buildRolePrompt`; the invariant then holds on every path (and the test the comment claims exists can enforce it). | -| `orchestrator/subagent-tools.ts:111-132` (`makeWorkerTool`) | `WorkerToolDeps` silently drops the Worker's `formatCommand`, `providerOptions` (web_search), `timeout`, `onUsage` → the orchestrator-tool Worker runs with a **different, degraded config** than the direct path (no format, no web_search, no usage accounting, no timeout). Not a missing verify gate (per-commit verify is intentionally off) — a config-drift bug between two spawn paths. | Thread `formatCommand`/`providerOptions`/`timeout`/`onUsage` through `WorkerToolDeps` so both paths configure the Worker identically. Leave per-commit verify off by design. | -| `subagents/worker.ts:483-486` (`runEditor`) | A `FileChange` is derived from the model's **first line of text**; no check the file actually changed on disk. A model that narrates without calling `writeFile`/`editFile` still yields a `changes` entry → poisons the PR body and can leave `stageAndCommit` with nothing to commit (throw). | Verify the path actually changed (stat / `git status`) before recording; treat "no diff" as an editor failure. | - -## Steps -1. Make `buildRolePrompt` the sole prompt builder; delete the ad-hoc concat in `subagent-tools`. Fold in the untrusted-data envelope from `01`. -2. Extend `WorkerToolDeps` to carry `formatCommand`/`providerOptions`/`timeout`/`onUsage`; wire them in `makeWorkerTool` so both spawn paths configure the Worker identically. Leave per-commit verify **off** (by design). -3. `runEditor`: confirm on-disk change before emitting a `FileChange`; fail the editor on no-op. - -## Tests -- Unit: a subagent built via the orchestrator-tool path contains the contract/``/step-budget blocks (assert on the composed prompt). `makeWorkerTool`-built Worker receives the same `formatCommand`/`providerOptions`/`timeout`/`onUsage` as the direct path (config parity). `runEditor` with a narrate-only model (no file write) records **no** change and fails, rather than reporting a phantom edit. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Contract + `` + step-budget blocks are present on **every** subagent-spawn path. -- Both spawn paths configure the Worker identically (no silent config drift); per-commit verify stays off by design. -- `changes` reflects real disk edits only. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/06-cli-tools-observability.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/06-cli-tools-observability.md deleted file mode 100644 index 807a9ebc..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/06-cli-tools-observability.md +++ /dev/null @@ -1,39 +0,0 @@ -# 06 — CLI, tools & observability hygiene - -> Part of [`overview.md`](overview.md). Depends on: none. Independent, parallelizable. - -Lower-severity correctness, SRP, and hygiene fixes. Secret-scrubbing and ANSI-sanitization matter more under autonomous operation (no human watching the terminal/logs). - -## Files to change -| `file:line` | Sev | Problem | Fix | -| --- | --- | --- | --- | -| `observability/step-progress.ts:149-154` (via `clip` :89-92) | MED | Model text + tool inputs written to stderr with only newline-collapse → raw ANSI/control seqs can spoof the cyan `[aitm …]` prefix / manipulate the terminal. | Strip C0/ANSI control sequences in `clip` before emit. | -| `observability/error-reporter.ts:35-52` | LOW | `Sentry.init` has no `beforeSend`/`ignoreErrors`; raw top-level throws (with possibly a token-bearing URL or resolved config value) go to GlitchTip. | Add `beforeSend` that redacts secret-shaped substrings. | -| `logger/logger.ts:70-73, 96-101` | LOW | `redactValue` redacts by **key name** only; a secret interpolated into `msg` or a `url:"…?api_key=…"` value logs in cleartext. | Also scrub value contents for secret patterns, at least in `msg`. | -| `cli/cli.ts:89-95` (`emit`) | MED | All `exit.message`s go to **stderr**, but code-0 statuses (`session-cap`, `awaiting-pr`, `commands.ts:681-687`) are user-facing status that belongs on stdout per the Logger contract. | Route code-0 messages to stdout; keep code 1/2 diagnostics on stderr. | -| `cli/commands.ts:864-947` (`defaultRunMergeFlow`), `runStart` | MED | ~80 lines of orchestration (subagent models, tool surfaces, conflict resolver, step-progress labels; usage-tracker + ModelLimits + style-distill) inline in the dispatch module — CLAUDE.md scopes CLI to arg-parsing + exit codes. | Move merge-flow + start wiring into a `loop`/adapter module behind the existing `runMergeFlow`/adapter seam. | -| `tools/web-fetch.ts:191` + `tools/web-search.ts:13` | MED | `Accept-Encoding: …, zstd`; Node 20 undici can't decode zstd → garbled body / unparseable DDG HTML (silent "no results"). | Drop `zstd` from advertised encodings (or don't hand-set Accept-Encoding). | -| `tools/web-search.ts:181` | LOW | `response.text()` with no size cap / content-type check (web-fetch caps via `readBodyCapped`). | Cap the body length like web-fetch. | -| `tools/web-fetch.ts:165-170` | LOW | Returns hardcoded `truncated:true` even when the body ended exactly on `maxChars` with nothing cut. | Return the locally-computed `truncated`. | -| `cli/args.ts:101-104, 149-163` | LOW | `--criteria`/`--style`/`--model`/`--branch` swallow a following `--flag` token as their value (unlike `--base-url`/`--api-key`). | Apply the same next-token flag-guard. | -| `cli/args.ts:164-168` | LOW | Only `--`-prefixed tokens are treated as unknown flags; `aitm start -x` accepts `-x` as the goal. | Reject a leading single `-` in positionals (or validate the goal). | -| `tools/github-thread-tool.ts:45-47` | LOW | `replyToThread(threadId, input.body ?? '')` posts an **empty** comment when `body` omitted (schema optional, "enforced in execute" — it isn't). | Return an error result when `replyToThread` has no non-empty `body`. | -| `config/config-writer.ts:21-36` (`KNOWN_KEYS`) | MED | Stale subset of loader keys — omits `maxCiFixAttempts`, `llmStepTimeoutMs`, `webSearch`, `formatCommand`, `verifyCommand`, `selfReview`, `resolveConflicts`, `allowForcePush`, `bashRules`, `mcpRoleAllowlist`, `mcpDeferToolsOver`, `prBodySections`, `hooks` → `config set selfReview false` throws "Unknown config key". | Derive the writer's key table and the loader's from **one** shared constant. | -| `openrouter/model-limits.ts:47-60` (`forModel`) | LOW | Concurrent `forModel` both see `!this.cache`, both call `client.listModels()` (guard re-checked only after `await`) → duplicate authenticated round-trip. | Memoize the in-flight `preload()` promise. | -| `mcp/tool-search.ts:174-199` (`guardDeferred`) | LOW | `baseExecute(input as never,…)` + function-shape cast + whole-object `as AnyTool` bypass typing at the deferred-tool boundary. | Narrow via the tool's own input schema instead of `as never`. | -| `tools/datetime.ts:41-47` | LOW | Returns a locale string (not ISO-8601); with no `timezone` arg, formats in host zone but reports `timezone:''`. | Return ISO-8601 + echo the resolved zone (`Intl.DateTimeFormat().resolvedOptions().timeZone`). | - -## Steps -1. Security-adjacent first: ANSI strip in `step-progress`, `beforeSend` scrub in error-reporter, value-scrub in logger. -2. Stream routing in `cli.emit`; shared config-key constant (fixes `config set` for documented keys). -3. SRP: lift `defaultRunMergeFlow`/`runStart` wiring behind the adapter seam. -4. Tool hygiene: drop zstd, cap web-search body, fix `truncated`, arg flag-guards, github-thread empty-reply, model-limits memo, tool-search narrowing, datetime output. - -## Tests -- Unit: `clip` strips ANSI. logger/error-reporter redact a secret embedded in `msg`/error. code-0 status → stdout, code≥1 → stderr. `config set selfReview false` succeeds; writer/loader key tables come from one source. arg parser rejects `--criteria --model`. web-search caps body; `truncated` correct on exact-boundary body. `forModel` concurrent calls → one `listModels`. github-thread empty reply → error. datetime → ISO + resolved zone. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- No ANSI/secret leakage to terminal, logs, or GlitchTip. -- CLI is arg-parsing + exit codes; status on the right stream; every documented config key is settable. -- Tool edge-cases (zstd, body caps, truncation flag, arg guards, empty reply, datetime) are correct. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/07-tests.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/07-tests.md deleted file mode 100644 index 30299897..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/07-tests.md +++ /dev/null @@ -1,32 +0,0 @@ -# 07 — Test coverage - -> Part of [`overview.md`](overview.md). Depends on: 01–06 (add tests alongside each fix; this slice is the completeness sweep). - -House rule: no test, no merge. Every fixed module keeps its paired `*.test.ts`; behavior that spans modules gets integration coverage against a **real temp git repo + stubbed/sandbox `gh`**. All tests pass under **both** `bun test` and `node --test`. - -## Coverage map (per slice) -| Slice | Unit (`*.test.ts` beside module) | Integration (`packages/aitm/test/integration/`) | -| --- | --- | --- | -| `01` | project-vs-global config trust strip; prototype-pollution reject; snapshot secret-redaction; `assertSafeUrl` redirect-chain; expand-import diamond/hostile budget; reviewer prompt fencing | hostile-repo fixture: run cannot redirect inference / spawn unapproved MCP | -| `02` | concurrent `recordAddressedThreads`/`begin`/`appendProgress` no-lost-update | two concurrent ready groups on shared checkout: no branch/tree/state cross-contamination; reviewer fix on correct branch; dirty tree cleaned | -| `03` | `capGroups` dep remap; transitive-block `isComplete`; paginator stuck-cursor terminates; `resolveMaxSteps` decoupling; reviewer empty-diff isolation | autoMerge pushes before merge; no red-head merge; fresh-PR grace; unfixable PR stops durably across resume | -| `04` | `atomicWrite` no-orphan-temp + dir-fsync; transcript corrupt-line skip; compactor empty-summary passthrough | crash-mid-write → resume reads last good state | -| `05` | orchestrator-path subagent carries contract/``/step-budget; `makeWorkerTool` config parity (format/providerOptions/timeout/usage); `runEditor` phantom-edit rejection | both spawn paths configure the Worker identically (no drift); per-commit verify stays off | -| `06` | ANSI strip; secret scrub in msg/error/log; stream routing; shared config-key table (`config set selfReview`); arg flag-guards; web-search cap; `truncated`; `forModel` single fetch; empty-reply error; datetime ISO | — | -| `08` | `render()` fences `data` slots, not `instruction` slots; each role template carries contract/``/step-budget; malicious `data` slot stays enveloped; per-role snapshot tests | subagent spawned via any path renders an equivalent prompt (no path-dependent drift) | - -## Steps -1. Add/extend the paired unit test with each fix as it lands (don't batch to the end). -2. Add the integration fixtures above; reuse `testing/temp-repo.ts` for real git repos; stub `gh` at the module boundary (no mocking `gh`/AI SDK inside integration paths per CLAUDE.md — use the sandbox account seam). -3. Run the full gate; fix portability drift so both runtimes stay green. - -## Tests / commands -- `bun test` -- `bun run test:node` (Node `--test` target — portability gate) -- `bun run typecheck` -- `bun run lint` - -## Done when -- Every module touched in 01–06 has a passing paired test asserting the fixed behavior. -- Integration fixtures cover the hostile-repo, concurrent-checkout, and PR/CI-loop data-loss scenarios. -- All four commands green under both runtimes. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/08-prompt-templating.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/08-prompt-templating.md deleted file mode 100644 index ce8f55ac..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/08-prompt-templating.md +++ /dev/null @@ -1,38 +0,0 @@ -# 08 — Prompt templating (single source, injected slots) - -> Part of [`overview.md`](overview.md). Depends on: informs `01` (untrusted-data envelope) and `05` (single prompt builder) — land this as the structural home they plug into, or land them first and refactor into this. Owner-requested. - -**Root cause behind 01 & 05:** prompt text is assembled ad-hoc at each call site by string concatenation, so mandatory pieces (contract blocks, ``, step-budget, untrusted-data fencing) get dropped on whichever path forgot them. Fix the *structure*: every subagent/orchestrator prompt is a **named template with typed slots**; values are injected in one place (harness or top agent), never hand-concatenated at the call site. - -**Guiding principle (owner):** aitm has two kinds of logic — **code / harness** (deterministic: orchestration, git, gh, state, value computation) and **agent / logic-eng** (the LLM reasoning encoded in prompts). Keep them separate and each reusable. The template boundary *is* that seam: harness code computes and injects slot values; the template holds the agent-facing reasoning. Neither reaches into the other — no business logic in prompt strings, no prompt text hand-built in harness control flow. Good, reusable modules on both sides of the seam. - -## Current scattered sites (consolidate these) -| `file:line` | What it builds today | -| --- | --- | -| `subagents/role-prompt.ts` (`buildRolePrompt`) | The intended single builder (contract + `` + step-budget). Make it the template engine's front door. | -| `orchestrator/subagent-tools.ts:98,120,143` | Ad-hoc `styleContents + *_SYSTEM_PREFIX` concat, bypasses the above (finding 05). | -| `subagents/reviewer.ts:201` (`buildThreadPrompt`) | Inline concat of untrusted comment bodies (finding 01). | -| `subagents/specialist-registry.ts:149` (`composeSpecialistGuidance`) | Verbatim append of repo `.claude/agents/*.md` (finding 01). | -| `subagents/{planner,worker,explore}.ts` `*_SYSTEM_PREFIX` consts | Role prefixes scattered as string consts. | -| `orchestrator/orchestrator.ts` system prompt | Top-level prompt assembly. | - -## Design -- One `prompts/` module (SRP): named templates + a typed `render(templateName, slots)` that returns the final string. Named exports, kebab-case files, PascalCase slot types. -- **Slot kinds** carry trust: a `data`/untrusted slot is auto-wrapped in the fenced envelope from `01` (`…`, `…`) with the "data not instructions" directive; an `instruction` slot is verbatim. The template author can't forget to fence — the slot type does it. -- **Injection boundary:** the top agent / harness supplies slot values (goal, style digest, ``, step budget, group, rolling context, comment bodies); templates never read globals or reach into config. This makes prompts testable in isolation and keeps the contract blocks non-optional (they're baked into the template, not a caller's responsibility). -- No premature abstraction: start by extracting the prompts that already exist at the 6 sites above into templates — do not invent templates for prompts that don't exist yet. Inline first, template on the real second caller (which `buildRolePrompt` already is). - -## Steps -1. Create the `prompts/` module: a template registry + `render()` with typed `instruction` vs `data` (auto-fenced) slots. -2. Move the role prefixes, contract blocks, ``, and step-budget reminder into role templates behind `buildRolePrompt`; `buildRolePrompt` calls `render()`. -3. Convert the 6 sites to `render(...)`; delete the ad-hoc concatenation. Orchestrator-tool path (05) and reviewer/specialist path (01) now go through templates by construction. -4. Snapshot-test each rendered template with representative slots so prompt drift is caught in review. - -## Tests -- Unit: `render()` fences every `data` slot and never fences an `instruction` slot. Each role template rendered with fixture slots contains the contract/``/step-budget blocks (property, not string-match, where possible). Rendering with a malicious `data` slot (embedded "ignore previous instructions") keeps it inside the envelope. Snapshot tests for planner/worker/reviewer/orchestrator/explore system prompts. -- Commands: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- No subagent/orchestrator prompt is built by string concatenation at a call site — all go through `render()`. -- Untrusted slots are fenced by construction (can't be forgotten); contract blocks are baked into templates, not caller-supplied. -- Slot values are injected at one boundary (top agent/harness); templates read no globals. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/overview.md b/docs/plans/2026/07/17/101-aitm-audit-remediation/overview.md deleted file mode 100644 index 85764a5c..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/overview.md +++ /dev/null @@ -1,35 +0,0 @@ -# aitm Audit Remediation — hardening for autonomous parallel-team execution - -## Goal -Fix the real bugs a 5-agent parallel deep-dive found across `aitm`. Priority order is driven by the product stance: **non-interactive, autonomous, multi-agent team sharing one in-place checkout (no worktrees), driving GitHub PRs / comments / CI fixes** with no human in the loop to catch a wrong turn. That stance turns three finding-classes from "edge case" into "must-fix": (A) an arbitrary target repo is **hostile input**, (B) parallel agents share one working tree + one `.ai-task-master/` state dir with **no filesystem isolation**, (C) the PR/CI/review loop must **never lose a fix or spin forever** unattended. - -## Context -- Stack: `packages/aitm` — TS strict, ESM, `ai` package `experimental_Agent` + subagents-as-tools; OpenRouter-only via `Credentials`; `gh`/`git` via execa (array form). Runs unchanged on Bun + Node≥20 + Deno≥1.40. -- **Clean, do not touch**: no command-injection (every `gh`/`git` call is execa argv, GraphQL via `-f`/`-F`), no `Bun.*` shipped APIs, no `any`/`as unknown as` in shipped code (two narrow cast escapes noted in `06`). Branch sanitization (`workspace/branch-name.ts`), `SAFE_GROUP_ID` gate, cycle detection in `PlanGraph.validate`, usage-tracker cost math, `run-step` counter, `expand-imports` containment (realpath/symlink/`..` refusal) all verified sound. -- **Architecture principle (owner):** two kinds of logic — **code/harness** (deterministic: orchestration, git, gh, state) and **agent/logic-eng** (LLM reasoning in prompts). Keep them separate, reusable, each testable alone. Slice `08` makes the prompt-template boundary that seam; SRP fixes (`06` CLI, `05` wiring) keep harness logic out of the wrong layer. -- Trust model gap is the spine of slice `01`: `.ai-task-master/config.json` + `./.mcp.json` are repo-shippable yet already partly treated as untrusted (`hooks` stripped at `config-loader.ts:165`) — the same gate is missing on `baseURL`/`apiKey`/`mcpServers`. -- Reference patterns: `config-loader.ts:165` (existing trust strip for `hooks` — extend it), `state/state-store.ts:52` (correct serialized read-modify-write — copy it), `fs/atomic-write.ts` (temp+rename — the durability primitive to harden), `subagents/role-prompt.ts` `buildRolePrompt` (single place contract blocks are injected — all paths must route through it), `loop/ci-fix.ts` `rebaseAndForcePush` (the push-before-recheck primitive `autoMergeFlow` skips). -- **Review model (owner-clarified)**: aitm's own review runs **before the PR opens** (self-review is the primary quality gate). Post-PR review comments come from whatever the target repo runs (CodeRabbit etc.) — that path is optional/repo-dependent, not the core loop, so don't over-invest in it. **But** it's exactly why the prompt-injection fence in slice `01` (`reviewer.ts:201`) still ships: a third-party bot's comment body feeds a subagent holding `bash`/`writeFile`/`editFile`. Fence it; don't build it out. - -## Plan files (execute in order) -1. [`01-untrusted-repo-trust-boundary.md`](01-untrusted-repo-trust-boundary.md) — treat target-repo config/MCP/comments/imports as hostile: config-key redirect, arbitrary MCP spawn, prototype pollution, SSRF-redirect, expand-import DoS, prompt-injection. -2. [`02-parallel-team-shared-checkout.md`](02-parallel-team-shared-checkout.md) — safe concurrency on one shared checkout + one state dir: branch-before-edit, clean-tree gate, single-writer serialization, atomic/serialized state writes. -3. [`03-pr-ci-review-loop-correctness.md`](03-pr-ci-review-loop-correctness.md) — no lost fixes, no premature merge, no infinite/duplicate loops: autoMergeFlow push gap, CI empty-rows grace, durable attempt cap, pagination bounds, reviewer commit-abort, dangling deps, terminal-blocked, dead stop-condition. -4. [`04-persistence-durability.md`](04-persistence-durability.md) — crash-durable writes: dir fsync, temp-file leak, validated transcript reload, empty-summary passthrough. -5. [`05-subagent-wiring.md`](05-subagent-wiring.md) — every subagent path carries its contract + verify gate; changes reflect real disk edits. -6. [`06-cli-tools-observability.md`](06-cli-tools-observability.md) — stream correctness, secret scrubbing, ANSI sanitization, arg guards, config-key parity, misc tool hygiene. -7. [`08-prompt-templating.md`](08-prompt-templating.md) — structural: prompts as named templates with typed (auto-fenced) slots; the harness/code ↔ agent/logic seam. Underpins `01` + `05`. (Numbered `08`; execute before or alongside 01/05.) -8. [`07-tests.md`](07-tests.md) — paired `*.test.ts` + integration coverage for every fix; `bun test` + `node --test` both green. - -## Done when -- A hostile target repo cannot redirect inference, exfiltrate the API key, spawn an unapproved process, poison a prototype, drive an SSRF, blow up memory, or inject instructions into a tool-holding subagent. -- Two ready groups running concurrently on the shared checkout never clobber each other's branch, working tree, or state files; every fix is committed to the correct branch. -- Every CI/review fix reaches the remote before recheck/merge; no run merges a still-red head, re-burns budget on an unfixable PR forever, or loops on pagination. -- State/transcript writes survive a mid-write crash; corrupt state degrades loudly, not silently. -- `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint` all green. - -## Risks / open questions -- **Concurrency policy is a real design fork** (slice `02`): either (a) serialize ready groups to one-at-a-time on the shared checkout, or (b) restore per-group isolation. Worktrees were deliberately removed (commit 7572a96), so (a) is the presumed direction — but it caps the "parallel team" to parallel *planning/review*, serial *editing*. **Confirm with owner before implementing `02`.** The rest of `02` (atomic state writes) is needed either way. -- **Env-vs-file credential precedence** (finding auth#6): the header comment says `env` outranks file; the code puts `env` lowest. Slice `01` assumes user-owned config wins and env is a fallback — but the doc/code contradiction must be resolved deliberately, not silently. -- Slices `01`, `03`, `04`, `06` are independent and parallelizable across executors; `02` gates on the concurrency-policy decision; `07` follows all. -- Nothing here pulls in out-of-scope surfaces (mailbox, aitm-as-MCP-server, webhooks, Docker). If a fix seems to, stop and surface it. diff --git a/docs/plans/2026/07/17/101-aitm-audit-remediation/status.yml b/docs/plans/2026/07/17/101-aitm-audit-remediation/status.yml deleted file mode 100644 index 0d2595c3..00000000 --- a/docs/plans/2026/07/17/101-aitm-audit-remediation/status.yml +++ /dev/null @@ -1,36 +0,0 @@ -plan: 101-aitm-audit-remediation -title: aitm Audit Remediation — hardening for autonomous parallel-team execution -status: not_started # not_started | in_progress | blocked | complete | superseded -created_by: plan-author -worked_by: "" -owner: plan-owner -percent: 0 -current_focus: "" # start with 01 (trust boundary) + 04 (durability); 02 gates on concurrency-policy decision -slices: - - file: 01-untrusted-repo-trust-boundary.md - status: not_started - percent: 0 - - file: 02-parallel-team-shared-checkout.md - status: not_started - percent: 0 - - file: 03-pr-ci-review-loop-correctness.md - status: not_started - percent: 0 - - file: 04-persistence-durability.md - status: not_started - percent: 0 - - file: 05-subagent-wiring.md - status: not_started - percent: 0 - - file: 06-cli-tools-observability.md - status: not_started - percent: 0 - - file: 08-prompt-templating.md - status: not_started - percent: 0 - - file: 07-tests.md - status: not_started - percent: 0 -evidence: [] -notes: "Findings from a 5-agent parallel deep-dive audit (2026-07-17). Clean: no command-injection (execa argv throughout), no Bun-only shipped APIs, no any/as-unknown-as. Product stance drives severity: non-interactive autonomous multi-agent team on ONE shared in-place checkout + one .ai-task-master state dir (worktrees removed, commit 7572a96), driving GH PRs/CI. OPEN DECISION before 02: serialize editing on the shared checkout (assumed) vs restore per-group isolation. Owner-clarified review model: self-review + verify run BEFORE the PR opens, NOT per-commit (intentional, for speed; CI is the post-PR net). Post-PR review comments (CodeRabbit etc.) are optional/repo-dependent — do not build out, but DO keep the prompt-injection fence (01) since a third-party bot's comment feeds a bash/write-tool subagent. Do NOT reintroduce per-commit verification in slice 05. Architecture principle: two kinds of logic — code/harness (deterministic) vs agent/logic-eng (prompts); keep separate + reusable; slice 08 makes the prompt-template boundary that seam and underpins 01+05." -last_updated: 2026-07-17 diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/01-pr-lifecycle-idempotency.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/01-pr-lifecycle-idempotency.md deleted file mode 100644 index b1078adc..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/01-pr-lifecycle-idempotency.md +++ /dev/null @@ -1,26 +0,0 @@ -# 01 — PR lifecycle idempotency - -> Part of [`overview.md`](overview.md). Depends on: none. - -## Files to change -- `packages/aitm/src/loop/run-loop-adapter.ts:1031-1046` — `openPr` bridge: check-before-create. -- `packages/aitm/src/github/github-client.ts:165-201` — `createPr` reuse path. -- `packages/aitm/src/loop/stage-handlers.ts:98-106` — `handlePrOpen` resume semantics. -- `packages/aitm/src/loop/work-loop.ts:338-343,604-617,717-725,887-895` — awaiting-pr outcome, partial-group terminal status, prPerTask PR-open. -- `packages/aitm/src/cli/args.ts` — reject bad flag combo (if that option chosen). - -## Steps -1. **Idempotent PR open** (durability #1, high). `openPr`/`createPr`: call existing `getPrForBranch(head)` first; if a PR already exists for the branch, adopt it (return its number) instead of `gh pr create`. Kill-after-create/before-persist then resumes cleanly instead of blocking the group. -2. **prPerTask + no-automerge** (logic #2). `processGroup` (`work-loop.ts:396,400-427`): with `canResetToBase` false, task ≥2 re-creates a PR from the same head branch → GitHub rejects → group blocked. Per owner decision (overview risks): either reject the combo in `args.ts` up front, or open one PR after the last task (group mode path). Step 1 makes the crash harmless either way; this fixes the by-design double-create. -3. **awaiting-pr under autoMerge** (logic #3). `finalResult` (`work-loop.ts:887-895`): surface `awaiting-pr` outcomes as non-success even when `autoMerge` — a `StateWriteAfterSuccess` at pr-open must not exit 0 with a dangling unmerged PR. -4. **Partial group ≠ `merged`-and-forgotten** (logic #4 / durability #3). `workTasks` (`work-loop.ts:604-617`): a group with any task left `done:false` must not land in terminal `merged` with exit 0. Per owner decision: mark blocked, introduce `partial`, or reschedule remaining tasks. Minimum bar: run result reflects dropped work (non-success or explicit partial report). - -## Tests -- Unit: `work-loop.test.ts` — finalResult awaiting-pr × autoMerge matrix; workTasks partial-group terminal status. -- Unit: `github-client.test.ts` — createPr adopts existing PR (mock runCmd). -- Integration (`packages/aitm/test/integration/`): extend `crash-durability.test.ts` — kill between pr-create and state persist, resume, assert single PR + group completes. prPerTask+no-automerge 2-task group asserts chosen behavior. -- `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Crash at the pr-open boundary resumes to exactly one PR; no recoverable state reaches `blocked`. -- No exit-0 run with a dangling PR or an un-done task in a merged group. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/02-signal-cancellation-cleanup.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/02-signal-cancellation-cleanup.md deleted file mode 100644 index 9852cdb5..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/02-signal-cancellation-cleanup.md +++ /dev/null @@ -1,25 +0,0 @@ -# 02 — Signal handling + cancellation cleanup (RAII) - -> Part of [`overview.md`](overview.md). Depends on: none. - -## Files to change -- `packages/aitm/src/cli/cli.ts:12-22,132-146` — `MainCtx` gains `signal`; entrypoint registers handlers. -- `packages/aitm/src/cli/cli.ts:63-71` — `buildMergePrCtx` threads `ctx.signal` (consumer at `commands.ts:537` already exists). -- `packages/aitm/src/loop/run-loop-adapter.ts:596-600` — MCP close must not rely on an async `finally` surviving default signal termination. -- `packages/aitm/src/subagents/worker.ts:288,445` — editor fanout shared abort. -- `packages/aitm/src/testing/temp-repo.ts:15-31` — cleanup on setup throw. - -## Steps -1. **Wire the dead cancellation path** (cleanup #1, high). Entrypoint: create one `AbortController`; `process.on('SIGINT')`/`('SIGTERM')` → `controller.abort()`. Thread `controller.signal` through `MainCtx` → `buildMergePrCtx` → start/merge flows. Today `signal` is always `undefined` from the real binary; `take-over-flow.ts:174,279` `{ kind: 'cancelled' }` is unreachable. -2. **Cleanup on abort**: on abort, explicitly `await mcp.close()` (child processes from `Experimental_StdioMCPTransport`, `mcp-client.ts:157`) before exit — Node's default SIGINT termination skips the `finally` at `run-loop-adapter.ts:597` and orphans MCP servers. Second signal = immediate exit (escape hatch). -3. **Editor fanout teardown** (cleanup #2). `runManifestAndEdit` (`worker.ts:288`): one `AbortController` per fanout; pass `signal` to each `runEditor` `generateText` (`worker.ts:445`); `abort()` when any editor rejects so sibling LLM requests stop burning tokens. Also accept the outer signal from step 1. -4. **Temp-repo leak** (cleanup #3, test-only). `makeTempRepo`: wrap post-`mkdtemp` setup in try/catch → `rm(path, { recursive: true, force: true })` + rethrow. - -## Tests -- Unit: `cli.test.ts` — signal present in ctx; abort propagates to flows. `worker.test.ts` — one editor rejecting aborts siblings (mock model observing signal). `temp-repo.test.ts` — failing `git init` (bad PATH stub) leaves no dir. -- Integration: spawn `aitm start` in temp repo, SIGINT mid-run, assert exit path runs MCP close (observable via a stub MCP server) and `{ kind: 'cancelled' }` surfaces. -- Portability: `process.on` signal names identical across Bun/Node/Deno — no `Bun.*`. - -## Done when -- Ctrl-C: MCP children reaped, in-flight work aborted, cancelled result reported; no orphan processes. -- Failed editor cancels its siblings. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/03-review-loop-idempotency.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/03-review-loop-idempotency.md deleted file mode 100644 index fbc23579..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/03-review-loop-idempotency.md +++ /dev/null @@ -1,24 +0,0 @@ -# 03 — Review-loop + resume idempotency - -> Part of [`overview.md`](overview.md). Depends on: none (pairs well with 01). - -## Files to change -- `packages/aitm/src/subagents/reviewer.ts:150-158,241-279` — partial-resolution return on mid-pass throw. -- `packages/aitm/src/loop/stage-handlers.ts:155-166,181-185` — addressed-thread recording order / reviewer skip-if-replied. -- `packages/aitm/src/state/pr-context-store.ts:113-128` — `recordAddressedThreads` intent-first option. -- `packages/aitm/src/loop/work-loop.ts:288,636-656,746-760,865-874` — sessionCount timing; task-commit resume dedup. - -## Steps -1. **Keep partial resolutions** (durability #4). `runReviewer`: a `commitFix` throw (`reviewer.ts:260-263`) currently discards resolutions already replied/resolved on GitHub → next run re-feeds those threads → duplicate replies + commits. Return resolutions gathered before the throw (the `reviewer.ts:270` empty-index comment already intends this) so `recordAddressedThreads` records them. -2. **Close the record gap** (durability #5). Side effects land before the dedup record; crash between = re-processing on resume. Either record intent-to-address before acting, or (simpler, self-healing) make the reviewer skip threads already carrying a bot reply — check thread comments in `freshThreads` (`stage-handlers.ts:181-185`). Prefer the skip: it also heals step 1's residue. -3. **sessionCount per-group** (durability #6). `run()` (`work-loop.ts:288`) persists `incrementSessionCount(batch.length)` before the batch runs; crash inflates the count → premature `session-cap` block on resume. Increment as each group actually starts. -4. **Duplicate task commit on resume** (durability #7). Crash after Worker commit, before `completeTask` persists (`work-loop.ts:746-760`): re-run adds a second commit for the same task on the reused branch. Detect the task's commit already on the branch (trailer or message marker via `git log`) and skip straight to `completeTask`. Harmless under squash-merge; wrong under merge/rebase methods. - -## Tests -- Unit: `reviewer.test.ts` — commitFix throw at thread N returns resolutions 1..N-1. `stage-handlers.test.ts` — already-replied thread filtered. `work-loop.test.ts` — sessionCount increments per started group. -- Integration: extend `resume-flow.test.ts` / `crash-durability.test.ts` — kill after reviewer reply before record → resume produces no duplicate reply; kill after task commit before completeTask → resume produces no duplicate commit (`git log` count). -- `bun test`, `bun run test:node`. - -## Done when -- Re-running after any crash in the review/commit path produces zero duplicate GitHub replies, resolutions, or commits. -- Persisted sessionCount never exceeds groups actually started. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/04-gh-client-parsing-caching.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/04-gh-client-parsing-caching.md deleted file mode 100644 index 717f25ea..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/04-gh-client-parsing-caching.md +++ /dev/null @@ -1,24 +0,0 @@ -# 04 — GitHubClient parsing + caching - -> Part of [`overview.md`](overview.md). Depends on: none. - -## Files to change -- `packages/aitm/src/github/github-client.ts:137,162,384,430,488` — unguarded `JSON.parse`. -- `packages/aitm/src/github/github-client.ts:481` — `repoMeta()` memoization. -- `packages/aitm/src/loop/work-loop.ts:302` + `packages/aitm/src/loop/run-loop-adapter.ts` — `defaultBranch()` resolved once. -- Rethrow boundaries: `work-loop.ts:344,703,1255`, `run-loop-adapter.ts:224,397`, `github-client.ts` throws — `{ cause }`. - -## Steps -1. **Guard the five parses** (durability #2). `defaultBranch`, `getPrForBranch`, `paginateReviewThreads`, `paginateThreadComments`, `repoMeta` do bare `JSON.parse(r.stdout)`; `gh` can emit non-JSON on exit 0 (notices, proxy HTML, truncation) → raw `SyntaxError` aborts the run anonymously. Route through existing `safeJson` (`github-client.ts:541-547`) + `safeParse`; on failure throw an error naming the command with stdout excerpt and `cause`. Follow the already-guarded `getFailedCiLogs`/`tryParseChecks` pattern. -2. **Memoize `repoMeta()`** (N+1 #1, high). Owner/name are per-run constants, yet each `listUnresolvedThreads` (`:329`) / `getFailedCiLogs` (`:261`) call spawns `gh repo view` — 1-2× per poll tick in take-over (`take-over-flow.ts:199`, ≤30 iterations) and per stage transition (`stage-handlers.ts:182`). Cache first resolved `{owner,name}` on the instance. -3. **`defaultBranch()` once per run** (N+1 #2). `runGroup` re-derives it per group (`work-loop.ts:302`); `merge-flow-adapter.ts:22` already resolves once and threads `baseBranch` — do the same in `runLoopAdapter`, or memoize on the client alongside step 2. -4. **Preserve `cause`** (durability cross-cutting). At the listed rethrow boundaries replace `err instanceof Error ? err.message : String(err)` collapses with `new Error(msg, { cause: err })`. Pattern exists at `StateWriteAfterSuccess` (`work-loop.ts:248-257`). Sweep, don't refactor — same messages, add cause. - -## Tests -- Unit: `github-client.test.ts` — mock runCmd returning exit-0 non-JSON for each of the five → descriptive error naming the command, `cause` set; repoMeta/defaultBranch invoked twice spawn one subprocess (call-count spy). -- Unit: cause preserved through one representative boundary per file. -- `bun test`, `bun run test:node`, `bun run lint`. - -## Done when -- Zero bare `JSON.parse` on subprocess stdout in `github-client.ts`. -- One `gh repo view` per run regardless of poll ticks/groups. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/05-state-efficiency-durability.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/05-state-efficiency-durability.md deleted file mode 100644 index e7b726b3..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/05-state-efficiency-durability.md +++ /dev/null @@ -1,27 +0,0 @@ -# 05 — State efficiency + durability polish - -> Part of [`overview.md`](overview.md). Depends on: none. - -## Files to change -- `packages/aitm/src/state/state-store.ts:55,58-66` — in-memory cache, drop double validate. -- `packages/aitm/src/loop/run-loop-adapter.ts:545-546` + `packages/aitm/src/plan/plan-graph.ts:10-13,71-108` — validate-once graph. -- `packages/aitm/src/state/pr-context-store.ts:58,82,88` — atomic writes. -- `packages/aitm/src/fs/atomic-write.ts:34,43-53` — post-rename dir-fsync severity. -- `packages/aitm/src/state/transcript-store.ts:153-164` — persistent-failure signal. - -## Steps -1. **StateStore cached RMW** (N+1 #3). `update()` re-reads `state.json` from disk + runs `RunStateSchema.parse` twice per call, driven per stage transition / task / batch. Store is the sole writer and serialized via `updateChain`: cache last-written `RunState`, mutate from it under the chain, keep the single post-mutation `parseState`, drop the disk re-read (first `update` after construction still reads). -2. **PlanGraph validate-once** (N+1 #4). `ready`/`isComplete` closures rebuild `new PlanGraph([...liveGroups])` per while-tick, re-running full DFS cycle/dangling validation on immutable topology. Validate once at plan acceptance; per-tick calls read live statuses from one graph (or a rebuild that skips `validate()`). -3. **pr-context atomic writes** (durability #9). `saveCiFailures`/`saveComments` use bare `writeFile`, unlike the rest of `.ai-task-master/`. Route through `fs/atomic-write.ts`. -4. **Post-rename fsync downgrade** (durability #10). `fsyncParentDir` failure after a successful `rename` throws, reporting a durable write as failed. Warn instead of throw for the post-rename dir-fsync only; pre-rename behavior unchanged. -5. **Transcript-failure signal** (durability #8). `FileRecorder.append` swallows all errors by design; after N (e.g. 3) consecutive failures set a persistent flag the resume path can read, so `findResumable` can distinguish "truncated by crash" from "recording died mid-run". Keep the never-throw contract. -6. Optional, owner-gated (see overview risks): memoryIndex per-group caching with write-invalidation (`run-loop-adapter.ts:186-191,938,1061,1126`). Skip if freshness wins. - -## Tests -- Unit: `state-store.test.ts` — read-count spy: N updates = 1 initial read; external-corruption test updated to match cached contract. `plan-graph.test.ts` — validate called once (spy) across ticks. `pr-context-store.test.ts` — tmp+rename observable (no partial file on injected crash). `atomic-write.test.ts` — post-rename fsync failure warns, resolves. `transcript-store.test.ts` — 3 consecutive append failures → flag set. -- Integration: `crash-durability.test.ts` still green (contract unchanged where it matters). -- `bun test`, `bun run test:node`. - -## Done when -- One disk read + one schema validation per state update after warm-up; crash tests unchanged-green. -- No bare `writeFile` under `.ai-task-master/`. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/06-prompt-compression-fencing.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/06-prompt-compression-fencing.md deleted file mode 100644 index af874cde..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/06-prompt-compression-fencing.md +++ /dev/null @@ -1,31 +0,0 @@ -# 06 — Prompt compression + injected-value fencing - -> Part of [`overview.md`](overview.md). Depends on: none. Reconcile with `../../../17/101-aitm-audit-remediation/08-prompt-templating.md` (same seam; don't duplicate). - -Design intent (owner): every runtime value reaches a prompt **via the builder with typed slots** — `buildRolePrompt`/`render`/`slots.ts` is the gold standard. Audit verdict: system prompts already comply; the gaps are the first-user-message context block and token duplication. - -Standards refs: `gold-standards-in-ai/docs/writing-for-agents/compressed-config.md`, `claude-code-bible/docs/11-compressed-config.md` (fragments, one rule per line, agent prompt <50 lines, per-spawn cost), `claude-task-master/src/claude_task_master/core/prompts_base.py` (PromptBuilder `include_if`). - -## Files to change -- `packages/aitm/src/loop/run-loop-adapter.ts:334-341,650,748,983,1019` (+ `695/699,903/904,1092/1095`) — claudeMd fence/cap; style duplication. -- `packages/aitm/src/observability/system-reminder.ts:32-34,115-122` — verbatim `wrapReminder` sections. -- `packages/aitm/src/subagents/worker.ts:392-416,448-453,505-514` — editor frame, manifest interpolation caps. -- `packages/aitm/src/subagents/prompt-blocks.ts:62-88`, `role-guidance.ts:32-95` — contract/role prose. -- `packages/aitm/src/orchestrator/orchestrator.ts:333-346,389-403` — commit/PR prompt duplication. - -## Steps -1. **Fence + cap claudeMd** (high). Target repo's `CLAUDE.md` is injected verbatim into the `` block — a literal `` inside it (docs, pasted logs, hostile repo) breaks out of the envelope. Route external `ContextSection` bodies through the same defuse as `slots.ts:62-65` `defuseEnvelopeTags` (or JSON-escape like `prompt-blocks.ts:119-133` `memoryIndexBlock`). Cap `styleContents` before injection — the ~600-word bound only exists inside the distiller (`coding-style.ts:37-41`); the raw fallback (`run-loop-adapter.ts:650,748`) is unbounded. -2. **Style digest once per call** (high). Same `style` string sent as system-prompt block AND as `harnessContextBlock` claudeMd section — every planner/worker/reviewer/self-review/CI-fix call pays it twice. Keep the system block (cacheable); drop the context-section copy at all listed call sites. -3. **Slim the editor leaf**. `runEditor` ships full contract stack + style digest per file, ×N parallel per manifest. Leaf is "one file, can't see plan" — follow `explore.ts:53` lean-leaf pattern. Trim conservatively (editors write code — keep style essentials); measure tokens before/after. -4. **Cap manifest interpolations**. `group.title`/`task.text`/`subtasks`/`rollingContext`/`file.purpose` interpolated raw, uncapped; `rollingContext` grows across groups. Apply slice-caps matching `VERIFY_TAIL_MAX` discipline (`worker.ts:201,640-645`). -5. **Orchestrator commit/PR prompts**. Both prepend full `buildSystemPrompt()` into the *user* prompt per group. Move to `system` field or trim to delivery facts. -6. **Compress contract prose** (soft). Rewrite `HARNESS_/COMMUNICATION_/AUTONOMY_CONTRACT_TEXT` + Worker/Editor role prose as fragments per the standards refs. Behavior-sensitive — A/B on a real run before adopting. - -## Tests -- Unit: `system-reminder.test.ts` — body containing `` cannot close the envelope. `run-loop-adapter.test.ts` — style appears exactly once per built prompt; raw-fallback capped. `worker.test.ts` — oversized rollingContext truncated at cap. -- Token check: log prompt char counts before/after on `e2e-smoke.ts`; record the delta in the PR. -- `bun test`, `bun run test:node`. - -## Done when -- No unfenced/uncapped external content in any prompt path; style digest single-sourced. -- Measured per-call prompt-size reduction reported. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/07-cli-flag-correctness.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/07-cli-flag-correctness.md deleted file mode 100644 index 79ca8e39..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/07-cli-flag-correctness.md +++ /dev/null @@ -1,20 +0,0 @@ -# 07 — CLI flag correctness - -> Part of [`overview.md`](overview.md). Depends on: none. - -## Files to change -- `packages/aitm/src/cli/args.ts:233-236` — `--no-resume` parse (kept or dropped). -- `packages/aitm/src/cli/commands.ts:469,528` — honor `resume: false` in `runMergePr`. -- `packages/aitm/src/cli/cli.ts:46-48` + `args.ts` HELP returns — usage-error exit code. - -## Steps -1. **Make `--no-resume` real** (logic #1). Parsed and forwarded (`commands.ts:528`) but never read — `runMergePr` always uses persisted `currentPr` (`commands.ts:469`), so stale state drives the wrong PR to merge. When `resume: false`: skip persisted `currentPr`, force the synthesize-takeover path from the current branch. (Alternative — drop the flag — rejected: the stale-state escape hatch is the point.) -2. **Parse errors exit nonzero** (logic #5). Malformed input (`--max-prs abc`, unknown flag, missing goal) returns HELP → exit 0, masking CI-wrapper typos. Split `help` (explicitly requested, exit 0) from `usage-error` (print help to stderr, exit 2). Respects the `Logger` stdout/stderr split (status → stdout, diagnostics → stderr). - -## Tests -- Unit: `args.test.ts` — `--no-resume` sets `resume:false`; malformed inputs yield `usage-error`. `commands.test.ts` — `resume:false` ignores persisted `currentPr` (stub state with stale PR). `cli.test.ts` — exit codes: help 0, usage-error 2. -- `bun test`, `bun run test:node`. - -## Done when -- `aitm merge-pr --no-resume` with stale `state.json` targets the current branch's PR, not the persisted one. -- `aitm start --max-prs abc "goal"` exits 2. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/08-tests.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/08-tests.md deleted file mode 100644 index 9ed49224..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/08-tests.md +++ /dev/null @@ -1,17 +0,0 @@ -# 08 — Tests + gates - -> Part of [`overview.md`](overview.md). Depends on: 01–07 (run last; per-slice tests land with their slice — this closes gaps). - -## Files to change -- Paired `*.test.ts` beside every touched module (house rule: no test, no merge) — verify each slice actually added them. -- `packages/aitm/test/integration/crash-durability.test.ts`, `resume-flow.test.ts` — extended crash matrix. - -## Steps -1. Audit slices 01–07 for the paired-test rule: every changed `src/**/*.ts` has a sibling `*.test.ts` exercising the change (not just existing green). -2. Consolidate the crash matrix in integration tests — kill points: after `gh pr create` / after reviewer reply / after task commit, each before its state persist; resume asserts no duplicate PR/reply/commit and no wrongly-blocked group. Real temp git repo + real `gh` sandbox (no mocking, per house rules). -3. Signal integration: SIGINT mid-run (slice 02) — MCP children reaped, cancelled result surfaced. -4. Full gates both runtimes: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. No `Bun.*` in shipped code introduced by any slice (grep). -5. Record the slice-06 prompt-size delta (e2e-smoke char counts) in the closing PR. - -## Done when -- All gates green on Bun and Node; crash/signal matrix passes; every touched module has paired-test coverage of its fix. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/overview.md b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/overview.md deleted file mode 100644 index 04b326c8..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/overview.md +++ /dev/null @@ -1,37 +0,0 @@ -# Parallel-Agent Bug Hunt — remediation - -## Goal -Fix confirmed findings from a 5-agent parallel sweep (2026-07-18, HEAD `7f9e8e5`) across five lenses: logic/correctness, resource cleanup (RAII), N+1/repeated work, error-handling/durability, prompt compression + injected-value hygiene. - -## Context -- Stack: `packages/aitm` — TS strict, ESM, `ai` `experimental_Agent` + subagents-as-tools; OpenRouter-only via `Credentials`; `gh`/`git` via execa argv. Runs unchanged Bun + Node≥20 + Deno≥1.40. -- Follows [`../../17/101-aitm-audit-remediation/`](../../17/101-aitm-audit-remediation/overview.md) — partially remediated in PR #215 (its `status.yml` is stale). This hunt audited post-#215 HEAD; no finding here is already fixed. Its slice `08-prompt-templating` overlaps slice `06` here — reconcile, don't duplicate. -- Production forces `concurrency = 1` (`run-loop-adapter.ts:563`). Non-mutexed `openPr`/`autoMergeFlow`/`addressReviews` are latent, not live — revisit before ever enabling concurrency > 1. Not in scope here. -- **Verified clean (do not "fix")**: `atomicWrite` temp+fsync+rename core; `StateStore.update` serialization chain; `waitForChecks` backoff; `ModelLimits`/CLAUDE.md/specialist-roster caching; GraphQL pagination bounds; CI-fix attempt caps; `mcp-client` connect/close error paths; `web-fetch`/`web-search` body draining; system-prompt fencing via `slots.ts` `defuseEnvelopeTags` (except the one seam in `06`). -- Reference patterns cited per slice: `state/state-store.ts` serialized RMW, `fs/atomic-write.ts`, `slots.ts` fencing, `worker.ts` `VERIFY_TAIL_MAX` cap discipline, `github-client.ts` `safeJson`. -- Prompt standards source: `gold-standards-in-ai/docs/writing-for-agents/compressed-config.md`, `claude-code-bible/docs/11-compressed-config.md` (agent prompt <50 lines, fragments, per-spawn cost), `claude-task-master` `prompts_base.py` PromptBuilder (`include_if` sections). - -## Plan files (execute in order) -1. [`01-pr-lifecycle-idempotency.md`](01-pr-lifecycle-idempotency.md) — crash-safe `gh pr create`; prPerTask+no-automerge duplicate PR; false `success` on awaiting-pr; partial group marked `merged` with a dropped task. -2. [`02-signal-cancellation-cleanup.md`](02-signal-cancellation-cleanup.md) — SIGINT/SIGTERM + AbortController wiring (currently dead code); editor-fanout sibling abort; temp-repo leak. -3. [`03-review-loop-idempotency.md`](03-review-loop-idempotency.md) — reviewer partial-resolution loss; addressed-thread record ordering; duplicate task commit on resume; sessionCount pre-batch inflation. -4. [`04-gh-client-parsing-caching.md`](04-gh-client-parsing-caching.md) — unguarded `JSON.parse` of `gh` stdout ×5; memoize `repoMeta`/`defaultBranch`; `{ cause }` at rethrow boundaries. -5. [`05-state-efficiency-durability.md`](05-state-efficiency-durability.md) — StateStore in-memory cache + drop double-validate; PlanGraph validate-once; pr-context atomic writes; post-rename fsync downgrade; transcript-failure signal. -6. [`06-prompt-compression-fencing.md`](06-prompt-compression-fencing.md) — claudeMd fence/cap in system-reminder; style digest sent twice; editor-leaf frame slimming; contract-prose compression. -7. [`07-cli-flag-correctness.md`](07-cli-flag-correctness.md) — inert `--no-resume`; parse errors exit 0. -8. [`08-tests.md`](08-tests.md) — paired `*.test.ts` + integration coverage per fix; both runtimes green. - -## Done when -- Kill -9 at any point in pr-open / review-address / task-commit resumes without a duplicate PR, duplicate reply, duplicate commit, or a permanently-blocked recoverable group. -- Ctrl-C closes MCP children and aborts in-flight subagent/gh work; `{ kind: 'cancelled' }` is reachable from the real binary. -- No `gh repo view` inside a poll tick; no unguarded `JSON.parse` of subprocess stdout. -- A run never exits 0 while planned work was dropped or a PR dangles unmerged under autoMerge. -- Style digest sent once per subagent call; repo `CLAUDE.md` fenced + capped before injection. -- `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint` all green. - -## Risks / open questions -- **Partial-PR policy (01)**: shipping a partial group is partly intentional. Decide: blocked group vs distinct `partial` status vs carry-forward task. Owner call before implementing. -- **prPerTask + no-automerge (01)**: reject flag combo vs one-PR-after-last-task. Owner call. -- **Editor-leaf slimming (06)**: which contract blocks a write-capable leaf keeps is a behavioral trade-off — trim conservatively, measure. -- `05` memoryIndex per-task re-read is intentional freshness — only cache per group with write-invalidation, or skip. -- Slices 01–07 are independent and parallelizable across executors; 08 follows all. diff --git a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/status.yml b/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/status.yml deleted file mode 100644 index 4be1e328..00000000 --- a/docs/plans/2026/07/18/101-parallel-agent-bug-hunt/status.yml +++ /dev/null @@ -1,36 +0,0 @@ -plan: 101-parallel-agent-bug-hunt -title: Parallel-Agent Bug Hunt — remediation -status: not_started # not_started | in_progress | blocked | complete | superseded -created_by: plan-author -worked_by: "" -owner: plan-owner -percent: 0 -current_focus: "" # start with 01 (PR idempotency) + 02 (signals); owner decisions gate 01 steps 2/4 -slices: - - file: 01-pr-lifecycle-idempotency.md - status: not_started - percent: 0 - - file: 02-signal-cancellation-cleanup.md - status: not_started - percent: 0 - - file: 03-review-loop-idempotency.md - status: not_started - percent: 0 - - file: 04-gh-client-parsing-caching.md - status: not_started - percent: 0 - - file: 05-state-efficiency-durability.md - status: not_started - percent: 0 - - file: 06-prompt-compression-fencing.md - status: not_started - percent: 0 - - file: 07-cli-flag-correctness.md - status: not_started - percent: 0 - - file: 08-tests.md - status: not_started - percent: 0 -evidence: [] -notes: "Findings from a 5-agent parallel sweep (2026-07-18, HEAD 7f9e8e5, post-PR-#215): logic, resource-cleanup/RAII, N+1, error-handling/durability, prompt compression + builder/fencing. Owner decisions before 01: partial-PR policy (blocked vs partial status) and prPerTask+no-automerge handling (reject combo vs one PR after last task). Prompt design intent: values SHOULD be injected via the typed-slot builder (buildRolePrompt/slots.ts) — 06 closes the one bypass (claudeMd in system-reminder) and the duplication, not the pattern. Verified clean at HEAD (do not re-fix): atomicWrite core, StateStore serialization, waitForChecks backoff, model-limits/CLAUDE.md caching, pagination bounds, mcp-client close paths, web-fetch/search body draining. Latent (concurrency=1 masks): non-mutexed openPr/autoMergeFlow/addressReviews — revisit only if concurrency > 1. Overlaps 2026/07/17 plan slice 08 (prompt templating) — reconcile." -last_updated: 2026-07-18 diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/01-observability-liveliness.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/01-observability-liveliness.md deleted file mode 100644 index e49130c5..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/01-observability-liveliness.md +++ /dev/null @@ -1,34 +0,0 @@ -# 01 — Observability & liveliness - -> Part of [`overview.md`](overview.md). Depends on: none. -> Steals: claudetm console recipe (blank-line-before-tool, one distilled arg, cwd-relative paths, global task context), Kimi status-line ideas, opencode `ctx.metadata` display-ready titles. - -## Files to change -- `packages/aitm/src/observability/step-progress.ts` — rendering upgrades (blank lines, short labels, relative paths, reasoning line). -- `packages/ai-claude-compat/src/subagent.ts:193-257` — `callWithRetry`/`defaultRetryDelayMs`: add `onRetry` callback param, thread through `callWithStepTimeout`. -- `packages/aitm/src/loop/run-loop-adapter.ts` — wire `onRetry` → progress line; style-distill progress; heartbeat. -- `packages/aitm/src/state/transcript-store.ts:87-98,202-205` — aggregate the invalid-message warning. -- `packages/aitm/src/cli/commands.ts:201-208` — usage line: add per-group timing; keep cost/cache columns (04 fills values). -- `packages/aitm/src/agent-config/coding-style.ts` (distiller) — progress callback naming files read. -- New: `packages/aitm/src/observability/heartbeat.ts` + paired test. - -## Steps -1. **Blank-line chunking** (claudetm `agent_message.py:63-66` pattern): in `renderStepLines` (`step-progress.ts:154-171`) emit one blank line before the first tool line of a step and before each agent-text line. Guard: never two consecutive blanks. -2. **Short labels**: `agentLabel` (`step-progress.ts:54-62`) currently embeds the full group slug every line → cap label to `role + g` (e.g. `k3 worker g1`); print the full slug once on group start via `harnessProgress`. Add `editor:` labels (05 consumes this). -3. **Relative paths + arg distillation**: in `summarizeToolInput` (`:111-151`) make `file_path`/`path` cwd-relative (claudetm `_relative_path` idea); keep `DETAIL_MAX=250` for `command`, drop to 120 for paths/patterns. -4. **Retry visibility**: add `onRetry(info: {attempt, maxAttempts, delayMs, reason})` to `callWithRetry` options (`subagent.ts:205-223`). Parse `Retry-After` header/body when present (opencode `session/retry.ts` pattern) and honor it for the delay. Adapter renders: `Rate limited (429), retrying in 15s (3/10)` — never an empty `Rate limited:` line. -5. **Heartbeat** (`observability/heartbeat.ts`): `startHeartbeat(label, sink)` → timer printing `still working… 2m10s` every 60s while no other progress line was emitted (track last-emit timestamp in the sink). Start/stop around every subagent `generate` call in `run-loop-adapter.ts`. Non-TTY safe (plain line, no ANSI rewrite). -6. **Reasoning line**: extend `StepProgressEvent` (`step-progress.ts:21-24`) with optional `reasoningText`; `composeStepFinish` source already receives SDK step — pass `step.reasoningText` when present. Render dim, clipped to 200 chars, prefixed `thinking:`. Config `showReasoning` (default true). -7. **Style-distill progress**: the `coding style: distilling…` phase runs a fast-tier agent with read tools — attach `agentStepProgress('style', …)` so each `readFile` shows (`coding style: reading CLAUDE.md`, …). User-visible answer to "what files is he reading". -8. **Transcript warning aggregation**: `validMessages` (`transcript-store.ts:87-98`) fires `onWarn` per bad element → count and emit ONE summary warning per reconstruct (`skipped N invalid transcript messages`). Root-cause note: record which schema field failed at debug level. -9. **Task/group timing**: `WorkLoop` already brackets tasks — print `task done in 7.2m` on `completeTask` (`work-loop.ts:888-913`) and group totals at `merged`, claudetm-style (active-work vs CI-wait split optional, needs `pr_active_work` accumulator in state schema — include only if trivial). - -## Tests -- `step-progress.test.ts`: blank-line rules, relative paths, reasoning line, label shortening (snapshot the rendered lines with a fake sink/clock). -- `subagent.test.ts` (compat): `onRetry` invoked with parsed Retry-After; delay honored. -- `heartbeat.test.ts`: fires only during silence; stops on progress. -- `transcript-store.test.ts`: N invalid messages → 1 warning. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- A recorded fake-sink run renders: group header, blank-line-separated tool steps, distilled args with relative paths, a retry line with countdown, a heartbeat during a stubbed 3-minute silent call, one aggregated transcript warning. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/02-tool-output-spill.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/02-tool-output-spill.md deleted file mode 100644 index d998ac51..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/02-tool-output-spill.md +++ /dev/null @@ -1,33 +0,0 @@ -# 02 — Tool output spill, background bash, loop guards - -> Part of [`overview.md`](overview.md). Depends on: none. -> Steals: opencode `tool/truncate.ts` (spill-to-file + paging hint, 7-day retention), Kimi `ToolResultBuilder` + background `output_path`, opencode doom-loop guard (`processor.ts:356-379`) and tool-call repair (`llm.ts:296-312`), Claude Code save-to-file behavior. - -## Files to change -- New: `packages/ai-claude-compat/src/tool-output-store.ts` + test — central spill service. -- `packages/ai-claude-compat/src/bash-tool.ts:85,121-130` — route overflow through the store instead of destructive head/tail. -- `packages/ai-claude-compat/src/search-tools.ts:163-166` — same for grep/glob truncation notices. -- `packages/ai-claude-compat/src/fs-tools.ts:121-146` — readFile over-window notice includes `offset` continuation hint (already windowed; just improve the notice). -- `packages/ai-claude-compat/src/background-process.ts` — wire into aitm. -- `packages/aitm/src/loop/run-loop-adapter.ts:302,310-311` — inject `ProcessManager` into `bashInit`; mount `bashOutput`/`killBash` tools for worker/reviewer. -- New: `packages/ai-claude-compat/src/tool-guards.ts` + test — repeat-call dedup/doom-loop reminder. - -## Steps -1. **`ToolOutputStore`**: `save(toolName, content) → {path, bytes, lines}` writing under `/tool-output/--.txt`; `cleanup(maxAgeDays=7)` called once per run start. Constructor takes the dir (aitm passes `.ai-task-master/tool-output/`); pure `node:fs/promises`. -2. **Bash overflow**: keep `MAX_BASH_OUTPUT_CHARS=30_000` in-context cap, but on overflow spill the FULL stream to the store and append (opencode `truncate.ts:129-137` wording): `[output truncated: N lines omitted. Full output: — page it with readFile(offset/limit) or grep]`. Same treatment in `multiBash`. -3. **Grep/glob overflow**: truncation notice gains the saved-file path when results exceeded caps (`DEFAULT_MAX_RESULTS=200`, `GLOB_MAX_FILES=2000`). -4. **Aggregate step budget**: in the tool wrapper layer (where `toModelOutput` is built), track per-step total chars; once a step's combined tool output exceeds 120k chars, force spill mode for remaining results in that step (prevents N×cap context floods noted in the map, §2). -5. **Background bash wiring**: `run_in_background: true` currently degrades to foreground because aitm never injects a `ProcessManager` — construct one per run in `run-loop-adapter.ts` (`localEditTools` init), mount `bashOutput`/`killBash`, and on run end kill leftovers. Background completion returns tail + `output_path` (Kimi `background/__init__.py:75-97` shape). -6. **Doom-loop guard** (`tool-guards.ts`): hash (toolName, canonical input) per conversation; identical repeat ≥3 → prepend escalating reminder to the tool result; ≥8 → return error result instructing a different approach (Kimi `toolset.py:371-423` escalation, no permission system to fall back on). -7. **Tool-call repair**: on unknown tool name, try lowercase/known-alias match before failing; else return a structured "unknown tool, available: […]" error result instead of throwing (opencode `llm.ts:296-312`). Lives beside the guard in compat. -8. **Multi-read decision**: do NOT add a `multiRead` tool — parallel tool calls already cover it (provider `parallelToolCalls:true`, `worker.ts:527-531`). Instead strengthen `readFile`/`grep` tool descriptions to say "batch independent reads as parallel calls in one step". Document the decision in the PR body. - -## Tests -- `tool-output-store.test.ts`: save/cleanup/retention; path shape. -- `bash-tool.test.ts`: overflow → file exists with full content, model output has path + hint; background path returns `output_path`; killBash reaps. -- `tool-guards.test.ts`: dedup escalation ladder; repair aliasing. -- Integration (`packages/aitm/test/integration/`): worker in temp repo runs a command producing 100k output → follow-up `readFile` of the spill path succeeds (real repo, no LLM — drive tools directly). -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- No tool output is destructively lost above caps; spill files are pageable and cleaned after 7 days; `run_in_background` actually backgrounds; repeated identical calls get escalating pushback. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/03-pr-composition-robustness.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/03-pr-composition-robustness.md deleted file mode 100644 index dba19cc8..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/03-pr-composition-robustness.md +++ /dev/null @@ -1,25 +0,0 @@ -# 03 — PR composition robustness - -> Part of [`overview.md`](overview.md). Depends on: none. -> Fixes the observed run-101 failure: group `blocked (orchestrator PR composition failed schema validation: title >72 chars)` after 10.1M tokens. Review-before-PR ordering is already correct (`maybeSelfReview` runs inside `openPr` bridge before `orchestrator.openPr`, `work-loop.ts:658-666`) — do not reorder it. - -## Files to change -- `packages/aitm/src/orchestrator/orchestrator.ts:322-398` — `composePr`: in-conversation schema retry + deterministic fallback. -- `packages/aitm/src/orchestrator/orchestrator.test.ts` — paired tests. -- `packages/aitm/src/loop/work-loop.ts:428-458` — composition failure path must not reach the group-`blocked` catch. - -## Steps -1. **Schema retry**: mirror compat `runWithSchemaRetry` (used by planner `planner.ts:95` and worker manifest, `MANIFEST_SCHEMA_RETRIES=2`): on `PrCompositionSchema` (`orchestrator.ts:191-195`) or `assertPrBodySections` (`:168-187`) failure, feed the violation back as a user message ("title was N chars, max 72 — resubmit") and retry up to 2 times within the same conversation. Keep `toolChoice: 'auto'` (thinking-model constraint, `:358-365`). -2. **Deterministic fallback**: if retries exhaust (or the model never calls `submit`), synthesize instead of throwing: - - title: `feat: ` hard-sliced to 72 chars (word boundary when possible); - - body: `## Summary` from group title+tasks, `## Changes` from `git log --oneline base..head` (available via `GitHubClient`/deps), `## Testing` from the verify/self-review outcome string. Must pass `assertPrBodySections` by construction. -3. **Never block on composition**: `composePr` becomes total (always returns a composition). Log a warning line (`PR composition fell back to generated title/body`) via the progress sink so the run surfaces the degradation. Delete/adjust the throw sites at `:386-395`. -4. **Log the composition**: one progress line with the final title on PR open (users currently can't see what title was attempted). - -## Tests -- Unit (`orchestrator.test.ts`, MockLanguageModel): over-long title → retry message sent → second attempt accepted; retries exhausted → fallback used, sections valid, title ≤72; model never calls submit → fallback; happy path unchanged. -- Unit (`work-loop.test.ts`): openPr no longer produces `blocked` for composition-shaped errors (only for genuine push/gh failures). -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Run-101's failure input (72+ char title) yields an opened PR (retried or fallback), never a blocked group; degradation is visible in the console. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/04-caching-transport.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/04-caching-transport.md deleted file mode 100644 index 764c49be..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/04-caching-transport.md +++ /dev/null @@ -1,34 +0,0 @@ -# 04 — Prompt caching, transport, cost - -> Part of [`overview.md`](overview.md). Depends on: none. -> Steals: opencode `applyCaching` breakpoints + `prompt_cache_key`=sessionID (`provider/transform.ts:1142-1150,1245`), Kimi `prompt_cache_key`=session-id (`llm.py:360-362`), OpenRouter `session_id` sticky routing, undici keep-alive tuning. - -## Files to change -- `packages/aitm/src/credentials/credentials.ts:26-60` — `chatSettings`: caching + session params per provider family. -- `packages/aitm/src/credentials/defaults.ts` — nothing model-wise; document cache behavior. -- `packages/aitm/src/config/provider-presets.ts:11-29` — add `moonshot` preset (api.moonshot.ai OpenAI-compatible, kimi-k2 family); annotate presets with `caching: 'automatic' | 'cache_control'`. -- New: `packages/aitm/src/credentials/llm-fetch.ts` + test — keep-alive fetch factory. -- `packages/aitm/src/observability/usage-tracker.ts:46-113` — cache read/write + discount columns; cost via pricing catalog. -- `packages/aitm/src/openrouter/client.ts:37-47` — reuse `listModels` pricing for cost resolution (cached per run). -- `packages/aitm/src/cli/commands.ts:201-208` — usage line gains `cache-hit %` and real `$`. -- `packages/aitm/src/loop/run-loop-adapter.ts:374-379` — cache-hostile prompt fix (dynamic block placement). - -## Steps -1. **Session stickiness + implicit cache key**: generate one run-scoped id (persist in state so resume reuses it per group/stage conversation). In `chatSettings`, pass provider options: OpenRouter → `session_id` (sticky upstream routing) and `prompt_cache_key` for OpenAI-family routes; direct OpenAI-compatible baseURLs (z.ai, moonshot) → `prompt_cache_key` only. Verify the `@openrouter/ai-sdk-provider` passthrough mechanism (extraBody/providerOptions) — if it can't carry arbitrary body keys, inject via the custom fetch (step 3) body rewrite. -2. **cache_control scope**: keep `anthropic/*` ephemeral breakpoints (`credentials.ts:53-58`) but stop dropping it when `baseURL` is custom-yet-OpenRouter-shaped; add Qwen/Alibaba to the `cache_control` family per OpenRouter docs. Everything else relies on automatic upstream caching — no-op. -3. **Keep-alive fetch** (`llm-fetch.ts`): factory returning a `fetch` for the provider: on Node, dynamic-import `undici`, build `Agent({keepAliveTimeout: 60_000, connections: 16})`, pass as `dispatcher` per request; on Bun/Deno (or undici unavailable) return global fetch (native pooling). Feature-detect via `process.versions.bun` / `typeof Deno` — no `Bun.*` APIs. Wire into `providerSettings` (`credentials.ts:81-86`) as `fetch`. -4. **Stable prompt prefix**: `harnessContextBlock` (`run-loop-adapter.ts:374-379`) injects `currentDate` + `Step N of M` into the FIRST user message — a per-step mutation near the prefix. Move the dynamic `runProgress` into the LAST message of each request (or a trailing system-reminder), keep `currentDate` date-only (stable within a day). Audit other per-call dynamic strings early in prompts (memory index ordering, style digest) — they must be byte-identical across calls in a conversation. -5. **Usage/cache reporting**: extend `UsageTracker.record` to capture `cachedInputTokens` AND provider-metadata cache-write/discount when present (OpenRouter `cache_discount`, requires usage accounting enabled — send `usage: {include: true}` if the provider supports it). Summary line: `Usage: N calls, X in (Y% cached) / Z out, $C — per-role…`. -6. **Real cost**: `ModelLimitsLookup` returns `null` for unknown models → on flush, resolve missing prices once via `OpenRouterClient.listModels` (only when baseURL is OpenRouter; else keep `cost unknown`). Cache the catalog in-memory per run; network failure → silent fallback to null. -7. **Moonshot preset**: `provider-presets.ts` gains `moonshot` (baseURL `https://api.moonshot.ai/v1`, models kimi-k2.5 family, automatic caching, `prompt_cache_key` on). Paired test updates. - -## Tests -- `credentials.test.ts`: chatSettings emits session/cache params per family; anthropic breakpoints preserved; z.ai/moonshot get `prompt_cache_key` only. -- `llm-fetch.test.ts`: Node path returns dispatcher-wrapped fetch (mock undici import); Bun path returns global fetch (gate with `process.versions.bun`). -- `usage-tracker.test.ts`: cache columns, catalog-priced cost, unknown stays null. -- `provider-presets.test.ts`: moonshot preset shape. -- A/B smoke (manual, record in PR body): one small real run before/after step 4, compare `cached_tokens` ratio. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Requests carry session stickiness + cache keys per provider family; keep-alive dispatcher active on Node; usage line shows cache-hit % and real cost on OpenRouter defaults; measured cache-hit ratio improves on the A/B smoke run. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/05-editor-team-fanout.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/05-editor-team-fanout.md deleted file mode 100644 index 371914a0..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/05-editor-team-fanout.md +++ /dev/null @@ -1,28 +0,0 @@ -# 05 — Editor team fanout ("football team") - -> Part of [`overview.md`](overview.md). Depends on: 01 (labels). -> Team invariants already hold — keep them: only the main agent manages subagents (orchestrator role prefix `orchestrator.ts:87-104`; Kimi enforces the same root-only rule), no worktrees, editors share the working tree. This slice makes the fanout bounded, cooperative, and visible. - -## Files to change -- `packages/aitm/src/subagents/worker.ts:481-505` — `runEditorFanout`: concurrency pool + file grouping. -- `packages/aitm/src/subagents/worker.ts:507-549` — `runEditor`: shared team brief + progress label. -- `packages/aitm/src/subagents/specialist-registry.ts:115-131` — announce selection. -- `packages/aitm/src/config/schema.ts` — `editorConcurrency` (default 4, min 1); reuse existing `concurrency` naming conventions. -- New: `packages/ai-claude-compat/src/pool.ts` + test — tiny promise pool (inline-first rule: only extract if compat lacks one; check before adding). - -## Steps -1. **Bounded pool**: replace unbounded `Promise.all` with a pool of `min(editorConcurrency, files)`; keep the shared `AbortController` semantics (any reject aborts siblings, `worker.ts:481-505`). -2. **File grouping**: group manifest entries by top-level dir (or explicit `group` field if the manifest schema gains one) so one editor owns cohesive files instead of strictly one-per-file; cap ~3 files/editor. Single-file manifests: behavior unchanged. -3. **Team brief**: build once per fanout — task text + manifest table (path → purpose) + rolling context (existing `ROLLING_CONTEXT_MAX=4000`, `worker.ts:215`) — and inject into every editor's system prompt so each teammate sees the whole play, not just its file. Keep per-editor style cap `EDITOR_STYLE_MAX=1500`. -4. **Identity in logs**: label each editor `editor:` via the 01 label hook; fanout start prints roster: `worker: fanning out 3 editors — auth/ (2 files), api/ (1 file)…`; each completion prints one outcome line (changed/blocked). Uses `agentStepProgress` per editor. -5. **Specialist announcement**: when `selectSpecialist` picks a `.claude/agents/*.md`, print `using specialist: (score N)` once per group. -6. **Phantom-edit policy unchanged**: keep `editorTouchedPath` git check (`worker.ts:556-574`); with grouping, check all files of the group. - -## Tests -- `worker.test.ts`: pool cap honored (mock model, observe max concurrent generates); grouping by dir; abort propagation preserved; single-file path byte-identical prompts vs today (regression guard). -- `pool.test.ts` (if extracted): cap, rejection, abort. -- `specialist-registry.test.ts`: announcement callback. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- A 10-file manifest runs ≤4 editors concurrently in ~4 dir-cohesive groups, every editor visible in the console with its own label, roster + outcomes printed; no behavior change for 1-file manifests. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/06-context-pruning-compaction.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/06-context-pruning-compaction.md deleted file mode 100644 index eab094a8..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/06-context-pruning-compaction.md +++ /dev/null @@ -1,24 +0,0 @@ -# 06 — Context pruning & compaction - -> Part of [`overview.md`](overview.md). Depends on: none. -> Steals: opencode prune-before-compact (`session/compaction.ts:243-287`) + anchored updatable summaries (`core/src/session/compaction.ts:161-168`), Kimi usage-grounded token accounting (`context.py:76-77`). - -## Files to change -- `packages/aitm/src/compaction/compaction-step.ts:41-127` — pruning stage before summarization; anchored summary. -- `packages/aitm/src/compaction/compactor.ts:57-95` — accept prior summary for update-in-place; usage-fed token counts. -- `packages/aitm/src/observability/usage-tracker.ts` — expose last-call input tokens per conversation (feed the trigger). -- `packages/aitm/src/loop/run-loop-adapter.ts:842-846` — wire usage feed into the shared Compactor. - -## Steps -1. **Prune first**: in `buildCompactionStep`, before invoking the LLM summarizer, walk messages older than the last `keepLastSteps=6`, replace completed tool-result contents (over ~1k chars) with `[old tool result cleared — rerun the tool if needed]`, keeping a 40k-char recency shield of tool output. Only if pruning frees <20k chars proceed to LLM compaction. Cheap pass, no model call. -2. **Anchored summary**: when a `SUMMARY_HEADER` block already exists in the prefix, pass it to `Compactor.compact` as `` and prompt for an UPDATED summary (opencode template sections: objective / done / in-progress / files / next) instead of re-summarizing from scratch. -3. **Usage-grounded trigger**: `shouldCompact` (`compactor.ts:57-77`) currently estimates chars/4 over live messages; prefer the API-reported input tokens of the conversation's last call (from `UsageTracker` via a per-conversation sink) and only char-estimate the delta appended since. Fewer premature/missed compactions. -4. **Cache interaction note** (doc comment + PR body): pruning/compaction rewrites the prefix → one-time cache miss; that's why prune thresholds are conservative and compaction stays rare (aligns with 04's stable-prefix work). - -## Tests -- `compaction-step.test.ts`: prune clears old tool results, respects recency shield, skips LLM when enough freed; anchored update path passes previous summary. -- `compactor.test.ts`: usage-fed trigger math; fallback to estimate when no usage yet. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- Long worker conversations prune before summarizing (observable in transcript records), summaries update instead of restarting, and compaction triggers track real usage tokens. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/07-streaming-liveliness.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/07-streaming-liveliness.md deleted file mode 100644 index b1f018ed..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/07-streaming-liveliness.md +++ /dev/null @@ -1,25 +0,0 @@ -# 07 — Streaming adoption (gated) - -> Part of [`overview.md`](overview.md). Depends on: 01. Higher risk — config-gated `streaming: false` default until burn-in. -> Steals: Kimi two-regime stream-idle watchdog (claudetm `agent_query.py:46-66,488-554` variant), Kimi live tool-arg preview (streamed-JSON lexing — optional stretch), opencode per-chunk SSE timeout (`provider.ts:1762`) and stream-based rendering. - -## Files to change -- `packages/ai-claude-compat/src/subagent.ts` — the single generate funnel (`callWithStepTimeout` → `callWithRetry`) gains a `streamText` path; step results normalized so callers see the same shape. -- `packages/aitm/src/observability/step-progress.ts` — render text deltas line-buffered (print on newline, not per-token) using the 01 sink. -- `packages/aitm/src/config/schema.ts` — `streaming` flag. -- `packages/aitm/src/loop/run-loop-adapter.ts` — thread flag to all subagent factories. - -## Steps -1. **Streaming funnel**: add `streamText` alternative inside the compat funnel; consume the stream, forward text-deltas + tool-call events to an optional `onStream` sink, and resolve to the same final result object `generateText` returns (`await result.text/steps`). Retry/timeout wrappers unchanged around the whole stream. -2. **Stall watchdog**: replace the flat `stepMs` deadline in streaming mode with per-chunk inactivity timeout (120s no chunk → abort + retry once) plus overall cap; after finish-reason arrives, a short 30s grace regime (two-regime pattern — never re-run a completed coding step; duplicate-PR hazard). -3. **Line-buffered rendering**: progress sink prints assistant text as it streams, buffered to whole lines, respecting 01 blank-line rules; tool lines still render on tool-call events (before results — earlier than today's post-step rendering). -4. **Gating + parity tests**: `streaming:false` must remain byte-identical in behavior; e2e-smoke integration runs once with the flag on. - -## Tests -- `subagent.test.ts` (compat, MockLanguageModel streaming): funnel parity of final results; watchdog aborts a stalled mock stream; grace regime does not retry after finish. -- `step-progress.test.ts`: line-buffered delta rendering. -- Integration: `e2e-smoke` variant with `streaming: true`. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- With `streaming: true`, text and tool lines appear live during generation, stalled streams recover, and all existing tests pass with the flag off (default). diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/overview.md b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/overview.md deleted file mode 100644 index 73a36ec6..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/overview.md +++ /dev/null @@ -1,43 +0,0 @@ -# aitm: liveliness, tool efficiency, team fanout, caching & transport - -## Goal -Close the gap between aitm and the best agentic CLIs (Claude Code, Kimi CLI, opencode, claudetm) for big `aitm start '...'` runs: readable live output, oversized-output spill instead of destructive truncation, robust PR composition (no more `blocked: title >72 chars` after 10M tokens), provider-level prompt caching + keep-alive transport, bounded "football team" editor fanout, and cheaper context management. - -## Context -- Stack: Bun dev runtime, must run unchanged on Node ≥20 / Deno ≥1.40; ESM only; `ai` package `ToolLoopAgent`-style agents; OpenAI-compatible inference via `Credentials` (`@openrouter/ai-sdk-provider`, `createOpenRouter` at `packages/aitm/src/credentials/credentials.ts:139-145`); `gh` CLI wrapper; no streaming today — everything is `generateText`. -- Live console contract: `packages/aitm/src/observability/step-progress.ts` (prefix `:80-87`, `renderStepLines:154-171`, `summarizeToolInput:111-151`, `DETAIL_MAX=250`). Structured `Logger` (`packages/aitm/src/logger/logger.ts:40`) is a separate stderr/file sink. -- Retry loop: compat `packages/ai-claude-compat/src/subagent.ts` `callWithRetry:205-223` — silent, no Retry-After parsing. -- PR composition: `packages/aitm/src/orchestrator/orchestrator.ts` `composePr:322-398`, schema `:191-195`, `assertPrBodySections:168-187` — single-shot, throw → group `blocked` (`work-loop.ts:428-458`). -- Editor fanout: `packages/aitm/src/subagents/worker.ts` `runEditorFanout:481-505` — one editor per manifest file, unbounded `Promise.all`, no shared context. -- Caching today: `cache_control: ephemeral` only when model id starts `anthropic/` and no custom baseURL (`credentials.ts:53-58`). No `prompt_cache_key`, no `session_id` stickiness, no custom fetch/keep-alive. -- Research findings the slices lean on (verified 2026-07-18): - - OpenRouter: per-upstream caching (Anthropic `cache_control` breakpoints; OpenAI/DeepSeek/Gemini/Moonshot automatic), `session_id` body param for sticky upstream routing, usage `prompt_tokens_details.cached_tokens` + `cache_discount`. Moonshot + z.ai direct: automatic caching, OpenAI-compatible `cached_tokens` reporting. - - undici (Node global fetch): keep-alive default idle timeout **4s** — sequential LLM calls re-handshake; tune via `Agent({keepAliveTimeout})` + custom `fetch` on the provider. - - Oversized-output consensus (Claude Code, opencode `tool/truncate.ts`, gemini-cli): cap in context + spill full output to a file + tell the model to Read(offset)/grep the file. Kimi CLI: central `ToolResultBuilder` (50k chars), background jobs return tail + `output_path`. - - claudetm readability recipe: blank line before every tool call, one distilled arg per tool, cwd-relative paths, module-global task context in every prefix, color-coded speaker, tool bodies suppressed. - - opencode: prune-before-compact (clear old tool outputs, 40k recency shield), anchored updatable summaries, retry layer with Retry-After, doom-loop guard, tool-call repair. -- Reference pattern for schema-retry: compat `runWithSchemaRetry` (used by planner/worker; NOT by composePr). - -## Plan files (execute in order; 01–06 are independent, 07 depends on 01) -1. [`01-observability-liveliness.md`](01-observability-liveliness.md) — readable live output: blank lines, short labels, retry/heartbeat lines, reasoning, style-distill progress, warning spam fix. -2. [`02-tool-output-spill.md`](02-tool-output-spill.md) — spill oversized tool output to file + paging; wire background bash; doom-loop guard + tool-call repair. -3. [`03-pr-composition-robustness.md`](03-pr-composition-robustness.md) — composePr schema retry + deterministic fallback; composition failure never blocks a group. -4. [`04-caching-transport.md`](04-caching-transport.md) — prompt caching per provider, stable prompt prefix, keep-alive fetch, cache/cost stats, moonshot preset. -5. [`05-editor-team-fanout.md`](05-editor-team-fanout.md) — bounded editor pool, file grouping, shared context digest, per-teammate log identity. -6. [`06-context-pruning-compaction.md`](06-context-pruning-compaction.md) — prune-before-compact, anchored summaries, usage-grounded token counts. -7. [`07-streaming-liveliness.md`](07-streaming-liveliness.md) — adopt `streamText` for live text + stall watchdog (higher risk, gated). - -## Done when -- A full `aitm start` run reads like the claudetm sample: task/group boundaries with blank lines, short prefixes, one distilled arg per tool line, visible retries ("Rate limited, retrying in Ns (n/10)"), no silent multi-minute gaps, no `warning: skipping a transcript message` spam. -- No tool result over its cap is destructively lost: full output lands under `.ai-task-master/tool-output/` and the model demonstrably pages it back (integration test). -- PR composition failure can no longer mark a group `blocked`: schema retry + deterministic fallback covered by unit tests; the `title>72` scenario from run 101 passes. -- Usage summary prints cache hit tokens, cache discount when available, and a real `$` cost for known models (no more `cost unknown` on OpenRouter defaults). -- Editor fanout bounded (config `concurrency`, default ≤4) with per-editor labels in the console; behavior identical for single-file manifests. -- All gates green on Bun and Node: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`; every touched module keeps its paired `*.test.ts`. - -## Risks / open questions -- Streaming adoption (07) touches every generate site via compat — land last, behind config `streaming` (default off) until burn-in. -- Prompt-prefix reordering (04) changes what the model sees first; A/B a smoke run before defaulting. -- undici is a new runtime dep for keep-alive tuning on Node; Bun/Deno fall back to native pooling (portability rule: no `Bun.*`; dynamic import + feature-detect). -- `tmp/kimi` + `tmp/opencode` research clones are untracked and NOT gitignored — executor should add `tmp/` to `.gitignore` (or delete the clones) before any `git add -A`. -- Out of scope (hard): mailbox, aitm-as-MCP-server, webhooks/inbound HTTP, Docker. Kimi's D-Mail/checkpoint-revert and opencode SQLite storage are explicitly not planned. diff --git a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/status.yml b/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/status.yml deleted file mode 100644 index a40ae02a..00000000 --- a/docs/plans/2026/07/18/102-aitm-liveliness-tools-team-caching/status.yml +++ /dev/null @@ -1,33 +0,0 @@ -plan: 102-aitm-liveliness-tools-team-caching -title: "aitm: liveliness, tool efficiency, team fanout, caching & transport" -status: not_started -created_by: plan-author -worked_by: "" -owner: plan-owner -percent: 0 -current_focus: "" -slices: - - file: 01-observability-liveliness.md - status: not_started - percent: 0 - - file: 02-tool-output-spill.md - status: not_started - percent: 0 - - file: 03-pr-composition-robustness.md - status: not_started - percent: 0 - - file: 04-caching-transport.md - status: not_started - percent: 0 - - file: 05-editor-team-fanout.md - status: not_started - percent: 0 - - file: 06-context-pruning-compaction.md - status: not_started - percent: 0 - - file: 07-streaming-liveliness.md - status: not_started - percent: 0 -evidence: [] -notes: "Research inputs: parallel agent decompositions of Claude Code, Kimi CLI (tmp/kimi), claude-task-master, opencode (tmp/opencode) + web research on AI SDK agents, prompt caching (OpenRouter/Moonshot/z.ai/DeepSeek), undici keep-alive. tmp/ clones are untracked and not gitignored." -last_updated: 2026-07-18 diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/01-data-safety-state.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/01-data-safety-state.md deleted file mode 100644 index 07d72cf4..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/01-data-safety-state.md +++ /dev/null @@ -1,30 +0,0 @@ -# 01 — Data safety & state integrity - -> Part of [`overview.md`](overview.md). Depends on: none. -> Findings: [`findings/04-github-state-workspace-fs.md`](findings/04-github-state-workspace-fs.md) (bugs 1, 2, 9, 10, 18; resources 2-4), [`findings/03-cli-config.md`](findings/03-cli-config.md) (bug 3). - -## Files to change -- `packages/aitm/src/workspace/in-place-checkout.ts:145-153` — `ensureCleanTree` destroys pre-existing uncommitted user work via `git reset --hard` + `git clean -fd`. -- `packages/aitm/src/state/state-store.ts:43-48` — `init` silently overwrites existing `state.json`; no cross-process lock (`:24-77`). -- `packages/aitm/src/state/schema.ts:111-135` — no `schemaVersion`; ad-hoc read-time coercions. -- `packages/aitm/src/state/state-store.ts:224-226` — duplicate legacy task ids break resume dedup. -- `packages/aitm/src/cli/commands.ts:689-695` — `merge-pr --no-resume` clobbers a mid-plan run via `state.init()`. -- `packages/aitm/src/workspace/task-commit-marker.ts:11-13` — non-line-safe task ids silently disable resume dedup. -- `packages/aitm/src/state/transcript-store.ts:169-171, 238-251` — un-fsynced `run-end` record; orphaned empty reserved ordinals. - -## Steps -1. Dirty-tree guard: at run entry (first `acquire` of a run), if the tree is dirty, refuse with a clear message (or auto-stash behind a flag); keep auto-clean only between groups. See findings/04 item 1 for the distinction. -2. Add `StateStore` run lock: exclusive `run.lock` (open `wx`, pid inside) acquired in init/resume, released in try/finally; second process fails fast. Test with two store instances over one dir. -3. Make `StateStore.init` refuse when `state.json` exists unless `force: true`; update callers. -4. Fix `merge-pr --no-resume`: update `currentPr` in place (or refuse when `prGroups` non-empty) instead of `init()` clobber; extend `commands.test.ts:1101-1135` with a mid-plan-run seed. -5. Add `schemaVersion` to `RunStateSchema` + keyed migration table replacing the five per-field legacy escapes in `state-store.ts:212-248`. -6. `legacyTask`: suffix index into every legacy id, not just empty-slug. -7. `taskCommitTrailer`: reject/sanitize ids containing newlines. -8. Transcript store: retry/fsync the `run-end` record; prune empty reserved ordinals during `begin`. - -## Tests -- Unit beside each module (`in-place-checkout.test.ts`, `state-store.test.ts`, `commands.test.ts`, `transcript-store.test.ts`). Two-instance lock contention; dirty-tree refusal; init-refuse; migration table round-trip. -- `bun test && bun run test:node && bun run typecheck`. - -## Done when -- A dirty tree at run start can never be silently destroyed; concurrent runs fail fast; `--no-resume` never loses a plan; state files carry a version. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/02-config-trust-secrets.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/02-config-trust-secrets.md deleted file mode 100644 index b96b66c1..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/02-config-trust-secrets.md +++ /dev/null @@ -1,30 +0,0 @@ -# 02 — Config trust boundaries & secret redaction - -> Part of [`overview.md`](overview.md). Depends on: none. -> Findings: [`findings/03-cli-config.md`](findings/03-cli-config.md) (bugs 1, 2, 4), [`findings/06-observability-logger-compaction-plan-tools.md`](findings/06-observability-logger-compaction-plan-tools.md) (bugs 1, 5, 6, 13, 14; capability 1), [`findings/04-github-state-workspace-fs.md`](findings/04-github-state-workspace-fs.md) (bug 11). - -## Files to change -- `packages/aitm/src/config/config-loader.ts:160-163,70-76` — project-scope `bashRules` can re-enable `git push --force`/`gh pr merge` from an untrusted checked-in config. -- `packages/aitm/src/config/profiles.ts:77-84,43,57,239-248` — profile names unchecked → prototype pollution via `__proto__`/`constructor`. -- `packages/aitm/src/config/config-writer.ts:29-39` — writer happily stores secrets/shell commands into project scope that the loader then strips. -- `packages/aitm/src/workspace/git-exec.ts:46-47` — `assertGitAllowed` bypassed by `-C`/`-c` global options before `push`. -- `packages/aitm/src/observability/step-progress.ts:235-255,282,290` — progress stream never runs `scrubSecrets`. -- `packages/aitm/src/logger/secret-scrubber.ts:15` — misses `github_pat_`, `sk_live_`/`sk_test_` families. -- `packages/aitm/src/logger/logger.ts:67-69` — `status()` unscrubbed. -- `packages/aitm/src/observability/error-reporter.ts:32-50` — `scrubEvent` misses `frames[].vars`, `breadcrumb.data`, `extra`, `tags`, `contexts`. -- `packages/aitm/src/tools/web-fetch.ts:151-159` — SSRF denylist misses 100.64/10 (CGNAT), 192.0.0/24, 198.18/15, `64:ff9b::/96`. - -## Steps -1. Treat project `bashRules` as untrusted: merge project rules *after* global deny rules; forbid project `allow` overriding `DEFAULT_BASH_RULES` (or strip entirely, matching `hooks`/`formatCommand`). -2. Validate profile names: `Object.hasOwn` membership, reject `FORBIDDEN_KEY_SEGMENTS` (mirror `provider-presets.ts:52-56`). Add hostile-name tests (`add/use/set __proto__`). -3. Export `UNTRUSTED_PROJECT_FIELDS` from config-loader; make `ConfigWriter.set` reject those keys in `--project` scope. -4. `assertGitAllowed`: skip leading `-C ` / `-c k=v` global options before locating the subcommand; test both bypass forms. -5. Secret redaction sweep: pipe `step-progress` `clip()` output and `logger.status()` through `scrubSecrets`; extend scrubber regex (`github_pat_`, `(?:sk|pk|rk)_(?:live|test)_`); deep-walk Sentry events in `scrubEvent`. -6. Env-value scrubbing (new capability): collect literal values of `OPENROUTER_API_KEY` + profile keys at startup, redact those exact strings in every output channel (logger, progress, reporter) — pattern matching can't catch arbitrary-format keys from custom OpenAI-compatible endpoints. -7. Extend web-fetch SSRF ranges per findings. - -## Tests -- Paired unit tests per module; hostile-config fixture proving a checked-in project config cannot loosen bash governance; secret-leak regression: run a fake step whose tool input embeds a `Bearer` token / `github_pat_` and assert scrubbed output on every channel. - -## Done when -- No checked-in repo file can widen shell permissions; no output channel emits an unredacted credential; both `git push` bypasses are closed. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/03-cancellation-resources.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/03-cancellation-resources.md deleted file mode 100644 index a51b120d..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/03-cancellation-resources.md +++ /dev/null @@ -1,34 +0,0 @@ -# 03 — Cancellation & resource lifecycle - -> Part of [`overview.md`](overview.md). Depends on: none. Cross-package: needs `signal` support in `packages/ai-claude-compat`. -> Findings: [`findings/07-resource-lifecycle-sweep.md`](findings/07-resource-lifecycle-sweep.md) (all), [`findings/01-loop.md`](findings/01-loop.md) (bug 6; resources 1-5), [`findings/02-subagents-orchestrator.md`](findings/02-subagents-orchestrator.md) (resources 1-4), [`findings/06-observability-logger-compaction-plan-tools.md`](findings/06-observability-logger-compaction-plan-tools.md) (resources 1-4), [`findings/03-cli-config.md`](findings/03-cli-config.md) (resources 1-4). - -Copy the good pattern already in-tree: `subagents/worker.ts:984-1038` (AbortController + listener removal in finally). - -## Files to change -- New `packages/aitm/src/fs/sleep.ts` (or `loop/sleep.ts`) — abortable `sleep(ms, signal)`. -- New `packages/aitm/src/loop/disposer.ts` — run-scoped `Disposer` (`add(fn)`, idempotent `disposeAll()`). Hand-rolled, NOT `AsyncDisposableStack` (Node 20 / Deno 1.40 portability). -- `packages/ai-claude-compat/src/subagent.ts:935` — add `signal` param to `runSubagent`/`agent.generate`. -- `packages/aitm/src/subagents/factory.ts` — `signal` on `SubagentInit`; forward at all 4 create sites (planner/reviewer/worker/scouts). -- `packages/aitm/src/loop/{work-loop.ts,stage-handlers.ts,take-over-flow.ts,ci-fix.ts,self-review.ts}` — thread `signal` into `StageDeps`, poll loops, grace sleeps. -- `packages/aitm/src/github/github-client.ts:41-59,75-80` — `defaultRunCmd` gains `timeout`+`cancelSignal`; `defaultSleep` → abortable. -- `packages/aitm/src/workspace/git-exec.ts:66`, `orchestrator/orchestrator.ts:71` — same execa timeout/signal chokepoints. -- `packages/aitm/src/loop/run-loop-adapter.ts:639-642,764,631-632,1189…` — unconditional `mcp.close()` in finally; `.catch` on `reapOnAbort` close; prune `workerHandles`/`ciFixHandles` on terminal group stages; `plannerRecorder.end()` in finally. -- `packages/aitm/src/credentials/llm-fetch.ts:77-85` — return `{ fetch, close }`; don't clobber caller's `dispatcher`; dispose at run end via Disposer. -- `packages/aitm/src/mcp/oauth.ts:96-102` — `proc.on('error', …)` on the browser spawn (currently crashes the process on headless hosts). -- `packages/aitm/src/cli/cli.ts:197-238` — unified shutdown: flush Logger + UsageTracker + reporter on normal exit AND first signal; `process.exitCode` instead of hard `exit` where possible; force-exit path still flushes (bounded). -- `packages/aitm/src/observability/{usage-tracker.ts,heartbeat.ts:55-58,error-reporter.ts:61-89}` — persist/flush spend on signal; `unref()` heartbeat; reporter `close()`. - -## Steps -1. Land compat `signal` support first (blocking dependency). -2. Add `sleep(ms, signal)` + `Disposer`; unit-test both (abort mid-sleep clears timer; disposeAll runs all, tolerates throwers, idempotent). -3. Thread `RunLoopInput.signal` per file list above; check `signal.aborted` at top of every poll iteration. -4. Execa chokepoints: `timeout` + `cancelSignal` in `defaultRunCmd`/`runGit`; `AbortSignal.timeout` on `OpenRouterClient.listModels` + `reference-catalog.ts:34`. -5. Register on the run Disposer: MCP manager close, llm-fetch agent close, transcript flush, usage flush; call from adapter `finally` and `reapOnAbort`. -6. CLI shutdown unification per findings/06 resources 1-2 and findings/03 resources 1-2. - -## Tests -- Worker/planner/reviewer signal wiring (fake model that blocks until abort); `waitForChecks` abort mid-sleep returns promptly; partial `connectAll` failure still closes connected clients; `openBrowser` spawn-error path (stub spawner); Disposer unit tests. - -## Done when -- One Ctrl-C cancels LLM streams, sleeps, and child processes within seconds (integration-testable with stub sleeps); every acquisition has a registered release; no fire-and-forget close without `.catch`. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/04-mcp-oauth.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/04-mcp-oauth.md deleted file mode 100644 index 899ca74e..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/04-mcp-oauth.md +++ /dev/null @@ -1,26 +0,0 @@ -# 04 — MCP client & OAuth - -> Part of [`overview.md`](overview.md). Depends on: 03 (Disposer/sleep primitives useful here). **Blocked on owner decision: inbound-HTTP scope carve-out (see overview Risks).** -> Findings: [`findings/05-mcp-openrouter-credentials-agent-config.md`](findings/05-mcp-openrouter-credentials-agent-config.md) (mcp/ + oauth sections), [`findings/07-resource-lifecycle-sweep.md`](findings/07-resource-lifecycle-sweep.md) (process items 1-2), [`findings/03-cli-config.md`](findings/03-cli-config.md) (arch 2, portability 1). - -## Files to change -- `packages/aitm/src/mcp/mcp-client.ts` — `:76-77` no connect timeout (hang-forever); `:135-149` close not time-boxed, `terminate()` unreachable; `:80-99` pid snapshot lost on mid-handshake failure; `:73` `buildClientConfig` outside try; `:69-101` sequential connects; `:206-209` sanitized-name collisions. -- `packages/aitm/src/mcp/oauth.ts` — missing PKCE (`:282-293,343-348`); unvalidated callback cast (`:234,254-256`); wrong derived server URL (`:325` + `cli/commands.ts:969-971`); template path bug (`:107-109`); `closeAllConnections` (`:199-206`); callbackUrl port ignored (`:272-276`); token response unvalidated (`:362-373`); state-mismatch silent hang (`:237-245`); dead code (`:54-58,222-226,271`). -- `packages/aitm/src/mcp/tool-search.ts:184-186,200` — non-executable deferred tool loop; soft cast. -- `packages/aitm/src/cli/commands.ts:967-987,976` — OAuth endpoint inference belongs in `mcp/oauth.ts`; `.js` import specifier breaks Deno-from-source. -- `packages/aitm/src/templates/*.html` — dead assets (never copied to dist); owner decision: delete + inline fallback, or add build copy step. - -## Steps -1. Resolve the scope decision first (inbound-HTTP carve-out in CLAUDE.md vs dropping remote-OAuth). Everything below assumes keep-with-carve-out; if dropped, delete `oauth.ts` + `mcp-login` instead. -2. MCP client: add `connectTimeoutMs`/`closeTimeoutMs` to `McpClientInit`; parallel `Promise.allSettled` connects; move `buildClientConfig` inside try; snapshot pid right after `createClient` resolves; time-box close batch then always `terminate()`; warn on post-sanitization name collisions. -3. OAuth correctness: S256 PKCE pair; validate callback (`code` or `error` present); validate `access_token` non-empty; RFC 8414 metadata discovery replacing hardcoded `/oauth/authorize`+`/oauth/token` (move endpoint derivation from `commands.ts` into `oauth.ts`); pass original server URL through `OAuthOptions`; honor `callbackUrl` port; log state mismatches; `closeAllConnections()` in `stop()`; `fileURLToPath(new URL(...))` inside try; delete dead `detectRuntime`/`ServerImpl`/`rejecter` paths. -4. `tool-search`: distinct "not executable" message for `!baseExecute`; generic wrapper type instead of `as AnyTool`. -5. Fix the dynamic import specifier to `'../mcp/oauth.ts'`. -6. Templates decision: default recommendation — delete HTML files, keep inline `getDefaultHtml`. - -## Tests -- Rewrite `oauth.test.ts` against injected server/browser seams (today it spawns a real browser and binds real ports — see findings/05 test item): state validation, callback parsing, PKCE presence, token exchange, timeout, mismatch logging. -- mcp-client: connect timeout expiry closes the client; partial-failure close; name-collision warning. - -## Done when -- No MCP/OAuth path can hang the process forever; OAuth is OAuth-2.1-conformant (PKCE + discovery); `mcp-login` works under Deno; zero real network/browser use in unit tests. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/05-loop-flows.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/05-loop-flows.md deleted file mode 100644 index 0141534c..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/05-loop-flows.md +++ /dev/null @@ -1,32 +0,0 @@ -# 05 — Loop flows: start / merge-pr correctness & unification - -> Part of [`overview.md`](overview.md). Depends on: none (03 makes the signal work easier but isn't required). -> Findings: [`findings/01-loop.md`](findings/01-loop.md) (all bug + arch items not taken by slice 03/10). - -## Files to change -- `packages/aitm/src/loop/take-over-flow.ts` — `:228-236` unhandled `'no-changes'` → up to 30 wasted coding-tier passes (HIGH); `:364-421` hand-rolled CI-fix duplicating `runFixSession` without compaction/memory/usage/guards; `:186-193` once-only review grace; `:197,239-257` no addressed-thread dedup; `:211,228` dead `'cancelled'` branch; `:167-171,312` iteration accounting. -- `packages/aitm/src/loop/ci-fix.ts:179` — `prContext.clear(pr)` wipes `addressed_threads.json` (loop-termination dedup); clear only `ci/`/`comments/` subdirs. Also `:383,391` stale rebase stderr; `:378-381` unchecked `git rebase --abort`. -- `packages/aitm/src/loop/self-review.ts:162-177` — Worker `'error'` masked as `{ kind: 'clean' }`; surface as own outcome. -- `packages/aitm/src/loop/run-loop-adapter.ts:1140-1183` — `discoverSpecialists` outside try + floating `.then()` → poisoned memoized promise blocks all later workers; `:1539` plain push where siblings use `--force-with-lease`; `:693` `PlanGraph.validate` throw → graceful blocked. -- `packages/aitm/src/loop/work-loop.ts:1096-1105` vs `stage-handlers.ts:158` — prPerTask ignores `adminMerge` + `maxCiFixAttempts`; route both modes through one policy. -- `packages/aitm/src/loop/stage-handlers.ts:155` — grace sleep on every waiting-ci pass; add once-guard. -- `packages/aitm/src/loop/merge-flow-adapter.ts:30` — merge-pr subagents skip `bashRules`, ProcessManager, `applyHooks` (issues #113/#121); also no usage/budget seam (#190). - -## Steps -1. Add the `'no-changes'` guard to take-over's CI-fix result handling (mirror `ci-fix.ts:194-201`); regression test first — `take-over-flow.test.ts` has zero coverage of this kind. -2. Scope `prContext.clear`: new `clearCi(pr)`/`clearComments(pr)`; keep `addressed_threads.json`. -3. Self-review: return `'error'` outcome distinct from `'clean'`; caller treats as unclean/blocked. -4. Wrap specialist discovery in try/catch with `.catch` on the announce; a discovery failure degrades to empty roster, never poisons the run. -5. Unify CI policy: extract one `ciOutcomePolicy` used by stage machine and prPerTask (`adminMerge` timeout override + `maxCiFixAttempts` cap). -6. Unify take-over pipeline: replace `take-over-flow.ts:364-421` with `runFixSession`; add `freshThreads`-style dedup + re-arm review grace after each push; fix iteration accounting; type ci status as `CiState`, handle `'pending'`. -7. merge-flow parity: pass `bashRules`, ProcessManager, `applyHooks`, and an `onUsage`/budget seam through `merge-flow-adapter` + `TakeOverSubagents`. -8. Small fixes: `--force-with-lease` on `openPr` push; graceful blocked on `PlanGraph.validate` throw; fresh stderr in second-attempt rebase abort; check `rebase --abort` exit code. - -## Tests -- `take-over-flow.test.ts`: no-changes guard, thread dedup, pending status, grace re-arm, iteration counts. -- `work-loop.test.ts`: adminMerge + fix-attempt cap on prPerTask path. -- `merge-flow-adapter.test.ts`: bashRules/hooks/usage plumbing asserted. -- `ci-fix.test.ts` / `pr-context-store.test.ts`: clear scoping. - -## Done when -- `aitm merge-pr` and `aitm start` share one CI-fix pipeline, one thread-dedup, one merge policy; no path can burn 30 no-op LLM passes; an errored review can't masquerade as clean. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/06-github-client.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/06-github-client.md deleted file mode 100644 index 7fd0669a..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/06-github-client.md +++ /dev/null @@ -1,27 +0,0 @@ -# 06 — GitHubClient robustness - -> Part of [`overview.md`](overview.md). Depends on: none (03 adds the timeout/signal plumbing; don't duplicate it here). -> Findings: [`findings/04-github-state-workspace-fs.md`](findings/04-github-state-workspace-fs.md) (bugs 3-8, 12, 13; arch 1-3, 5, 6). - -## Files to change -- `packages/aitm/src/github/github-client.ts` — all items below. -- `packages/aitm/src/github/errors.ts` — dead domain errors; wire them in. -- `packages/aitm/src/github/check-tolerance.ts:74` — memoize `envRules()`. - -## Steps -1. `defaultRunCmd` (`:49-58`): detect `err.code === 'ENOENT'` → throw `GhCliMissing`; surface `shortMessage` instead of flattening to `{exitCode:1, stderr:''}`. Wire the other domain errors (`GhAuthRequired`, `PrNotFound`) at their natural throw sites or delete them — the file header promises "always domain errors". -2. `waitForChecks` (`:236-278`): tolerate N consecutive transient poll failures before throwing; recognize "no checks reported" (non-zero exit + empty stdout) as an empty row set entering `CHECKS_EMPTY_GRACE_MS`; anchor the budget on `Date.now()` so gh latency and the initial wait count. -3. Kill `NODE_ENV === 'test'` instant-sleep (`:70-73`); require explicit `AITM_INSTANT_SLEEP`. -4. `failedRunIds` (`:313-327`): filter by head SHA server-side or paginate past `--limit 30`. -5. GraphQL pagination (`:432-434, 476-477`): append the current page's nodes before the non-advancing-cursor break; log on `MAX_REVIEW_THREAD_PAGES` truncation. -6. Merge-conflict classifier (`:572`): drop bare `conflict` from the regex. -7. `createPr` (`:218-220`): ensure labels once per run (cache like `cachedRepoMeta`). -8. `defaultBranch` (`:162-175`): Zod schema like every sibling. -9. Split for testability (SRP): extract `checks-poller.ts` (poll/backoff/tolerance policy) and `review-threads.ts` (GraphQL pagination) from the 857-line class; transport (`runCmd`) stays. Keep this split small — the full arch pass is slice 10. -10. Memoize `check-tolerance` env parsing per process. - -## Tests -- `github-client.test.ts` (+ new paired tests for split modules): ENOENT → `GhCliMissing`; transient-failure tolerance; "no checks reported" grace; SHA-filtered run lookup; cursor-guard page retention; conflict-regex negative case (`label conflict`); NODE_ENV no longer affects sleeps. - -## Done when -- A missing `gh`, a network flake, a checkless PR, and a >30-run branch all produce correct behavior instead of empty-message throws, aborted 2-hour waits, hard-fails, or silent `[]`. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/07-subagents-orchestrator.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/07-subagents-orchestrator.md deleted file mode 100644 index 11fb7e5a..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/07-subagents-orchestrator.md +++ /dev/null @@ -1,31 +0,0 @@ -# 07 — Subagents & Orchestrator - -> Part of [`overview.md`](overview.md). Depends on: none. **Carries owner decision: delete or wire the agent-as-tool path.** -> Findings: [`findings/02-subagents-orchestrator.md`](findings/02-subagents-orchestrator.md) (all items not taken by slice 03). - -## Files to change -- `packages/aitm/src/subagents/planner.ts:80-99`, `reviewer.ts:133-139`, `worker.ts:289-298`, `planner-scouts.ts:143-155` — copy-pasted init forwarding; planner drops `prepareStep`+`providerOptions`, reviewer drops `providerOptions`. -- `packages/aitm/src/subagents/reviewer.ts:283-292` — `git add -A` sweeps stray edits into thread-fix commits. -- `packages/aitm/src/subagents/worker.ts:653-676,686-694` — verify-fix pass: committed files missing from `delivery.changes`; stale `priorHandle` instead of `planned.handle`. -- `packages/aitm/src/subagents/worker.ts:797-801,1364-1368` — porcelain parsing breaks on renames/quoted paths; use `--porcelain -z`. -- `packages/aitm/src/subagents/worker.ts:1170` etc. — `Date.now()` toolCallId collisions; counter or `randomUUID()`. -- `packages/aitm/src/orchestrator/orchestrator.ts:793-806` — `refineCommitMessage` no fallback → empty `git commit --amend -m` fails the group; fall back to `draftCommitMessage`, strip fences. -- Injection surfaces: `worker.ts:1430-1439→713-721` (verify output as trusted task text), `prompts/slots.ts:66-69` (defuse only own envelope), `orchestrator.ts:816-819,927-929` (uncapped interpolation). -- Decision: `orchestrator/subagent-tools.ts` + `Orchestrator.build` (~400 LOC, zero production callers, already drifted — unmetered/undeadlined). Default recommendation: **delete** the agent-as-tool path; WorkLoop drives roles directly. If kept instead: forward `timeout`/`onUsage`/`formatCommand`/`providerOptions`, clamp `maxPrs`, fix the prompt/tool-surface contradiction. - -## Steps -1. Extract one `forwardInit` helper used by all four create sites; or better, per-role init types so unsupported fields are compile errors (`factory.ts:51-93` grab-bag). -2. Reviewer: stage only thread-edited paths (or `discardStrayEdits` between threads). -3. Worker verify-fix: derive `extraChanges` from tree diff; thread `planned.handle` into the fix pass. -4. Porcelain `-z` parsing helper (one place, two callers). -5. `refineCommitMessage` total-function fallback mirroring `composePr`. -6. Injection: route `verifyOutputTail` through a `data` envelope (like `review-comment`); `defuseEnvelopeTags` defangs ALL known envelope/reminder tags; cap orchestrator prompt interpolations at `MANIFEST_FIELD_MAX`. -7. Resolve the orchestrator dead-path decision; if delete — also remove `ORCHESTRATOR_ROLE_PREFIX`, `resolveMaxSteps`, dead `SubagentToolDeps` export, and their tests. -8. Small: `summarizeReviewerResult` includes partial resolution count; explore tool gets `timeout` + usage sink (`makeAgentTool` seam in compat). -9. **Design stance — no step caps.** Do NOT lower `EDITOR_MAX_STEPS` or add step limits anywhere (the audit suggested a backstop; rejected — #266 removed step caps deliberately so agents can run long). Runaway protection comes from per-step timeouts and the run-level cost/token ceiling (#190) instead; the explore/orchestrator usage-sink gaps in this slice and slice 05's merge-pr budget seam are what actually close that hole. - -## Tests -- Planner/reviewer forwarding (field-drop regression); reviewer stray-edit isolation; verify-fix tree-diff delivery; rename-porcelain parsing; empty/fenced refined commit message; envelope defusing for foreign tags. - -## Done when -- No `SubagentInit` field is silently dropped; thread commits contain only thread edits; a bad model response can't fail finalize; repo-derived text can't forge trusted prompt regions; the orchestrator module contains no unwired duplicate path. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/08-compaction-observability.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/08-compaction-observability.md deleted file mode 100644 index bd45ce98..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/08-compaction-observability.md +++ /dev/null @@ -1,30 +0,0 @@ -# 08 — Compaction guarantee & observability wiring - -> Part of [`overview.md`](overview.md). Depends on: none. -> Findings: [`findings/06-observability-logger-compaction-plan-tools.md`](findings/06-observability-logger-compaction-plan-tools.md) (bugs 2-4, 7-12; arch 1-5; tests 1-2), [`findings/05-mcp-openrouter-credentials-agent-config.md`](findings/05-mcp-openrouter-credentials-agent-config.md) (openrouter + agent-config items). - -## Files to change -- `packages/aitm/src/compaction/compaction-step.ts` — `:144-152` prune path can still overflow the window (HIGH); `:91,204-213` raw `JSON.stringify` crash on circular/BigInt (reuse `compactor.ts` `safeStringify`); `:131-134` original task brief lost to summarization; `:85-90` re-summarize every step (cache keyed on message-array length). -- `packages/aitm/src/logger/logger.ts:40` — `new Logger(...)` has zero production callers: the whole structured-logging module is dead code and every `logger?.warn` a no-op. Construct in `cli/commands.ts`, thread through the run; pass at all four `buildCompactionStep` sites (`run-loop-adapter.ts:1275-1279,1378-1382`, `ci-fix.ts:275`, `self-review.ts:211`). -- `packages/aitm/src/tools/datetime.ts:41-50` — returns UTC labeled with the requested timezone; return `formatter.format(date)` alongside ISO. Fix the test that bakes it in (`datetime.test.ts:23`). -- `packages/aitm/src/plan/schema.ts:72-76` — `.min(1)` on groups (inside the schema-retry loop); `plan-markdown.ts:46-53` — surface orphan task lines / unknown complexity tags. -- `packages/aitm/src/observability/run-step.ts:72-78` — unknown task id → `undefined`, clamp fallback. -- `packages/aitm/src/tools/github-thread-tool.ts:46-48` — error string on missing body. -- `packages/aitm/src/tools/web-fetch.ts:235-239` — truncated flag on exact-cap stream. -- `packages/aitm/src/openrouter/model-limits.ts:152-158` — `maxOutputTokens` in `hasGap`; shared `fetchCatalog` helper for `client.ts:109-111`/`reference-catalog.ts:35-39` (with `AbortSignal.timeout` from slice 03). -- `packages/aitm/src/credentials/credentials.ts:60` — explicit OpenRouter baseURL should still count as on-OpenRouter. -- `packages/aitm/src/agent-config/` — absolute out-of-repo stylePath expansion root (`agent-config-detector.ts:81-94`); trailing-punctuation `@import` capture (`expand-imports.ts:144`); warn on non-ENOENT readdir (`:118`). -- `packages/aitm/src/state/transcript-store.ts:100` — `console.debug` → Logger/onWarn (stdout contract). - -## Steps -1. Compaction: after prune, re-estimate; fall through to summarize when still over budget; escalate summarize → hard-truncate-oldest until it provably fits (post-compaction verification). Keep run's first user message verbatim ahead of any summary. Guard `estimateTokens` with `safeStringify`. Cache compacted result. -2. Wire Logger into production + the four compaction sites; extract the shared cycle-safe serializer (`logger.ts:146-165` vs `compactor.ts:203-213`, both cite #251). -3. Land the tool/plan/openrouter/credentials/agent-config point fixes above. - -## Tests -- Compaction: prune-still-over-budget, circular/BigInt message, brief-preservation, cache-hit. -- Logger-wired smoke: compaction warning actually reaches stderr. -- datetime timezone output; plan `.min(1)` retry; catalog timeout. - -## Done when -- Context can never be sent overflowing; the structured logger is live in shipped runs; every point fix has a regression test. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/09-cli-config-ux.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/09-cli-config-ux.md deleted file mode 100644 index 9e81951e..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/09-cli-config-ux.md +++ /dev/null @@ -1,34 +0,0 @@ -# 09 — CLI/config paper cuts & missing UX - -> Part of [`overview.md`](overview.md). Depends on: none. -> Findings: [`findings/03-cli-config.md`](findings/03-cli-config.md) (bugs 5-13; arch 5-7; capabilities). - -## Files to change -- `packages/aitm/src/cli/args.ts` — `:270-277` no `--` end-of-options sentinel (goals starting with `-` unrepresentable); `:300-313` branch-name validation misses control chars + bare `@`; `:11,16` null-arm schema drift; `:434-439` vs `:373-379` inconsistent `--`-value grammar between `profile set` and `config set`. -- `packages/aitm/src/cli/cli.ts:163-174` — help drifted: `--pr-per-task`, `--max-fix-attempts`, `--max-iterations`, `moonshot` preset undocumented; generate HELP_TEXT from the flag tables. -- `packages/aitm/src/cli/commands.ts` — `:552-557` idempotent start re-run drops persisted criteria (fall back to `state.readGoal().criteria`); `:1284` takeover state hardcodes `agentConfigFile: 'CLAUDE.md'`; `:874-883` `ttyConfirm` ignores AbortSignal; `:203-208` `drainStdin` hangs on interactive TTY. -- `packages/aitm/src/config/config-writer.ts:41-47` — `unset` skips `CONFIG_KEYS` validation. -- `packages/aitm/src/config/config-loader.ts:508-543` — stale top-level `baseURL` overrides an active profile's baseURL → key sent to wrong host; profile-supplied key ⇒ profile baseURL wins (or warn). -- `packages/aitm/src/config/` shared helpers — `parseValue`/`splitKey`/dotted get-set/`isNotFound`/`formatZodError` triplicated across writer/profiles/loader; extract `config/json-file.ts` + dotted-path util (already diverged once). -- Warn seams: `commands.ts:335`, `config-loader.ts:124` write to bare `process.stderr` instead of ctx stderr. - -## New capabilities (from findings) -- `aitm config list --effective` — print merged `ResolvedConfig` with per-key source labels (profile/global/env/default). -- Env-var overrides for common run settings (`maxSessions`, `logLevel`, …) so CI wrappers don't write files. -- `profile rename` + profile-name validation (validation itself lands in slice 02). - -## Steps -1. Add `--` sentinel across all subcommands; unify the twin-command grammar; then the low-risk parser fixes (branch-name regex, null-arm narrowing). -2. Help-text generation from flag tables (kills the drift class, not just today's instances). -3. Point fixes in commands/config-writer/config-loader per list above. -4. Extract shared json-file/dotted-path helpers (second-real-caller rule is satisfied three times over). -5. Implement `config list --effective`, env overrides, `profile rename`. - -## Tests -- `args.test.ts`: `--` handling per subcommand, hostile branch names. -- `commands.test.ts`: criteria fallback on re-run, agentConfigFile provenance, ttyConfirm abort, drainStdin TTY error. -- `config-writer/profiles/config-loader` tests: unset validation, precedence warning, shared-helper behavior preserved. -- Help snapshot test asserting every parsed flag appears in help. - -## Done when -- Every accepted flag is documented and every documented flag accepted; profile activation can't silently send a key to the wrong host; goals starting with `-` work. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/10-architecture-refactors.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/10-architecture-refactors.md deleted file mode 100644 index 5307df23..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/10-architecture-refactors.md +++ /dev/null @@ -1,29 +0,0 @@ -# 10 — Architecture refactors - -> Part of [`overview.md`](overview.md). Depends on: 01-09 (moves code they touch — do last). -> Findings: [`findings/08-architecture-sweep.md`](findings/08-architecture-sweep.md) (all), plus SRP items from [`findings/01-loop.md`](findings/01-loop.md), [`findings/02-subagents-orchestrator.md`](findings/02-subagents-orchestrator.md), [`findings/06-observability-logger-compaction-plan-tools.md`](findings/06-observability-logger-compaction-plan-tools.md). - -Every dependency cycle found is a shared-TYPE cycle, not a logic cycle — two moves dissolve almost all of them. - -## Steps (ordered) -1. **Extract leaf `src/domain/`**: `PrGroup`, `Task`, `TaskComplexity`, `Role`, `WorkerDelivery`, tool I/O types. Dissolves state↔plan, state↔subagents, tools↔subagents, config↔credentials↔mcp cycles (findings/08 §2). Pure type moves; no behavior change. -2. **One composition root**: new `src/composition/` takes the wiring halves of `cli/commands.ts` (1307 LOC — constructs 8 services + `defaultRunLoop`) and `loop/run-loop-adapter.ts` (2049 LOC, imports 17/19 dirs). `RunLoopInput`/`RunMergeFlowInput` move out of `cli/` — kills the cli↔loop cycle. CLI returns to "arg parsing and exit codes only"; presentation helpers → `cli/format.ts`. -3. **Hoist default constants** into config-adjacent leaves (`DEFAULT_MAX_CI_FIX_ATTEMPTS`, `DEFAULT_LLM_STEP_TIMEOUT_MS`, `DEFAULT_MCP_DEFER_TOOLS_OVER`) so `config/` never imports upward (config-loader.ts:17-21). -4. **Module splits** (each with its paired test moving along): - - `run-loop-adapter.ts` → tool-resolution / subagent-session (the ~60-line ×4 setup litany → `buildSubagentSession`) / planner-wiring; delete the adapter-local duplicate `github` tool (keep `tools/github-thread-tool.ts`). - - `worker.ts` (1484) → editor-fanout + git commit phase + verify gate. - - `work-loop.ts` (1320) → prPerTask mode out. - - `orchestrator.ts` → `pr-body.ts` (~450 lines of text machinery). - - `step-progress.ts` (435) → format/sink/renderer. - - `config-loader.ts` (640) → `claude-code-config.ts` reader. - - `coding-style.ts` — inject `OnUsage` instead of importing from subagents (layering inversion). -5. **Dedup util extractions**: `describeError` (work-loop/run-loop-adapter), fs-safe `sanitize` (3 variants in state/), cycle-safe serializer (logger/compactor — done in slice 08 if already landed), `detectRuntime` (oauth/llm-fetch). -6. **Packaging hygiene**: exclude `src/testing` from `tsconfig.build.json`; drop web-search internals (`decodeDdgHref`, `parseDuckDuckGoHtml`, `DEFAULT_STEALTH_HEADERS`, `DEFAULT_IMPERSONATE_TARGETS`) from `index.ts` barrel; resolve templates decision (slice 04). -7. **Portability policy**: decide `import process from 'node:process'` sweep (16 files) vs documenting Deno-via-npm-compat only; apply consistently. -8. **CLAUDE.md refresh**: module map (10 of 19 dirs undocumented), provider-wiring invariant ("credentials + openrouter, presets in config"), testing claim (see slice 11), inbound-HTTP carve-out (per slice 04 decision), atomic-write duplication note vs `ai-claude-compat`. - -## Tests -- No new behavior — the bar is: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint` green after every numbered step (each step is a separate commit/PR-able unit); import-cycle check (e.g. `madge --circular`) clean at dir level. - -## Done when -- Zero dir-level import cycles; one composition root; no shipped file >800 LOC with multiple reasons to change; CLAUDE.md matches the code. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/11-tests-ci-docs.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/11-tests-ci-docs.md deleted file mode 100644 index 3cfe7bc3..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/11-tests-ci-docs.md +++ /dev/null @@ -1,29 +0,0 @@ -# 11 — Tests, CI & docs closure - -> Part of [`overview.md`](overview.md). Depends on: 01-10 (this closes what they didn't cover). -> Findings: test sections of all eight findings files; [`findings/08-architecture-sweep.md`](findings/08-architecture-sweep.md) §4. - -## Files to change -- Missing pairs: `src/github/errors.test.ts`, `src/github/schema.test.ts`, `src/credentials/defaults.test.ts` (or amend the CLAUDE.md rule for type/constant-only files — pick one, apply consistently). -- `src/mcp/oauth.test.ts` — full rewrite (slice 04 owns it; verify done). -- `src/testing/temp-repo.ts:19` — `git init -b main` (env-independent branch name). -- `src/index.test.ts:5-23` — assert the exact public surface (presence AND absence) so drift fails. -- `.github/workflows/ci.yml:39-44` + CLAUDE.md — reconcile the "tests pass under both `bun test` and `node --test`, enforced by CI" claim with reality (Bun job skips tests due to oven-sh/bun#5090): either restore a scoped `bun test` job or amend the claim. - -## Coverage gaps to close (if their slice didn't) -- Two-store lock contention; `waitForChecks` transient failure + no-checks grace (slice 01/06). -- `take-over-flow` no-changes; prPerTask adminMerge (slice 05). -- Worker outer-abort signal wiring; scout runner real wiring (slice 03/07). -- `error-reporter` DSN-present branch (`beforeSend` registration). -- Compaction overflow + circular-message regressions (slice 08). -- `runMcpLogin` through an injectable `performOAuth` seam (slice 04/09). -- Failure-path cleanup tests from findings/07: `openBrowser` spawn error, partial `connectAll` leak, oauth stop under keep-alive, undici agent teardown. - -## Steps -1. Sweep each landed slice's "Tests" section against what actually merged; write the misses. -2. Add the three trivial missing pairs (or the documented rule amendment). -3. Fix temp-repo branch pinning; tighten index surface test. -4. Resolve the CI/CLAUDE.md testing claim. - -## Done when -- Every shipped `.ts` under `src/` has a paired test (or the rule explicitly exempts type/constant-only files); CI configuration and CLAUDE.md tell the same story; all coverage gaps listed above have a named test. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/01-loop.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/01-loop.md deleted file mode 100644 index de0c9fde..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/01-loop.md +++ /dev/null @@ -1,59 +0,0 @@ -# Findings — loop/ - -> Raw report from parallel audit agent. Scope: `packages/aitm/src/loop/` (12 modules + tests, cross-module contracts verified). - -## Bugs / correctness - -- [severity: high] [category: bug] `take-over-flow.ts:228-236` — a `'no-changes'` WorkerResult from the CI-fix pass is unhandled (only `'blocked'`/`'error'` are checked), so it falls through to `pushedSomething = true`, force-pushes nothing, and re-loops up to `maxIterations` (30) coding-tier LLM passes on a red PR — the exact burn ci-fix.ts:194-201 explicitly blocks on ("'no-changes' here is a contradiction"); add the same guard. -- [severity: med] [category: bug] `ci-fix.ts:179` (with `src/state/pr-context-store.ts:42-44`) — `runFixSession` calls `prContext.clear(pr)`, which `rm -rf`s the whole `pr//` dir *including* `addressed_threads.json`, silently wiping the addressing-reviews dedup that stage-handlers.ts:240-244 depends on for loop termination; after a CI failure mid-review-cycle, replied-but-unresolved threads are re-fed to the Reviewer (duplicate replies) — clear only the `ci/`/`comments/` subdirs. -- [severity: med] [category: bug] `self-review.ts:162-177` — a Worker `'error'` result (provider crash, step timeout) with verify green-or-unrun returns `{ kind: 'clean' }` and logs "nothing to fix": an errored review pass is indistinguishable from a genuinely clean diff, defeating the pre-PR gate; surface `worker.kind === 'error'` as its own outcome (or `unclean` with the error). -- [severity: med] [category: bug] `run-loop-adapter.ts:1140-1183` — `await discoverSpecialists(input.cwd)` (line 1142) sits *outside* the try/catch, and the roster announce at 1177 is `void ...then()` with no `.catch`: a `loadAgents` rejection (fs permission, malformed agent file) is an unhandled promise rejection AND the memoized rejected `specialistsPromise` makes every later `await specialistRoster()` (line 1402) throw, blocking every subsequent worker pass for the rest of the run; wrap discovery in the try and add `.catch`. -- [severity: med] [category: bug] `work-loop.ts:1096-1105` vs `stage-handlers.ts:158` — the prPerTask `autoMergeFlow` ignores `adminMerge` on a `CiFailed` poll timeout (the throw propagates → group blocked) and applies no `maxCiFixAttempts` budget (exactly one fix pass then throw), diverging from the stage machine's documented `--admin` timeout-override and issue-#128 cap; route both modes through one policy. -- [severity: med] [category: bug] `work-loop.ts:395,445` + `stage-handlers.ts:155` — `signal` is never threaded into stage handlers, `waitForChecks` (polls up to 2h, github-client.ts:94), or the 2-minute `REVIEW_COMMENTS_GRACE` sleep; `WorkLoop.run` only checks abort at batch boundaries after `Promise.allSettled`, so a single SIGINT can take *hours* to yield `cancelled` — pass the signal into `StageDeps`/`waitForChecks`/sleep. -- [severity: low] [category: bug] `take-over-flow.ts:211,228` — `ciStatus === 'cancelled'` is dead code: `observeCheckStatus` returns `CiResult.state`, which is `CiState = 'success'|'failure'|'pending'` (github-client.ts:109), never `'cancelled'`; and an unexpected `'pending'` silently burns a cooldown iteration doing nothing — type the variable as `CiState` and handle `'pending'` explicitly. -- [severity: low] [category: bug] `take-over-flow.ts:167-171,312` — iteration accounting is inconsistent: a first-iteration happy-path break reports `iterations: 0` on `merged`, while merged-after-exhaustion reports `maxIterations`; blocked branches mix both conventions. -- [severity: low] [category: bug] `take-over-flow.ts:186-193` — `reviewGraceDone` fires only once per flow; review bots that re-review after a CI-fix push re-greens are merged past without the grace window that exists precisely for them. -- [severity: low] [category: bug] `take-over-flow.ts:197,239-257` — no addressed-thread dedup (no equivalent of stage-handlers' `freshThreads`): a replied-but-unresolved thread is re-fed to the Reviewer on every iteration, up to 30 duplicate passes/replies on `aitm merge-pr`. -- [severity: low] [category: bug] `stage-handlers.ts:155` — the 2-minute grace sleeps on *every* pass through waiting-ci (each ci-fix loop-back and each resume re-entry), unlike take-over's once-guard — pure added latency per fix cycle. -- [severity: low] [category: bug] `run-loop-adapter.ts:1539` — `openPr` pushes with plain `git push -u origin `; a resumed group whose branch was locally rewritten (a prior ci-fix rebase whose push failed) fails the plain push and blocks the group, while every other push path uses `--force-with-lease`. -- [severity: low] [category: bug] `run-loop-adapter.ts:693` — `PlanGraph.validate(groups)` on a resumed (possibly corrupted) state.json throws out of `runLoopAdapter` as an unhandled exception instead of a graceful `{ kind: 'blocked' }`. -- [severity: low] [category: bug] `ci-fix.ts:383,391` — a second-attempt non-conflict `continue` failure aborts with `manualReason` built from the *first* rebase's stderr, reporting a stale error to the operator. - -## Resource cleanup - -- [severity: med] [category: resource] `run-loop-adapter.ts:639-642,761-767` — `mcp.close()` runs only when `mcpConnected === true`: a `connectAll()` that throws *partway* (some stdio children already spawned) never sets the flag, so the finally skips close and the connected transports/child processes leak on normal (non-abort) unwinding; also a `seams.makeMcp`-supplied manager is never closed. `close()` is documented idempotent — call it unconditionally in the finally. -- [severity: med] [category: resource] `run-loop-adapter.ts:1189,1200,1514,1776` — `workerHandles` / `ciFixHandles` retain full `ModelMessage[]` conversations per group for the whole run and are never pruned when a group reaches a terminal stage; a long many-group run accumulates every conversation in memory — delete on merged/blocked. -- [severity: low] [category: resource] `run-loop-adapter.ts:631-632` — `reapOnAbort`'s `void mcp.close()` floats with no `.catch`; an abort-time close rejection becomes an unhandled rejection during shutdown. -- [severity: low] [category: resource] `ci-fix.ts:378-381` — `abortAndBlock` ignores a failed `git rebase --abort`; the checkout is then left mid-rebase and the next fix session's Worker edits a mid-rebase tree with no detection — check the abort's exit code and fold it into the blocked reason. -- [severity: low] [category: resource] `run-loop-adapter.ts:1012` — `plannerRecorder?.end()` is skipped when `runPlanner` throws (only the heartbeat is in the finally), leaving a dangling open transcript for a stage documented as never-resumed; same skip pattern at 1349/1515/1773 (arguably intentional for resumable stages — the planner one is not). -- [severity: low] [category: resource] `work-loop.ts:384,458` — `groupStartedAt` entries are never deleted after a group finishes (bounded by plan size; minor). - -## Architecture - -- [severity: high] [category: arch] `run-loop-adapter.ts` (2049 LOC) — at least six reasons to change in one module: tool resolution/partial-fill (356-400, 1954-2022), MCP deferred-tool mounting (1853-1951), branch naming (774-832), planner wiring + scout survey (874-1026), budget check (1033-1058), the orchestrator bridge (1120-1822), and a github glue tool (2036-2049); split into tool-resolution, subagent-session, and planner-wiring modules. -- [severity: med] [category: arch] `run-loop-adapter.ts:1354-1772` — the worker / self-review / ci-fix / reviewer bridges each repeat the same ~60-line setup litany (usage sink, memory index, transcript begin/resume, heartbeat sink, composeStepFinish, streaming renderer, onRetry, providerOptions, conditional-spread pyramid); four real callers of an unextracted `buildSubagentSession` abstraction. -- [severity: med] [category: arch] `run-loop-adapter.ts:2036-2049` vs `src/tools/github-thread-tool.ts` — two implementations of the same `github` review-thread tool with different signatures and divergent validation (the adapter copy posts `input.body ?? ''` — empty replies allowed; the tools copy rejects an empty body with `{ok:false}`); merge-flow-adapter.ts:31 uses one, run-loop-adapter.ts:1255 the other — delete the adapter-local copy. -- [severity: med] [category: arch] `take-over-flow.ts:364-421` — a hand-rolled CI-fix path duplicating ci-fix.ts's `runFixSession` but without compaction, memory, usage accounting, the `'no-changes'` guard, or coding-tier model selection (uses `workerModel` = role 'worker' instead of `modelForCapability('coding')`): `aitm merge-pr` fixes CI with a different, weaker pipeline than `aitm start` — reuse `runFixSession`. -- [severity: med] [category: arch] `merge-flow-adapter.ts:30` — `localEditTools(checkoutPath)` omits `input.resolved.bashRules`, the background ProcessManager, and `applyHooks`: `aitm merge-pr` subagents silently ignore the bash deny/allow governance (issue #113) and operator PreToolUse/PostToolUse hooks (issue #121) that `aitm start` enforces. -- [severity: med] [category: arch] `take-over-flow.ts:81-116` / `merge-flow-adapter.ts` — no `onUsage`/UsageTracker field anywhere in `TakeOverSubagents` and no budget seam in the flow, so usage reporting and the run-level cost/token ceilings (issue #190) do not apply to `aitm merge-pr` at all. -- [severity: low] [category: arch] `run-loop-adapter.ts:716` — `effectiveConcurrency` is hardcoded to `1`, making WorkLoop's batch dispatch, `checkoutMutex` (mutex.ts), and the `concurrency` dep production-dead machinery maintained only for tests. -- [severity: low] [category: arch] `run-loop-adapter.ts:743,745` — a resume mixes persisted options (`current.options.prPerTask`) with freshly-resolved CLI flags (`input.resolved.autoMerge`, `selfReview`, `mergeMethod`); rerunning with different flags half-applies them to a resumed plan with no warning. -- [severity: low] [category: arch] `work-loop.ts:341-343` vs `run-loop-adapter.ts:269-271` — `describeError` duplicated verbatim (same doc comment) in two loop modules; two real callers merit the shared util the house rules call for. -- [severity: low] [category: arch] `work-loop.ts` (1320 LOC) — WorkLoop mixes the batch driver, stage dispatch, the entire prPerTask mode (`processGroup`/`openAndMaybeMerge`, lines 532-1037), outcome accounting, and delivery-merge helpers; prPerTask is a second reason to change and splits cleanly. - -## Test pairing / coverage - -- [severity: med] [category: test] `take-over-flow.test.ts` — zero coverage of a `'no-changes'` worker result on the CI-fix path, the exact unhandled kind in the high-severity bug above. -- [severity: low] [category: test] `work-loop.test.ts` — no `adminMerge` coverage on the `autoMergeFlow`/prPerTask path, leaving the stage-machine-vs-prPerTask policy divergence unpinned. -- [severity: low] [category: test] `merge-flow-adapter.test.ts` — only 3 tests for the production wiring; the missing bashRules/hooks/usage plumbing above is unasserted. -- [severity: low] [category: test] Pairing itself is clean: all 12 modules have a paired `*.test.ts`. - -## Portability / house rules - -- No `Bun.*` APIs, no `any`, no `as unknown as`, no default exports anywhere in `src/loop/` (grep-verified) — compliant. Minor note: `self-review.ts:338` runs verify via `sh -c` (POSIX-only shell, but runtime-portable across Bun/Node/Deno per the house rule's scope). - -## Missing capabilities worth adding - -- **Deep cooperative cancellation** — thread the AbortSignal through stage handlers, `waitForChecks` polling, grace sleeps, and subagent generate calls so SIGINT cancels in seconds; today the only checks are at WorkLoop batch boundaries and take-over iteration tops. -- **Mid-group budget checkpoints** — cost/token ceilings are consulted only before dispatching a group batch (and never in merge-pr); a single group's task loop + CI-fix cycles can burn unbounded spend between checks. Check per task and per fix pass. -- **Unified start/merge-pr recovery pipeline** — route the take-over flow through `runFixSession` and a shared `freshThreads` dedup so both commands get the same no-changes guard, addressed-thread termination, tolerated-check handling, usage accounting, and fix-attempt cap. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/02-subagents-orchestrator.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/02-subagents-orchestrator.md deleted file mode 100644 index abda852a..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/02-subagents-orchestrator.md +++ /dev/null @@ -1,61 +0,0 @@ -# Findings — subagents/ + orchestrator/ - -> Raw report from parallel audit agent. Scope: `packages/aitm/src/{subagents,orchestrator}/` (+ `packages/ai-claude-compat/src` references). - -## Bugs / correctness - -- [severity: med] [category: bug] `subagents/planner.ts:80-99` — `createPlannerAgent` silently drops `init.prepareStep` and `init.providerOptions` even though `SubagentInit` carries both (worker forwards both at `subagents/worker.ts:292-294`; reviewer forwards `prepareStep` at `subagents/reviewer.ts:134` but drops `providerOptions`), so Planner compaction or OpenRouter server tools wired by a caller are silently lost; forward them, or narrow each role's init type so unsupported fields are compile errors. -- [severity: med] [category: bug] `subagents/reviewer.ts:283-292` — `commitFix` stages `git add -A`, sweeping ANY dirty file into a thread's "fixed" commit, including stray edits left by an earlier replied/wontfix thread of the same pass (no per-thread or end-of-pass stray-edit cleanup like the worker's `discardStrayEdits`); stage only paths edited for this thread or reset stray edits between threads. -- [severity: med] [category: bug] `orchestrator/orchestrator.ts:793-806` — `refineCommitMessage` uses raw model text with no validation or fallback: an empty/fenced/over-72-char response goes straight into `git commit --amend -m` (orchestrator.ts:774), where an empty message fails the whole group at finalize; fall back to `delivery.draftCommitMessage` and strip fences, mirroring `composePr`'s total-function design. -- [severity: med] [category: bug] `subagents/worker.ts:653-676` — in `commitWithVerify`, a fix pass that returns `blocked`/`error` may still have written files; if the re-verify then passes, `stageAndCommit` (worker.ts:675) commits those edits but `extraChanges` only captures `fixed.kind === 'ok'` (worker.ts:662), so committed files are missing from `delivery.changes` and hence the PR body/commit narration; derive extra changes from a tree diff instead of the fanout outcome. -- [severity: med] [category: bug] `subagents/worker.ts:653-661` with `686-694` — the verify fix pass spreads `{...input, task}` so `planManifest` continues the stale `input.priorHandle` (a previous CI-fix run's conversation) instead of `planned.handle` from the first pass of this very run, losing the just-planned manifest context the #107 continuation mechanism exists to preserve; thread `planned.handle` into the fix pass. -- [severity: low] [category: bug] `subagents/worker.ts:797-801` and `1364-1368` — `dirtyPaths`/`hasStrayEdit` parse porcelain with `line.slice(3)`, which mis-parses rename records (`R old -> new`) and git-quoted paths, so an inherited-dirty renamed file can defeat the inline-edit inference (`dirtyBefore.has(file.path)` at worker.ts:828 never matches); use `git status --porcelain -z` and parse records properly. -- [severity: low] [category: bug] `orchestrator/subagent-tools.ts:90-94` — `plannerInputSchema` lets the orchestrator's model choose any positive `maxPrs` unbounded, unlike the operator-configured cap on the direct path; clamp it against a dep-provided ceiling. -- [severity: low] [category: bug] `subagents/worker.ts:1170` (also 794, 1344, 1403, 1467; reviewer.ts:338) — `Date.now()`-based toolCallIds collide when parallel editors run `editorTouchedPath` in the same millisecond; use a counter or `crypto.randomUUID()`. -- [severity: low] [category: bug] `orchestrator/subagent-tools.ts:235` — `summarizeReviewerResult`'s error line drops the partial `resolutions` the error result deliberately carries (reviewer.ts:95), so the orchestrator model can't see threads 1..N-1 were already resolved; include the count. - -## Prompt-injection surfaces - -- [severity: med] [category: bug] `subagents/worker.ts:1430-1439` → `713-721` — `buildVerifyFixTask` embeds `verifyOutputTail` (raw stdout/stderr of repo-authored test code — a hostile repo can print directives) as trusted `task.text` interpolated unfenced into the manifest prompt (worker.ts:715); route verify output through a `data` envelope like `review-comment` (`prompts/slots.ts`). -- [severity: low] [category: bug] `subagents/prompts/slots.ts:66-69` — `defuseEnvelopeTags` defangs only the slot's own envelope, so a hostile review comment may still contain literal `specialist-guidance`/`env`/`system-reminder` tags forging trusted-looking regions inside the fence; defang all known envelope/reminder tags, not just the current one. -- [severity: low] [category: bug] `orchestrator/orchestrator.ts:816-819` and `927-929` — `buildCommitPrompt`/`buildPrPrompt` interpolate model-authored `draftCommitMessage` and per-file `summary` uncapped and unfenced (the worker caps every such field at `MANIFEST_FIELD_MAX`, worker.ts:378); apply the same slice-cap discipline. - -## Missing resource cleanup / abort propagation - -- [severity: med] [category: resource] `subagents/worker.ts:686-703` — the manifest-planning loop (`runSubagent`/`continueSubagent`) never receives `WorkerInput.signal`; only the editor fanout honors abort (worker.ts:1110), so SIGINT during the long planning phase keeps burning LLM calls to completion. Root cause: compat's `runSubagent`/`agent.generate` accepts no signal (`ai-claude-compat/src/subagent.ts:935`); plumb an abortSignal through. -- [severity: med] [category: resource] `subagents/planner.ts:46-61`, `subagents/reviewer.ts:68-83`, `subagents/planner-scouts.ts:130-136` — `PlannerInput`, `ReviewerInput`, and `ScoutAgentInit` carry no abort signal at all, so a run-level SIGINT cannot cancel planning, review-thread, or scout LLM loops (scouts additionally swallow every error via `.catch(() => null)` at planner-scouts.ts:185, including cancellation). -- [severity: low] [category: resource] `subagents/worker.ts:1019` — `runEditorFanout` never passes `controller.signal` to `runPool` even though the pool supports `options.signal` (`ai-claude-compat/src/pool.ts:16-56`), so abort is only observed inside `generateText`, not between calls. -- [severity: low] [category: resource] `orchestrator/subagent-tools.ts:64-78` — `WorkerToolDeps` has no `signal` field, so an orchestrator-tool Worker fanout is uncancellable by construction. -- [severity: low] [category: resource] `subagents/worker.ts:211, 454` — every `ok` WorkerResult retains a live `SubagentHandle` (full manifest conversation) in memory and inside the tool-result object on the orchestrator path; `toModelOutput` hides it from the model but transcript/step persistence still sees a large object. - -## Token/step accounting - -- [severity: med] [category: bug] `orchestrator/orchestrator.ts:713-747` — `Orchestrator.build` never forwards `init.timeout`/`init.onUsage` (nor `formatCommand`/`providerOptions`) into `makeWorkerTool` despite `WorkerToolDeps` accepting them (subagent-tools.ts:74-78), and `PlannerToolDeps`/`ReviewerToolDeps` cannot carry them at all — every subagent run on the orchestrator-agent path is unmetered (#114) and undeadlined (#129). -- [severity: low] [category: bug] `subagents/explore.ts:39-57` — `buildExploreTool` forwards no `timeout` and there is no usage sink in `makeAgentTool`, so explore children's tokens are invisible to the run-level cost ceiling (#190) and their steps have no per-step deadline. -- [severity: low] [category: bug] `subagents/worker.ts:1109` with `factory.ts:49` — an editor leaf runs to `EDITOR_MAX_STEPS` = 1000 with no submit tool, no compaction, and no survey-budget nudge; consider a lower leaf backstop or the manifest pass's read-only-streak reminder. - -## Architecture - -- [severity: high] [category: arch] `orchestrator/subagent-tools.ts` (whole file) and `orchestrator/orchestrator.ts:91-108, 692-747` — `Orchestrator.build`, `ORCHESTRATOR_ROLE_PREFIX`, `resolveMaxSteps`, and all three `make*Tool` wrappers have zero production callers (grep: only tests; the WorkLoop drives `runWorker`/`runPlanner`/`runReviewer` directly via `loop/run-loop-adapter.ts:954, 1303, 1441`) — ~400 lines of duplicated agent construction whose "no config drift" mirroring has already drifted (see accounting finding); delete the agent-as-tool path or actually wire it. -- [severity: med] [category: arch] `orchestrator/orchestrator.ts:99-103` vs `subagent-tools.ts:97-99` and `orchestrator.ts:141-150` — the role prompt instructs the model to loop "each ready group → worker … stop when every group is merged", but the tools bind exactly one group/pr/threads at build time behind empty input schemas, so a second `worker` call re-runs the same group; prompt and tool surface contradict each other. -- [severity: med] [category: arch] `subagents/worker.ts` (1484 lines) — manifest planning, fanout pooling/labeling, inline-edit inference, branch/stage/commit git phase, verify gate, and four prompt builders in one module; split at least the git commit phase and the verify gate into their own tested modules. -- [severity: med] [category: arch] `orchestrator/orchestrator.ts:161-649` — ~450 lines of PR-body text machinery (fenceMask, heading normalization, run-on splitting, JSON-envelope peeling, repair, fallback) live inside the Orchestrator; extract a `pr-body` module. -- [severity: low] [category: arch] `subagents/factory.ts:51-93` — `SubagentInit` is one grab-bag type where worker-only fields (`onEditorStepFinish`) and role-ignored fields coexist; per-role init types would turn silent field drops into compile errors. -- [severity: low] [category: arch] `orchestrator/subagent-tools.ts:88` — `SubagentToolDeps` aggregate exported but referenced nowhere else in src; dead export. -- [severity: low] [category: arch] `subagents/planner.ts:91-96`, `reviewer.ts:133-139`, `worker.ts:289-298`, `planner-scouts.ts:143-155` — the conditional-spread forwarding of init fields to `createSubagent` is copy-pasted four times (and is where the field-drop drift lives); extract one forwarding helper. - -## Provider / portability / house rules - -Clean: no Anthropic SDK usage anywhere in the audited files; no `Bun.*` APIs, no default exports, no `any` or `as unknown as` (worker.ts:754-768's double cast is assertion-heavy but legal under strict). - -## Test coverage gaps - -- [severity: med] [category: test] `subagents/worker.test.ts` — no test exercises `WorkerInput.signal` (outer-abort wiring + listener removal, worker.ts:990-996/1036); only the sibling-rejection abort is covered (worker.test.ts:441). -- [severity: low] [category: test] `subagents/planner-scouts.test.ts` — covers only pure helpers with stub runners; `createScoutRunner` (planner-scouts.ts:141-165), the real agent wiring and null-on-failure path, is untested. -- [severity: low] [category: test] `orchestrator/orchestrator.test.ts:344-539` — `finalizeCommit` happy/failure paths tested but not an empty or fence-wrapped refined message (the bug path at orchestrator.ts:806). - -## Missing capabilities worth adding - -- Run-wide cancellation: one AbortSignal threaded from the CLI through every subagent LLM loop (planner, reviewer, scouts, manifest pass, orchestrator generateText) — requires a `signal` parameter on compat's `runSubagent`/`agent.generate`; today only the worker editor fanout is cancellable. -- Uniform usage metering: explore children and any orchestrator-tool-path run are invisible to the run-level cost/token ceiling; an `onUsage` seam in `makeAgentTool` plus forwarding in `Orchestrator.build` would close the gap. -- A shared "untrusted text" envelope for repo-derived content (verify-command output, editor summaries, rolling context) so the fencing discipline that protects review comments and specialist files covers the remaining injection channels. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/03-cli-config.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/03-cli-config.md deleted file mode 100644 index 19c60be2..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/03-cli-config.md +++ /dev/null @@ -1,50 +0,0 @@ -# Findings — cli/ + config/ - -> Raw report from parallel audit agent. Scope: `packages/aitm/src/{cli,config}/`. - -## Bugs / correctness - -- [severity: high] [category: bug] `config-loader.ts:160-163` — A project-scope `bashRules` wholesale-replaces the user's global deny rules and its `allow` entries win first-match over `DEFAULT_BASH_RULES` (config-loader.ts:70-76), so an untrusted checked-in `.ai-task-master/config.json` can re-enable `git push --force`/`gh pr merge` for the model shell even though the same loader strips `hooks`/`formatCommand`/`verifyCommand` as untrusted (config-loader.ts:54-64); treat project `bashRules` like the other untrusted fields (strip, or merge project rules *after* global deny rules and forbid project `allow` overrides of built-ins). -- [severity: med] [category: bug] `profiles.ts:77-84, 43, 57` — Profile *names* are never checked against `FORBIDDEN_KEY_SEGMENTS` and membership uses `in`/bracket access, so `aitm profile set __proto__ baseURL x` resolves `profiles['__proto__']` to `Object.prototype` and `setDotted` (profiles.ts:239-248) writes onto `Object.prototype` (in-process prototype pollution), while `profile use __proto__`/`use constructor` pass the `name in profiles` guard (profiles.ts:43) and persist a dangling `activeProfile`; validate names with `Object.hasOwn` and reject `FORBIDDEN_KEY_SEGMENTS` — ironic given provider-presets.ts:52-56 fixes exactly this for presets. -- [severity: med] [category: bug] `commands.ts:689-695` — `merge-pr --no-resume` with an existing state.json calls `state.init()` with a synthesized takeover state, and `StateStore.init` unconditionally overwrites (state-store.ts:43-48), destroying an in-progress run's `prGroups`/`runId`/plan linkage; the flag's contract is only "don't trust persisted currentPr", so it should update `currentPr` in place (or refuse when `prGroups` is non-empty) instead of clobbering the whole run. The test at commands.test.ts:1101-1135 blesses the overwrite but only seeds a bare `currentPr` state, never a mid-plan run. -- [severity: med] [category: bug] `config-writer.ts:29-39` — `aitm config set openrouterApiKey --project` (likewise `formatCommand`, `verifyCommand`, `hooks`, `baseURL`, `stylePath`) succeeds, writing a secret/shell command into the repo-committable `.ai-task-master/config.json` that the loader then silently strips at run time (config-loader.ts:54-64); the writer should reject (or at minimum warn on) `UNTRUSTED_PROJECT_FIELDS` keys in project scope — export that list from config-loader and check scope-aware. -- [severity: med] [category: bug] `config-loader.ts:508-521 vs 528-543` — Base URL resolves global > profile while the key also resolves global > profile, so a stale top-level `baseURL` set via `aitm config set` silently overrides the freshly-activated profile's `baseURL` and the profile's API key is sent as a Bearer token to a *different provider's* host (e.g. z.ai key to openrouter.ai); when a profile is active and supplies the key, its baseURL should win or the mismatch should at least warn. -- [severity: med] [category: bug] `commands.ts:552-557` — On an idempotent `aitm start` re-run of an unfinished run, `args.criteria` (usually `undefined`) is passed to the loop instead of the persisted criteria, unlike `aitm resume` which restores it (commands.ts:642-646); runStart's resume branch should fall back to `state.readGoal().criteria` when the flag is absent. -- [severity: low] [category: bug] `args.ts:270-277` — There is no `--` end-of-options sentinel anywhere in the parser, so a goal/criteria/value beginning with `-` is unpassable (`aitm start "--fix the flag parser"` → usage error) and `config set ` can never store a value starting with `--` (args.ts:363-371); support the conventional `--` separator. -- [severity: low] [category: bug] `cli.ts:163-174` — Help text has drifted from the parser: `--pr-per-task` and `--max-fix-attempts` (start, args.ts:229-253), `--max-iterations` (merge-pr, args.ts:332), and the `moonshot` preset (provider-presets.ts:9) are all accepted but undocumented; regenerate HELP_TEXT from the flag tables or add the missing lines. -- [severity: low] [category: bug] `args.ts:11,16` — `StartArgs.maxSessions?: number | null` and `stylePath?: string | null` declare `null` arms the parser never produces (the 0→null mapping happens later in commands.ts:1018-1019), schema drift between the arg type and the parser; narrow the parsed type and keep `null` only in `CliOverrides`. -- [severity: low] [category: bug] `args.ts:300-313` — `isValidBranchName` misses ASCII control chars (`\s` covers whitespace only, not `\x01`–`\x1f`/DEL) and the single-`@` ref git forbids, so such a `--branch` passes validation and fails later at `git checkout -B`; extend the regex with `[\x00-\x1f\x7f]` and reject `name === '@'`. -- [severity: low] [category: bug] `config-writer.ts:41-47` — `config unset ` performs no `CONFIG_KEYS` check (unlike `set`, line 33) and silently exits 0 on a key that never existed; validate the top-level key so typos are surfaced. -- [severity: low] [category: bug] `commands.ts:1284` — `synthesizeTakeoverState` hardcodes `agentConfigFile: 'CLAUDE.md'` even when the repo only has AGENTS.md (detection happens later at commands.ts:737), persisting wrong provenance in state; derive it from the actual `detector.detect()` result. -- [severity: low] [category: bug] `args.ts:434-439 vs 373-379` — `profile set` accepts a *value* starting with `--` while `config set` rejects it (its flag loop consumes any `--` token), an inconsistent grammar between the two twin commands; unify once a `--` sentinel exists. - -## Resource cleanup / RAII - -- [severity: med] [category: resource] `cli.ts:201-209` — `process.exit(code)` immediately after `main()` can truncate buffered stdout/stderr when piped (Node does not flush async stream writes on `exit`), so long outputs like `config list` JSON or the PR-links block can be cut off in `aitm … | tee`; set `process.exitCode = code` and let the process drain, or await stream flush before exiting. -- [severity: med] [category: resource] `cli.ts:234-238` — The second-signal force path `proc.exit(128 + signo)` bypasses `reporter.flush()` (cli.ts:202) and any in-flight `atomicWrite`, losing the crash report and potentially a temp file; flush the reporter (bounded) in the force-exit branch, and remove the handlers once `main()` resolves so a late Ctrl+C doesn't print a meaningless "Cancelling" during final flush. -- [severity: low] [category: resource] `commands.ts:874-883` — `ttyConfirm` never wires the run's `AbortSignal` (CleanCtx has no `signal`, commands.ts:177-183), so the first Ctrl+C during the `aitm clean` prompt only prints "Cancelling" while readline keeps blocking; pass the signal into `rl.question(question, { signal })`. -- [severity: low] [category: resource] `commands.ts:203-208` — `drainStdin` waits for EOF with no TTY guard, so an interactive `aitm profile add x --api-key-stdin` (nothing piped) hangs silently until Ctrl+D; error out (or prompt) when `process.stdin.isTTY` is true. - -## Architecture / SRP - -- [severity: med] [category: arch] `commands.ts:1-1307` — The module map pins CLI to "arg parsing and exit codes only", but commands.ts is 1307 LOC mixing presentation (usage/cost formatting at 302-322, PR-link URL reconstruction at 270-295, model banner assembly at 235-263, secret masking/redaction at 1117-1165), business logic (style-digest orchestration via StyleDistiller at 1175-1211, takeover-state synthesis at 1235-1298, resume/supersede policy at 417-449), and wiring; split into `cli/format.ts` (or move into observability), move `defaultResolveStyle` next to StyleDistiller, and `synthesizeTakeoverState` into the loop/take-over module. -- [severity: med] [category: arch] `commands.ts:967-987` — `runMcpLogin` embeds OAuth *protocol* logic in the CLI layer: hardcoded `${origin}/oauth/authorize` / `/oauth/token` endpoint inference (no RFC 8414 discovery) and `client_id` scraped from a query param; move endpoint derivation into `src/mcp/oauth.ts` so the command is pure dispatch. -- [severity: med] [category: arch] `config-writer.ts:113-206 vs profiles.ts:239-285` — `parseValue`, `splitKey`, dotted get/set, `isNotFound`, `formatZodError`, and the readRaw JSON-object guard are duplicated nearly verbatim between ConfigWriter and ProfileManager (and `isNotFound`/`formatZodError` a third time in config-loader.ts:621-632); extract a shared `config/json-file.ts` + dotted-path helper — the duplication already diverged once (writer's setDottedKey vs profiles' setDotted have different guards). -- [severity: low] [category: arch] `commands.ts:335` and `config-loader.ts:124` — Warnings write straight to `process.stderr` (detector `onWarn`, ConfigLoader default `warn`) instead of the ctx stderr seam every other output uses, a hidden global that makes these warnings uncapturable in tests and un-redirectable; thread `ctx.stderr` into `buildDetectOpts` and pass a `warn` option when constructing ConfigLoader. -- [severity: low] [category: arch] `cli.ts:122-128` — `buildMcpLoginCtx` ignores its `ctx` argument and `MainCtx` has no `performOAuth` field, so the OAuth seam declared in `McpLoginCtx` (commands.ts:198-201) is unreachable through `main()` — which is exactly why runMcpLogin has no command-level test. -- [severity: low] [category: arch] `config-loader.ts:379-383` — `redactedMcpServers as typeof resolved.mcpServers` casts a `Record` (headers/env replaced by the string `''`) into `McpServers`, an unsound widening skirting the no-cast house rule; type the snapshot as its own redacted shape instead of reusing `ResolvedConfig`. - -## Tests / portability - -- [severity: med] [category: portability] `commands.ts:976` (also type positions 199-200, 978) — Dynamic `import('../mcp/oauth.js')` uses a `.js` specifier while every other import in the package uses `.ts`; Bun and compiled dist resolve it, but Deno (a declared supported runtime) does not map `.js` → `.ts` without sloppy-imports, so `aitm mcp-login` breaks under Deno-from-source; use `'../mcp/oauth.ts'`. -- [severity: med] [category: test] `commands.test.ts` — `runMcpLogin` has zero tests (grep finds only arg-parsing cases in args.test.ts:607-644): the endpoint inference, `client_id` query-param extraction, snippet output, and error path are all uncovered; add tests through the `performOAuth` seam (after making it injectable via `main`, see above). -- [severity: low] [category: test] `config-writer.test.ts` / `profiles.test.ts` — Prototype-pollution tests cover key *paths* only (config-writer.test.ts:292-319, profiles.test.ts:170-173); there is no test for a hostile profile *name* (`profile add/use/set __proto__`), which is exactly the hole reported above — add name-based cases. -- [severity: low] [category: test] `cli.test.ts` — No test covers the entrypoint block's exit/flush ordering (cli.ts:195-211, the IIFE is untestable by construction); extracting it into an exported `runEntrypoint(proc)` would let the flush-before-exit and crash-path (exit 1) behavior be asserted. - -Test pairing itself is clean: all 9 modules across both directories have a paired `*.test.ts` (255 tests total), and no `Bun.*` APIs, `any`, `as unknown as`, or default exports exist in either directory. - -## Missing capabilities worth adding - -- An `aitm config list --effective` (or `config resolve`) that prints the merged `ResolvedConfig` with per-key source labels — today `config list` shows one raw file per scope, and the only way to see actual precedence outcomes (profile vs global vs env vs default) is to start a run and read the snapshot. -- A `--` end-of-options separator across all subcommands, unlocking goals/criteria/config values that begin with `-` (currently unrepresentable). -- Profile-name validation plus a `profile rename`; and env-var overrides for common run settings (only `OPENROUTER_API_KEY`/`OPENROUTER_BASE_URL` exist — CI wrappers cannot set e.g. `maxSessions`/`logLevel` without writing files). diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/04-github-state-workspace-fs.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/04-github-state-workspace-fs.md deleted file mode 100644 index 73b5f51d..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/04-github-state-workspace-fs.md +++ /dev/null @@ -1,54 +0,0 @@ -# Findings — github/ + state/ + workspace/ + fs/ - -> Raw report from parallel audit agent. Scope: `packages/aitm/src/{github,state,workspace,fs}/`. - -## Bugs / correctness - -- [severity: high] [category: bug] `packages/aitm/src/workspace/in-place-checkout.ts:145-153` — `ensureCleanTree` runs `git reset --hard` + `git clean -fd` on every `acquire`/`resetToBase`, so a user's pre-existing uncommitted work at run start is destroyed indistinguishably from "stale group junk"; refuse to start (or auto-stash) on a dirty tree at run entry and only auto-clean between groups. -- [severity: high] [category: bug] `packages/aitm/src/state/state-store.ts:24-77` — there is no cross-process lock anywhere (grep confirms no lockfile/flock in cli/loop/state), so two concurrent `aitm` runs on the same state dir do last-writer-wins on `state.json`, and the in-memory `cached` (line 39) never observes peer writes, guaranteeing lost updates; `transcript-store.ts:237` even anticipates "a peer sharing the state dir" — acquire an exclusive `run.lock` (open `wx` + pid) in init/resume with try/finally release. -- [severity: med] [category: bug] `packages/aitm/src/github/github-client.ts:49-58` — `defaultRunCmd` flattens every `ExecaError` — including spawn ENOENT (gh not installed) — into `{exitCode: 1, stderr: ''}`, so callers throw e.g. `gh pr view failed: ` with an empty message and `GhCliMissing` is never raised; detect `err.code === 'ENOENT'` → throw `GhCliMissing`, and surface `shortMessage`. -- [severity: med] [category: bug] `packages/aitm/src/github/github-client.ts:251-254` — one transient gh failure (network flake → empty/non-JSON stdout) mid-poll throws and aborts a wait that may be 2h in; there is no retry-on-failure in `waitForChecks` (the backoff only paces successful polls) — tolerate N consecutive poll failures before throwing. -- [severity: med] [category: bug] `packages/aitm/src/github/github-client.ts:251-268` — the empty-check-set grace path assumes `gh pr checks` emits literal `[]`; gh versions that report "no checks reported" via non-zero exit + empty stdout hit `tryParseChecks → null` and throw at line 253 instead of entering `CHECKS_EMPTY_GRACE_MS`, so a checkless PR can hard-fail rather than merge — recognize the "no checks" stderr as an empty row set (no test covers this case either). -- [severity: med] [category: bug] `packages/aitm/src/github/github-client.ts:70-73` — `isInstantSleepEnabled` keys production sleep behavior off ambient `NODE_ENV === 'test'`, so a run launched in an environment that happens to set it collapses `CHECKS_START_WAIT_MS`/`CHECKS_EMPTY_GRACE_MS` to zero and can read a just-pushed PR's empty check set as mergeable; require the explicit `AITM_INSTANT_SLEEP` opt-in only. -- [severity: med] [category: bug] `packages/aitm/src/github/github-client.ts:313-327` — `failedRunIds` uses `gh run list --limit 30` with no pagination; on a branch with many workflows the failed run can fall outside the newest 30 and `getFailedCiLogs` silently returns `[]` ("no logs" fed to the fix loop) — filter server-side by head SHA or paginate. -- [severity: med] [category: bug] `packages/aitm/src/github/github-client.ts:432-434` — the non-advancing-cursor guard returns *before* adding the current page's nodes, silently dropping that page's threads (same pattern at 476-477 for comments), and `MAX_REVIEW_THREAD_PAGES` exhaustion at 438-439 truncates with no warning; append the page's nodes before breaking and log on truncation. -- [severity: med] [category: bug] `packages/aitm/src/state/state-store.ts:224-226` — `legacyTask` derives ids as `slugify(text)`, so two legacy tasks with identical text get identical ids, and the `Aitm-Task-Id` trailer resume dedup (`workspace/in-place-checkout.ts:53-72`) then reports the second task done because the first's commit matches — suffix the index into every legacy id, not just the empty-slug case. -- [severity: med] [category: bug] `packages/aitm/src/state/schema.ts:111-135` — `RunStateSchema` has no `schemaVersion` field; migration is ad-hoc read-time coercion (`state-store.ts:212-248`) that cannot distinguish "legacy" from "corrupt" and will accrete per-field hacks (five `optional`/`default` legacy escapes already) — add a version field plus a small keyed migration table. -- [severity: med] [category: bug] `packages/aitm/src/workspace/git-exec.ts:46-47` — `assertGitAllowed` only fires when `args[0] === 'push'`, so `['-C', dir, 'push', '--force']` or `['-c', 'k=v', 'push', '-f']` bypasses the advertised force-push chokepoint; skip leading global options before locating the subcommand. -- [severity: low] [category: bug] `packages/aitm/src/github/github-client.ts:572` — the merge-conflict classifier regex includes bare `conflict`, so any gh error merely containing that word (e.g. a ref/label conflict message) is misreported as `MergeConflict`; keep only the specific phrases. -- [severity: low] [category: bug] `packages/aitm/src/github/github-client.ts:240-276` — `waited` excludes the initial `CHECKS_START_WAIT_MS` and each gh call's latency, so the "120 min" budget is wall-clock-inaccurate (loosely unbounded on slow gh calls); accumulate from a `Date.now()` anchor. -- [severity: low] [category: bug] `packages/aitm/src/state/pr-context-store.ts:101-110` — `readAddressedThreads` swallows *every* error (EACCES, corrupt JSON) into an empty set, so the review loop would re-reply to all already-addressed threads; only ENOENT should degrade to empty. -- [severity: low] [category: bug] `packages/aitm/src/state/pr-context-store.ts:46-97` — `saveCiFailures`/`saveComments` never purge their subdir, so if a caller skips `clear()` between polls, stale `failed_*.txt`/`NNN_*.txt` from a previous iteration survive alongside fresh ones and mislead the fix subagent; have each save clear its own subdir first. -- [severity: low] [category: bug] `packages/aitm/src/state/rolling-context.ts:46-55` — `capOldestFirst` assumes `\n\n` only ever separates whole blocks, but the `existing` string can come from `StateStore.writeContext` content it didn't author (an LLM summary with blank lines), mis-splitting into pseudo-blocks and dropping partial text; normalize/collapse blank lines in `existing` before splitting. -- [severity: low] [category: bug] `packages/aitm/src/workspace/task-commit-marker.ts:11-13` — `taskCommitTrailer` accepts raw planner-derived ids; an id containing a newline can never match the full-line check in `in-place-checkout.ts:69-71`, silently disabling resume dedup for that task — sanitize/reject non-line-safe ids at trailer build time. -- [severity: low] [category: bug] `packages/aitm/src/state/state-store.ts:43-48` — `init` unconditionally overwrites an existing `state.json`, so a mistaken second `aitm start` clobbers a resumable run at the store layer regardless of CLI guards; make init refuse (or require explicit force) when state exists. - -## Resource cleanup - -- [severity: med] [category: resource] `packages/aitm/src/github/github-client.ts:41-59` — no gh invocation carries a `timeout` or `AbortSignal` (execa called with only `cwd`), so a hung `gh api .../logs` or a stalled `gh pr checks` blocks the run forever — `CHECKS_TIMEOUT_MS` bounds loop iterations, never a single child process; pass execa `timeout`/`signal` through `RunCmdOptions` and kill on abort. -- [severity: low] [category: resource] `packages/aitm/src/state/state-store.ts:105-114` — `appendProgress` uses bare `appendFile` (no fsync, non-atomic), so a crash can leave a torn final line in `progress.md`; acceptable for a log but worth noting against the module header's "atomic writes" claim (line 2). -- [severity: low] [category: resource] `packages/aitm/src/state/transcript-store.ts:169-171` — `end()` is best-effort like any append: if only the final `run-end` write fails (fewer than 3 consecutive failures, so no marker), a *completed* transcript looks interrupted and `findResumable` (line 298) replays a finished conversation; retry or fsync the run-end record specifically. -- [severity: low] [category: resource] `packages/aitm/src/state/transcript-store.ts:238-251` — `reserveOrdinalFile` intentionally leaves empty reserved `.jsonl` files when an agent dies before its first step and nothing ever garbage-collects them (findResumable only skips them, line 293); prune empty ordinals during `begin` or cleanup. -- (Positive note: `fs/atomic-write.ts` is correct — `wx` temp + fsync + rename + parent-dir fsync with try/finally close and temp removal on both failure paths; no findings there.) - -## Architecture - -- [severity: med] [category: arch] `packages/aitm/src/github/github-client.ts:122-607` — one 857-line class carries five concerns (PR CRUD, checks polling + backoff policy, CI log download, GraphQL review-thread pagination, auth/scopes); split at least the checks-poller and review-thread reader into their own modules so polling policy is testable apart from transport. -- [severity: low] [category: arch] `packages/aitm/src/github/errors.ts:3-21` — `PrNotFound`, `ReviewThreadStale`, `GhCliMissing`, `GhAuthRequired` are exported but never thrown anywhere (grep-confirmed); the file header promises "never raw stderr; always domain errors" yet nearly every client throw is `new Error(\`gh … failed: ${stderr}\`)` — either wire the domain errors in or delete them. -- [severity: low] [category: arch] `packages/aitm/src/github/github-client.ts:162-175` — `defaultBranch` hand-rolls JSON narrowing while every sibling (`repoMeta` line 550, checks line 707, GraphQL line 422) uses Zod; use a `DefaultBranchSchema` for consistency. -- [severity: low] [category: arch] `packages/aitm/src/state/pr-context-store.ts:136-138` — the `sanitize` helper is duplicated verbatim in `transcript-store.ts:51-53` (its comment even says "mirroring PrContextStore.sanitize"), with a third slug variant at `state-store.ts:250-257`; extract one fs-safe-name util per the house "second real caller" rule. -- [severity: low] [category: arch] `packages/aitm/src/github/check-tolerance.ts:74` — `envRules()` re-parses the env var inside the per-rule loop's enclosing call, i.e. on every failed check row of every poll; parse once per process (or memoize) since the env cannot change mid-run. -- [severity: low] [category: arch] `packages/aitm/src/github/github-client.ts:218-220` — `createPr` spawns one `gh label create --force` per label on every PR creation even though labels are repo-level and never change mid-run; ensure-once per run (cache like `cachedRepoMeta`). - -## Tests / house rules - -- [severity: low] [category: test] `packages/aitm/src/github/errors.ts` and `packages/aitm/src/github/schema.ts` — neither has a paired `*.test.ts` (errors asserted only incidentally at `github-client.test.ts:69`), violating the "every module ships with tests" rule. -- [severity: low] [category: test] `packages/aitm/src/state/state-store.test.ts` — no test exercises two StateStore instances (or processes) over the same dir, so the cache-vs-disk lost-update hazard (`state-store.ts:39`) is untested; likewise `github-client.test.ts` has no case for a transient mid-poll gh failure or a non-zero "no checks reported" exit in `waitForChecks`. -- [severity: low] [category: test] `packages/aitm/src/state/transcript-store.ts:100` — `console.debug` writes to stdout in Node, violating the Logger contract (structured logs → stderr, stdout reserved for plain status) and polluting parseable CLI output; route through the store's `onWarn`/Logger debug path. -- Portability: clean — no `Bun.*` APIs, no `any`/`as unknown as`, no default exports anywhere in the four audited dirs (grep-verified). - -## Missing capabilities worth adding - -- A run-level exclusive lock file for `.ai-task-master/` (pid + heartbeat) so concurrent `aitm` invocations fail fast instead of silently corrupting shared state — transcript-store already half-designs for peer processes; state-store doesn't. -- Abort/timeout plumbing through `RunCmd` (execa `signal`/`timeout`) plus one centralized transient-failure retry policy for gh calls, so Ctrl-C/timeout reliably kills children and a single network flake can't abort a 2-hour CI wait. -- `schemaVersion` in `state.json` with a keyed migration table (and ideally an `aitm doctor`-style validate command) replacing the growing pile of read-time coercions and per-field `optional()` legacy escapes. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/05-mcp-openrouter-credentials-agent-config.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/05-mcp-openrouter-credentials-agent-config.md deleted file mode 100644 index 06acaf9a..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/05-mcp-openrouter-credentials-agent-config.md +++ /dev/null @@ -1,56 +0,0 @@ -# Findings — mcp/ + openrouter/ + credentials/ + agent-config/ - -> Raw report from parallel audit agent. Scope: `packages/aitm/src/{mcp,openrouter,credentials,agent-config}/` (+ `@ai-sdk/mcp` stdio transport internals and CLI call sites). - -## mcp/ - -- [severity: high] [category: bug] `src/mcp/mcp-client.ts:76-77` — `connectAll()` awaits `createClient()` and `client.tools()` with no timeout, so one MCP server that hangs mid-handshake (wedged stdio child, unresponsive HTTP endpoint) blocks run startup forever, defeating the stated "a broken MCP server should not block the whole run" contract; wrap each server's connect in a `Promise.race` with a per-server deadline and close the client on expiry. -- [severity: med] [category: resource] `src/mcp/mcp-client.ts:135-149` — `close()` awaits `Promise.all` of `client.close()` calls with no timeout, so a single hanging `close()` means `this.processes.terminate()` on line 149 is never reached — directly contradicting the comment on lines 147-148 ("a client.close() that hangs ... must not decide whether the child process survives"); time-box the close batch and always run `terminate()` after. -- [severity: med] [category: resource] `src/mcp/mcp-client.ts:80-99` — on the `tools()`-throws path, `client.close()` (line 82) runs before the `finally` reads the pid, and the SDK's `StdioMCPTransport.close()` and child-`close` handler both set `this.process = void 0`, so `stdioPid()` returns undefined and the pid is never registered for exactly the mid-handshake-failure case the line 95-97 comment claims to cover; snapshot the pid immediately after `createClient` resolves, before any close. -- [severity: low] [category: bug] `src/mcp/mcp-client.ts:206-209` — `sanitizeServerName` maps distinct configured names to the same key (`my-srv` and `my__srv` both → `my-srv`; `a b` and `a-b` both → `a-b`), silently overwriting one server's tools in the merged `ToolSet` with the other's; detect post-sanitization collisions and warn or de-duplicate with a suffix. -- [severity: low] [category: bug] `src/mcp/mcp-client.ts:69-101` — servers connect strictly sequentially, so N slow servers serialize startup latency; connect concurrently (`Promise.allSettled`) since failures are already isolated per server. -- [severity: low] [category: bug] `src/mcp/tool-search.ts:184-186` — a deferred tool that has no `execute` returns the "fetch its schema with tool_search first" guard even after activation, sending the model into a fetch/call loop it can never exit; return a distinct "tool is not executable" message for the `!baseExecute` case. -- [severity: low] [category: arch] `src/mcp/tool-search.ts:200` — `guardDeferred` returns `{ ...base, execute, toModelOutput } as AnyTool` — a soft cast that erases the `Tool` generic typing; model the wrapper with a generic over the base tool instead of casting. - -## mcp/oauth.ts (biggest problem cluster) - -- [severity: high] [category: arch] `src/mcp/oauth.ts:167-267,296-297` — this module ships an inbound localhost HTTP server (`NodeServer` + `http.createServer`), and CLAUDE.md's "Out of scope for v1" explicitly bans "Webhooks or any inbound HTTP" with instructions to stop and surface rather than implement; needs an explicit sanction (RFC 8252 loopback-redirect exception) or removal — surfaced as required. -- [severity: high] [category: bug] `src/mcp/oauth.ts:282-293` — the authorization request sends no PKCE `code_challenge` (and no `code_verifier` at token exchange, lines 343-348) even though the file header cites "MCP OAuth 2.1 spec" — OAuth 2.1/MCP make PKCE mandatory, so spec-compliant servers will reject the flow and the loopback redirect is open to code interception; generate an S256 challenge/verifier pair. -- [severity: med] [category: bug] `src/mcp/oauth.ts:234,254-256` — `Object.fromEntries(searchParams) as OAuthCallbackResult` is an unvalidated cast: a callback with neither `code` nor `error` (e.g. `/callback?state=x`) resolves the flow and posts `code=undefined` to the token endpoint; validate that `code` or `error` is actually present before resolving. -- [severity: med] [category: bug] `src/mcp/oauth.ts:325` + `src/cli/commands.ts:969-971` — `config.url` is derived by stripping `/oauth/authorize.*` off `authUrl` (built from `serverUrl.origin`), so an MCP server at `https://host/mcp` produces a config snippet pointing at `https://host` — the wrong server URL; pass the original server URL through `OAuthOptions` instead of reverse-engineering it. -- [severity: med] [category: bug] `src/mcp/oauth.ts:107-109` — `fileURLToPath(join(dirname(import.meta.url), ...))` mixes a `file://` URL string through `path.join` (collapses `///`, backslashes on Windows) and sits *outside* the `try`, so a parse failure throws out of `loadHtmlTemplate` instead of hitting the fallback; use `fileURLToPath(new URL('../templates/…', import.meta.url))` inside the try. -- [severity: med] [category: resource] `src/mcp/oauth.ts:199-206` — `stop()` awaits `server.close()`, which only completes after all connections close; a browser keep-alive connection makes the `finally` on line 330-332 hang indefinitely; call `server.closeAllConnections()` (Node ≥ 18.2) before awaiting close. -- [severity: med] [category: bug] `src/mcp/oauth.ts:272-276` — a caller-supplied `callbackUrl` does not inform the listening port: the server binds an auto-picked port in 8787-9000 while `redirect_uri` points wherever `callbackUrl` says, so the callback never reaches the server and the flow times out; parse and use the port from `callbackUrl` when provided. -- [severity: low] [category: bug] `src/mcp/oauth.ts:362-373` — the token response is checked only for an `error` key and then `as`-cast; a 200 response without `access_token` yields `Authorization: Bearer undefined`; validate `access_token` is a non-empty string. -- [severity: low] [category: bug] `src/mcp/oauth.ts:237-245` — a state-mismatch callback returns 400 to the browser but never settles `waitForCallback`, so the CLI silently hangs until the full timeout with no operator-visible signal; log/report the mismatch while continuing to wait. -- [severity: low] [category: arch] `src/mcp/oauth.ts:54-58,271` — `detectRuntime()` is computed and never used, `ServerImpl` is an interface with exactly one implementation, and `rejecter` (lines 222-226) is assigned but never invoked — dead code implying Bun/Deno servers that don't exist, and duplicating `detectRuntime` from `src/credentials/llm-fetch.ts:40-46`; delete the dead paths or implement them. -- [severity: med] [category: test] `src/mcp/oauth.test.ts:6-14,16-28,30-50,52-72` — the pairing is near-worthless: it re-implements `generateState` instead of importing it, "structure" tests assert TypeScript type shapes at runtime, the two `performOAuthFlow` tests spawn a REAL browser (`xdg-open`) and bind real ports on every test run, and line 49 drops the `await` on `assert.rejects` (floating promise); no coverage exists for state validation, callback parsing, or token exchange — rewrite against an injected server/browser seam. - -## openrouter/ - -- [severity: med] [category: bug] `src/openrouter/client.ts:106-108` and `src/openrouter/reference-catalog.ts:34` — both catalog fetches have no timeout/AbortSignal, and `ModelLimitsRegistry.fillFromReference`'s try/catch (`src/openrouter/model-limits.ts:137-142`) guards only rejection, not a hang — a stalled `/models` endpoint stalls `preload()` and therefore run startup indefinitely; pass `AbortSignal.timeout(...)` to both. -- [severity: low] [category: bug] `src/openrouter/model-limits.ts:152-158` — `hasGap` ignores `maxOutputTokens`, so a provider publishing window + pricing but no output cap never receives the reference catalog's `max_completion_tokens` even though `merge` (line 197-199) is ready to fill it; add it to the gap predicate. -- [severity: low] [category: arch] `src/openrouter/client.ts:109-111` vs `src/openrouter/reference-catalog.ts:35-39` — the fetch → `!res.ok` → body-excerpt → throw pattern is duplicated (with inconsistent excerpt caps, 500 vs 200); extract one shared `fetchCatalog(url, headers)` helper. - -## credentials/ - -- [severity: low] [category: bug] `src/credentials/credentials.ts:60` — `onOpenRouter = !resolved.baseURL` means an *explicit* `baseURL` of `https://openrouter.ai/api/v1` silently disables cache_control, session_id, and usage accounting on the actual OpenRouter endpoint; also treat OpenRouter's own host as on-OpenRouter. -- [severity: low] [category: resource] `src/credentials/llm-fetch.ts:77-85` — the undici `Agent` (60s keep-alive, 16 connections) has no disposal path — nothing ever calls `close()/destroy()` on it — and the wrapper `{ ...init, dispatcher }` silently clobbers any caller-supplied `init.dispatcher`; return a dispose handle alongside the fetch and only inject the dispatcher when the caller didn't set one. -- [severity: low] [category: arch] `src/cli/commands.ts:507` and `src/loop/run-loop-adapter.ts:1213` — `new OpenRouterClient(resolved.openrouterApiKey, resolved.baseURL)` is wired at two call sites outside `Credentials`, spreading key+baseURL pairing beyond the "one place" the module map mandates; expose a catalog-client factory from `Credentials` (or one shared builder) instead. -- [severity: low] [category: test] `src/credentials/defaults.ts` — no paired `defaults.test.ts` (values asserted only incidentally via credentials.test.ts); add a minimal pairing or fold the table into credentials.ts. - -## agent-config/ - -- [severity: low] [category: bug] `src/agent-config/agent-config-detector.ts:81-94` — the repoRoot containment check applies only to *relative* `stylePath`s; an absolute path outside the repo is accepted but then expanded with `root: this.repoRoot`, so every one of its relative `@`-imports silently fails containment and is left literal; if out-of-repo style files are intended, expand them rooted at their own directory (as `detectUser` does at lines 173-176). -- [severity: low] [category: bug] `src/agent-config/expand-imports.ts:144` — the `@([^\s]+)` pattern captures trailing prose punctuation (`see @docs/style.md.` → path `docs/style.md.`), so the realpath lookup fails and the import is silently left literal; strip trailing `.,;:!?)` from the captured path before resolving. -- [severity: low] [category: bug] `src/agent-config/agent-config-detector.ts:118` — `readdir(...).catch(() => null)` swallows EACCES/EIO the same as ENOENT, silently dropping entire subtrees of nested config files with no `onWarn`; warn on non-ENOENT readdir failures. - -## Cross-cutting checks that came back clean - -- No `Bun.*` APIs, no Anthropic-SDK-shaped code, no default exports, ESM throughout; `chatSettings`/`providerSettings` correctly centralize inference wiring in Credentials; API keys never appear in log/error strings; mcp-client.test.ts (487 lines), model-limits, expand-imports, and credentials test suites are genuinely thorough — tool-name-collision, allowlist, prototype-pollution, symlink-escape, and byte-budget edges all have direct tests. - -## Missing capabilities worth adding - -- **MCP connect/close deadlines as config**: a `connectTimeoutMs`/`closeTimeoutMs` on `McpClientInit` (with parallel connect) is the single change that removes the three hang-forever paths in mcp-client.ts. -- **OAuth completeness**: PKCE (mandatory), RFC 8414 authorization-server metadata discovery instead of hard-coding `/oauth/authorize`+`/oauth/token` (cli/commands.ts:970-971), and refresh-token capture — today the access token is printed once to stdout and expires with no recovery path. -- **Shared HTTP fetch helper with timeout+retry** for the two catalog clients (and any future keyless GET), replacing the duplicated non-2xx/excerpt logic and giving one place to add `AbortSignal.timeout`. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/06-observability-logger-compaction-plan-tools.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/06-observability-logger-compaction-plan-tools.md deleted file mode 100644 index de9a0e9b..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/06-observability-logger-compaction-plan-tools.md +++ /dev/null @@ -1,51 +0,0 @@ -# Findings — observability/ + logger/ + compaction/ + plan/ + tools/ (+ index, testing) - -> Raw report from parallel audit agent. Scope: `packages/aitm/src/{observability,logger,compaction,plan,tools,testing}/` + root `index.ts`. - -## Bugs / correctness - -- [severity: high] [category: bug] `src/observability/step-progress.ts:235-255,282,290` — Model text and tool inputs (e.g. a `bash` command containing `curl -H "Authorization: Bearer …"`) are written to stderr via `summarizeToolInput`/`renderStepLines` with only ANSI/control stripping, never `scrubSecrets` — the logger scrubs secrets meticulously (`logger.ts:104,164`) but the far chattier progress stream on the same fd does not, so secrets leak into terminal scrollback and any teed log file; run `clip()` output through `scrubSecrets` before emit. -- [severity: high] [category: bug] `src/compaction/compaction-step.ts:144-152` — The prune path skips the summarizer whenever `freedChars >= 20_000` (absolute) without re-checking that the pruned array now fits `usableInputTokens`, so a context overflowing by far more than ~5k tokens is still sent overflowing and the next model call fails on a window error; recompute the estimate over `pruned.messages` and fall through to summarize when it still exceeds the usable budget. -- [severity: med] [category: bug] `src/compaction/compaction-step.ts:91,204-213` — `estimateTokens` uses raw `JSON.stringify(message.content)` outside any try/catch, so a circular or BigInt-bearing SDK message throws straight out of `prepareStep` and crashes the step — the exact hazard `compactor.ts:198-202` documents and guards against in `safeStringify`; reuse `safeStringify` here. -- [severity: med] [category: bug] `src/tools/datetime.ts:41-50` — The tool's description promises the time "optionally formatted for a specific timezone" but `execute` always returns `date.toISOString()` (UTC) and only uses `Intl.DateTimeFormat` to echo the timezone name, so a model asking for Europe/Berlin gets a UTC instant labeled "Europe/Berlin" — actively misleading; return `formatter.format(date)` alongside the ISO instant. The test at `datetime.test.ts:23` bakes the wrong behavior in. -- [severity: med] [category: bug] `src/observability/error-reporter.ts:32-50` — `scrubEvent` claims to catch secrets in "stack frames" but only scrubs `exception.value`, `message`, `request.url`, and `breadcrumb.message`, missing `stacktrace.frames[].vars`, `breadcrumb.data`, `event.extra`, `event.tags`, and `event.contexts` — all of which the Sentry SDK populates and ships to GlitchTip unscrubbed; walk those fields too. -- [severity: med] [category: bug] `src/logger/secret-scrubber.ts:15` — The vendor-prefix pattern `gh[pousr]_` misses GitHub fine-grained PATs (`github_pat_…`) and underscore-form keys like Stripe `sk_live_`/`sk_test_` (only `sk-` with hyphen matches); add `github_pat_` and `(?:sk|pk|rk)_(?:live|test)_` alternatives. -- [severity: med] [category: bug] `src/compaction/compaction-step.ts:131-134` — On every compaction the original user task brief (goal + acceptance criteria) always lands in `older` and is replaced by the LLM summary, relying entirely on the summarizer to preserve the contract; keep the run's first user message verbatim ahead of the summary so the ground-truth task can never degrade through successive summarizations. -- [severity: low] [category: bug] `src/tools/web-fetch.ts:235-239` — `readBodyCapped` sets `truncated = body.length > maxChars` after the `>=` check, so a stream cancelled exactly on `maxChars` reports `truncated: false` even though more data remained; treat reaching the cap with an unfinished stream as truncated. -- [severity: low] [category: bug] `src/plan/plan-markdown.ts:46-53` — Task lines before any `## Group:` header are silently dropped (`current` undefined), and a hand-edited task whose text begins with a bracketed word (`- [ ] [FOO] fix x`) silently loses `[FOO]` to the complexity slot; count/return orphan lines or warn on unknown complexity tags. -- [severity: low] [category: bug] `src/plan/schema.ts:72-76` — `PlanSchema.groups` has no `.min(1)`, so an empty plan validates and only fails later at `subagents/planner.ts:124` — outside the schema-retry loop the file itself says is the cheap enforcement point; add `.min(1)` with a `.describe()`. -- [severity: low] [category: bug] `src/observability/run-step.ts:72-78` — In prPerTask mode a task id absent from the group clamps `findIndex` −1 to 0 (silently reporting the group's first task) and the done-count fallback yields `before+done+1`, one past the last task once a group completes; return `undefined` for unknown tasks and clamp the fallback. -- [severity: low] [category: bug] `src/tools/github-thread-tool.ts:46-48` — A missing/blank `body` for `replyToThread` returns bare `{ ok: false }` with no reason; include an error string. -- [severity: low] [category: bug] `src/tools/web-fetch.ts:151-159` — The SSRF IPv4 denylist misses 100.64.0.0/10 (CGNAT — metadata endpoints on some clouds), 192.0.0.0/24, 198.18.0.0/15, and NAT64 `64:ff9b::/96`; extend the range checks. (Fetch-path DNS-rebind TOCTOU at 73-77 documented as accepted; residual risk only.) -- [severity: low] [category: bug] `src/logger/logger.ts:67-69` — `status()` writes to stdout without `scrubSecrets`, the one Logger output path with no redaction at all; scrub status messages too. - -## Missing resource cleanup / lifecycle - -- [severity: med] [category: resource] `src/logger/logger.ts:77-84` vs `src/cli/cli.ts:197-207` — The CLI exit path awaits `reporter.flush()` but never a `Logger.flush()`, and `process.exit()` would discard pending `writeTail` file appends; wire logger flush into the same shutdown path. -- [severity: med] [category: resource] `src/observability/usage-tracker.ts:101-166` — Usage/cost accounting lives only in memory and is flushed solely on normal loop completion (`cli/commands.ts:505`); a crash or second-SIGINT force-exit loses the run's entire spend record — persist increments to state or flush totals in the signal/exit handler. -- [severity: low] [category: resource] `src/observability/heartbeat.ts:55-58` — The default `setInterval` handle is never `unref`'d; call `handle.unref?.()` as defense in depth (all five current call sites do `finally { stop() }` correctly). -- [severity: low] [category: resource] `src/observability/error-reporter.ts:61-89` — `Sentry.init` is never paired with `Sentry.close()`; `flush(2000)` drains events but leaves global integrations/handlers installed — wrong if `main` is ever embedded (it is exported from `index.ts:5`); return a `close()` on the reporter. - -## Architecture / house rules - -- [severity: med] [category: arch] `src/logger/logger.ts:40` — `new Logger(...)` appears nowhere in production code (only tests); every consumer takes `logger?: LoggerLike` and no CLI/loop site ever supplies one, so the entire structured-logging module — level filter, file transport, redaction — is dead code in the shipped binary, and every `logger?.warn` (e.g. compaction failure warnings at `compaction-step.ts:110,161,172`) is a silent no-op; construct a Logger in `cli/commands.ts` and thread it through the run. -- [severity: med] [category: arch] `src/loop/run-loop-adapter.ts:1275-1279,1378-1382` — The two main-path `buildCompactionStep` call sites (worker, reviewer) omit `logger` entirely while `ci-fix.ts:275` and `self-review.ts:211` at least thread the (never-populated) optional — so compaction skip/failure diagnostics are structurally unreachable exactly where compaction matters most; pass the run logger at all four sites. -- [severity: med] [category: arch] `src/compaction/compaction-step.ts:85-90` — Because the `prepareStep` message override doesn't persist, every step after the threshold re-runs the full prune + (when under 20k freed) a fresh LLM summarizer call against the reverted full history — a per-step summarizer bill acknowledged in the comment as a "follow-up"; cache the last compacted result keyed on message-array length and reuse it until the tail grows past budget. -- [severity: low] [category: arch] `src/observability/step-progress.ts:1-435` — One 435-line module holds five responsibilities (duration/tag formatting, label composition, sink abstraction, step renderer, live-stream renderer, handler composition); split into format/label, sink, and renderer modules. -- [severity: low] [category: arch] `src/logger/logger.ts:146-165` and `src/compaction/compactor.ts:203-213` — Two bespoke cycle-safe serializers solve the identical problem (both citing issue #251) with different mechanisms (WeakSet ancestor chain vs `JSON.stringify` holder walk); extract one shared helper. -- [severity: low] [category: arch] `src/index.ts:30-44` — The "keep this list narrow" public surface re-exports test-only internals (`decodeDdgHref`, `parseDuckDuckGoHtml` — both annotated "Exported for unit testing" — plus `DEFAULT_STEALTH_HEADERS`, `DEFAULT_IMPERSONATE_TARGETS`); tests can import from the module path directly, so drop them from the index. - -## Tests - -- [severity: low] [category: test] `src/compaction/compaction-step.test.ts` — No test covers (a) prune freeing ≥20k while the result still exceeds the budget, or (b) a circular/BigInt message hitting `estimateTokens`; both are the crash/overflow paths above. -- [severity: low] [category: test] `src/observability/error-reporter.test.ts:1-65` — Only the no-DSN and pure-function paths are tested; the DSN-present branch (SDK import, `beforeSend` wiring, flush) is entirely unexercised. -- [severity: low] [category: test] `src/testing/temp-repo.ts:19` — `git init` without `-b main` leaves the branch name to host `init.defaultBranch`, making dependent tests environment-sensitive; pin the branch. -- [severity: low] [category: test] `src/index.test.ts:5-23` — The surface test asserts presence of ~16 exports but neither the tool exports nor absence of unintended ones, so surface drift in either direction passes silently. - -House-rule scan: no `any`, no `as unknown as`, no default exports, no `Bun.*` APIs in any audited shipped file; every audited module has a paired `*.test.ts` and coverage is generally strong (logger, step-progress, web-fetch SSRF, and compactor suites notably thorough). - -## Missing capabilities worth adding - -- **Env-value secret scrubbing**: scrub the literal runtime values of `OPENROUTER_API_KEY`/known credential env vars from every output channel (logger, progress stream, GlitchTip events) — pattern-based scrubbing cannot catch arbitrary-format keys from custom OpenAI-compatible endpoints, which the provider stance explicitly supports. -- **Unified shutdown path**: one exit hook that flushes Logger, UsageTracker totals, and the error reporter together on normal exit and on first signal, so no telemetry/accounting channel depends on its caller remembering to flush. -- **Post-compaction size verification**: after prune or summarize, re-estimate the outgoing context and escalate (summarize, then hard-truncate oldest tail) until it provably fits the usable window, turning the current heuristic into a guarantee. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/07-resource-lifecycle-sweep.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/07-resource-lifecycle-sweep.md deleted file mode 100644 index 9ee92335..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/07-resource-lifecycle-sweep.md +++ /dev/null @@ -1,45 +0,0 @@ -# Findings — cross-cutting resource-lifecycle ("RAII") sweep - -> Raw report from parallel audit agent. Scope: every acquisition/release pattern in `packages/aitm/src/`. - -## Process / child-process lifecycle - -- [severity: high] [category: resource] `mcp/oauth.ts:96-102` — `openBrowser()` calls `spawn(command, args, { detached: true, stdio: 'ignore' })` with **no `'error'` listener** on the returned ChildProcess. On any host where the opener binary is missing (`xdg-open` on headless Linux — the common case for a CLI agent tool), spawn's failure is emitted asynchronously as an `'error'` event with no listener, which throws uncaughtException and **crashes the whole `aitm mcp-login` process** (skipping the `finally { await server.stop() }`). Fix: `proc.on('error', () => { /* print the auth URL, ask the user to open it manually */ })`. `mcp/oauth.test.ts` has no coverage of the spawn path at all. -- [severity: med] [category: resource] `mcp/mcp-client.ts:73` — `const config = buildClientConfig(name, server)` sits **outside** the per-server `try` in `connectAll()`. If the `Experimental_StdioMCPTransport` constructor throws for server N (bad cwd/env shape), `connectAll()` rejects; in `run-loop-adapter.ts:637-642` `mcpConnected` is then never set true, so the `finally` at `run-loop-adapter.ts:764` **skips `mcp.close()`** — servers 1..N-1's already-connected clients leak: stdio children survive until the process-exit SIGKILL guard, http/sse connections leak for the process lifetime. Fix: move `buildClientConfig` inside the `try`, and/or make the adapter's `finally` call `mcp.close()` unconditionally (idempotent by design). -- [severity: low] [category: resource] `loop/run-loop-adapter.ts:632` — `reapOnAbort` does `void mcp.close()` fire-and-forget; if an http/sse `client.close()` hangs, nothing escalates until process exit; worth a timeout race around the close. -- [severity: low] [category: resource] `github/github-client.ts:41-59`, `workspace/git-exec.ts:66`, `orchestrator/orchestrator.ts:71` — every `execa('gh'|'git', …)` call runs with **no `timeout` and no abort signal**. A network-wedged `gh api`/`gh pr checks` blocks the run indefinitely, and a SIGINT abort cannot kill an in-flight subprocess (only the second-SIGINT force-exit does, orphaning it). Fix: pass `{ timeout }` (and `cancelSignal` in execa ≥8) at the `defaultRunCmd`/`runGit` chokepoints. - -## Abort/signal propagation (acquired LLM streams kept running) - -- [severity: med] [category: resource] `subagents/worker.ts:1110` is the **only** place `abortSignal` reaches a `generateText` call. Planner (`run-loop-adapter.ts:995-1011`), Reviewer (`:1332-1348`), Worker manifest pass, CI-fix session (`loop/ci-fix.ts`), self-review (`loop/self-review.ts`), Compactor (`compaction/compactor.ts:183`), scouts (`subagents/planner-scouts.ts:184`) and the explore child (`subagents/explore.ts`) never receive `RunLoopInput.signal`. After first Ctrl-C, all these in-flight LLM streams keep running (and billing) to completion; `WorkLoop` only checks `signal.aborted` between iterations (`loop/work-loop.ts:395,407,445`). The worker editor fanout (`worker.ts:984-1038`) shows the correct pattern (shared `AbortController`, `removeEventListener` in `finally`) — thread the same signal through `SubagentInit` into every `createSubagent`/`generateText` site. -- [severity: med] [category: resource] `github/github-client.ts:75-80,236-278` — `defaultSleep` is a bare `setTimeout` promise and `waitForChecks` polls up to 120 min with sleeps up to 60s; neither is abort-aware. Same for take-over cooldown sleeps (`loop/take-over-flow.ts`) and `REVIEW_COMMENTS_GRACE` (2 min) in `loop/stage-handlers.ts:155`. Fix: an abortable `sleep(ms, signal)` (listener + `clearTimeout` in `finally`) threaded from the run signal; check `signal.aborted` at the top of each poll iteration. - -## Sockets / HTTP - -- [severity: low] [category: resource] `credentials/llm-fetch.ts:77-80` — the undici `Agent` (60s keep-alive, 16 connections) is created and **never `destroy()`/`close()`d**, no handle returned to any owner. Masked in the CLI because `cli/cli.ts:203` always `process.exit()`s, but any embedding of the exported `main()` keeps idle sockets holding the event loop up to 60s, one leaked Agent per `createLlmFetch()` call. Fix: return `{ fetch, close }` and dispose at run end. -- [severity: low] [category: resource] `mcp/oauth.ts:199-206` — `NodeServer.stop()` awaits `server.close()`, which does not terminate an active keep-alive connection (the browser that just received the success page holds one). Fix: `server.closeAllConnections()` (Node ≥18.2) before/after `close()`. -- [severity: low] [category: resource] `openrouter/client.ts:106` — `listModels()` fetch has no `AbortSignal.timeout`; a stalled `/models` endpoint hangs run startup indefinitely. The sibling tools (`tools/web-fetch.ts:316`, `tools/web-search.ts:175`) all use `AbortSignal.timeout` — mirror that here. - -## Timers, exits, files - -- [severity: low] [category: resource] `cli/cli.ts:203,208` — `process.exit(code)` immediately after the final stdout/stderr writes can truncate pending piped output on platforms where pipe writes are async (Windows). Resolve write callbacks or use `process.exitCode` + natural exit (fix together with the undici-agent disposal above). -- [severity: low] [category: resource] `loop/progress-file.ts` + `run-loop-adapter.ts:322` (`void recorder.step(...)`) — progress.md/transcript appends are fire-and-forget chains with no awaited flush before `process.exit`; the last lines of a run can be silently lost. A final `await chain` in the run's `finally` would cost nothing. -- [severity: low] [category: resource] `testing/temp-repo.ts:16` — `mkdtemp` cleanup is returned to the caller, but a test that throws before calling `cleanup()` leaks the tempdir; a `Symbol.asyncDispose` on `TempRepo` would enable `await using`. - -## Verified clean (worth stating) - -- `mcp/stdio-process-registry.ts` — exemplary: liveness-probed SIGTERM→SIGKILL escalation, synchronous `exit` guard armed/disarmed symmetrically, EPERM handled. Well tested. -- `fs/atomic-write.ts` — handle closed in nested `finally`, temp file removed on both failure paths, parent-dir fsync handle closed in `finally`. -- `tools/web-fetch.ts` / `web-search.ts` — redirect bodies cancelled per hop, capped body reader cancels + releases lock in `finally`, non-200 bodies cancelled. -- `subagents/worker.ts:984-1038` — fanout AbortController wiring with listener removal in `finally` is the model the rest of the codebase should copy. -- `observability/heartbeat.ts` — every call site (5 in `run-loop-adapter.ts`) stops it in a `finally`; stop is idempotent. -- `state/transcript-store.ts:243-244` — `open(…, 'wx')` handle closed on both success and EEXIST-retry paths. -- `loop/work-loop.ts:455-493` — checkout slot released in inner `finally` plus defensive outer catch-release. -- `cli/commands.ts:874-883` — readline closed in `finally`. - -## Systemic recommendations - -- **No central disposal pattern exists.** Lifecycle is hand-rolled per site: try/finally in the adapter, two independent reapers (`StdioProcessRegistry`, compat `ProcessManager`), an ad-hoc abort listener, and an undici agent with no owner. A small run-scoped `Disposer` (`add(fn)` + `disposeAll()` called from the adapter's `finally` *and* from `reapOnAbort`) would give every acquisition one guaranteed exit path. Avoid `await using`/`AsyncDisposableStack` for now: Node 20 / Deno 1.40 portability is a house rule and `DisposableStack` isn't reliably available there; a hand-rolled Disposer is. -- **One abortable-sleep + one signal-threading convention.** Add `sleep(ms, signal)` next to `defaultSleep` and add `signal` to `SubagentInit`, then sweep the ~8 LLM call sites and 3 poll loops. This closes the entire "first Ctrl-C does nothing for minutes" family in two primitives. -- **Chokepoint timeouts for subprocesses and startup fetches.** `defaultRunCmd`, `runGit`, and `OpenRouterClient.listModels` are single funnels — a `timeout`/`AbortSignal.timeout` at each covers every caller. -- **Test the failure-path cleanup, not just the happy path.** Untested today: `openBrowser` spawn failure (crashes), `connectAll` partial-connect leak on a throwing transport constructor, oauth `server.stop()` under a held keep-alive connection, undici agent teardown. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/08-architecture-sweep.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/08-architecture-sweep.md deleted file mode 100644 index dc489ecd..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/findings/08-architecture-sweep.md +++ /dev/null @@ -1,60 +0,0 @@ -# Findings — cross-cutting architecture sweep - -> Raw report from parallel audit agent. Scope: whole `packages/aitm/` — module-map conformance, dependency structure, portability, test pairing, export hygiene, out-of-scope creep. - -## Findings - -### 1. Module-map conformance (arch) - -- [med] [category: arch] `CLAUDE.md` (module map) — The map lists 10 modules; `src/` has 19 dirs. The 10 undocumented dirs (`compaction`, `config`, `fs`, `mcp`, `observability`, `openrouter`, `plan`, `tools`, `workspace`, `testing`) are each individually coherent (one responsibility per dir, consistently `schema.ts` + feature files), so this is doc drift, not code drift. Fix: update the CLAUDE.md module map; it is the stated contract and is now ~50% stale. -- [med] [category: arch] `src/credentials/` + `src/openrouter/` + `src/config/provider-presets.ts` + `src/credentials/llm-fetch.ts` — CLAUDE.md says "Provider wiring lives in one place (Credentials)". It now lives in three dirs (credentials = model handles, openrouter = catalog/limits/server-tools, config = presets/profiles). The split is reasonable; the stated invariant is false. Fix: rewrite the invariant as "provider wiring = credentials + openrouter, presets in config" or merge presets into credentials. -- [high] [category: arch] `src/cli/commands.ts` (1307 lines) — CLAUDE.md: "CLI: arg parsing and exit codes only." This file constructs Credentials, ConfigLoader/Writer, ProfileManager, GitHubClient, StyleDistiller, OpenRouterClient, ModelLimitsRegistry, StateStore and defines `defaultRunLoop` — it is a second composition root, not arg parsing. Fix: move wiring into `loop/run-loop-adapter.ts` (the existing composition root) or a new `src/bootstrap/` module; leave `cli/` with args + dispatch + exit codes (`args.ts` at 550 lines is already the right shape). -- [med] [category: arch] `src/loop/run-loop-adapter.ts` (2049 lines, imports from 17 of 19 src dirs) — the de-facto composition root living inside `loop/`, which also contains the domain loop (`work-loop.ts`, `stage-handlers.ts`). Two reasons to change: loop semantics vs. dependency assembly. Fix: extract wiring to `src/composition/` (or `bootstrap/`) so `loop/` only drives the plan. -- [med] [category: arch] `src/subagents/worker.ts` (1484 lines) — worker agent definition + editor-fanout pool scheduler (`runEditorFanout`, ~line 977) + team-brief rendering in one file. Fix: split fanout/pool into `subagents/editor-fanout.ts`. -- [low] [category: arch] `src/config/config-loader.ts` (640 lines) — loads aitm config AND discovers/parses Claude Code's `~/.claude.json` / project MCP envelopes AND does secret redaction. Fix: extract `claude-code-config.ts` reader. -- [low] [category: arch] `src/agent-config/coding-style.ts` — the "find CLAUDE.md, return payload" module grew an LLM `StyleDistiller` (imports `reportUsage` from `subagents/factory.ts`). Detector and distiller are different reasons to change and the import inverts layering. Fix: inject `OnUsage` instead of importing from subagents, or move StyleDistiller under `subagents/`. -- [med] [category: arch] `src/templates/` — not empty: contains `oauth-success.html` / `oauth-error.html`. But `tsc` never copies them — `dist/templates` does not exist — so the published package (`files: ["dist"]`) always hits the `catch` fallback in `src/mcp/oauth.ts:106-116` (`getDefaultHtml`). The HTML files are dead assets and the inline fallback duplicates them. Fix: either add a copy step to `build` or delete the HTML files and keep only the inline strings. -- [low] [category: arch] `src/testing/temp-repo.ts` — test scaffolding compiled into the published artifact (`dist/testing/temp-repo.js`) but unreachable: `exports` maps only `"."` → `dist/index.js` and `index.ts` doesn't re-export it. Dead weight in the npm tarball. Fix: exclude `src/testing` from `tsconfig.build.json`. - -### 2. Dependency structure (arch) - -- [high] [category: arch] `src/cli/commands.ts:26-27` ↔ `src/loop/run-loop-adapter.ts:49` / `src/loop/merge-flow-adapter.ts:11` — genuine cli↔loop cycle: `commands.ts` value-imports both adapters, and both adapters import `RunLoopInput` / `RunMergeFlowInput` back from `cli/commands.ts` (defined at commands.ts:48 and :73). Type-only backward edges so it runs, but the loop's own input contract lives in the CLI. Fix: move both input types into `loop/`. -- [med] [category: arch] config ↔ credentials ↔ mcp dir-level cycle — `config/schema.ts:11` → `mcp/schema.ts`; `config/config-loader.ts:16` → `credentials/defaults.ts`; `credentials/credentials.ts:12` → `config/schema.ts`; `mcp/mcp-client.ts:16` → `credentials/credentials.ts` (Role). File-level it's acyclic (schemas are leaves) but the dir graph is tangled. Fix: move `Role` and shared schema types into a leaf `types`/`domain` module, or keep all schemas in `config/schema.ts`. -- [med] [category: arch] `src/config/config-loader.ts:17-21` — config (bottom layer) imports default constants from three higher layers: `DEFAULT_MAX_CI_FIX_ATTEMPTS` from `loop/constants.ts`, `DEFAULT_LLM_STEP_TIMEOUT_MS` from `subagents/factory.ts`, `DEFAULT_MCP_DEFER_TOOLS_OVER` from `mcp/mcp-client.ts`. Inverted layering for the sake of defaults. Fix: hoist defaults into `config/` (or `credentials/defaults.ts`-style leaf) and have loop/subagents/mcp import them downward. -- [med] [category: arch] state ↔ plan cycle — `state/state-store.ts:8` → `plan/plan-markdown.ts`, while `plan/schema.ts:6`, `plan/plan-graph.ts:5`, `plan/plan-markdown.ts:7` → `state/schema.ts`. Fix: `PrGroup`/`Task`/`TaskComplexity` are domain types, not persistence types — extract to a leaf `domain/` module both depend on. -- [low] [category: arch] state ↔ subagents type cycle — `state/rolling-context.ts:9` imports `WorkerDelivery` from `subagents/worker.ts` while `subagents/worker.ts:65` imports `state/schema.ts`. Fix: move `WorkerDelivery` into `state/schema.ts` or the proposed `domain/`. -- [low] [category: arch] tools ↔ subagents type cycle — `tools/github-thread-tool.ts:15` imports `GithubToolInput/Output` from `subagents/reviewer.ts`; `subagents/planner.ts:20-22` and `worker.ts:66-68` import tool I/O types from `tools/`. Fix: tool I/O types belong with the tool; move the Github thread types into `tools/github-thread-tool.ts` and have reviewer import them. -- [low] [category: arch] `src/state/schema.ts` — fan-in hub imported by plan, loop, observability, orchestrator, subagents, cli, resume-normalize. Acceptable as a schema leaf (it imports nothing upward), but it holds domain types under a persistence-named module; renaming/moving per the `domain/` suggestion resolves three of the cycles above at once. -- Clean leaves confirmed: `logger/`, `fs/`, `github/`, `openrouter/` import nothing upward (logger imports nothing relative at all). No god module that both fans in and fans out except the two composition roots flagged above. -- `packages/ai-claude-compat` (`@developerz.ai/ai-claude-compat`, version-locked 0.0.44) — Claude-Code-style agent primitives for the AI SDK: fs/bash/edit/search tools, subagent-as-tool factory, pool, skills/agents loaders, tool hooks. Imported by 17 shipped aitm files, overwhelmingly in `subagents/` plus loop/orchestrator/compaction; only leakage into low layers is `config/schema.ts:9` and `config/config-loader.ts:14` importing `CommandRule` (a type). Boundary is clean: aitm never reaches into `ai-claude-compat/src/*` deep paths, only the package export. One duplication smell: both packages ship an `atomic-write` (`aitm/src/fs/atomic-write.ts` vs `ai-claude-compat/src/atomic-write.ts`) — [low] consider re-exporting one from the other. - -### 3. Portability - -- [low] [category: portability] Zero hits for `Bun.`, `Deno.`, `import.meta.main` in shipped code (only comments referencing the ban). All node builtins consistently `node:`-prefixed. No `require()`, no `__dirname`, no top-level await. `cli/cli.ts:195` uses an `isEntrypoint(import.meta.url, process.argv[1])` helper instead of `import.meta.main` — correct cross-runtime pattern. This section is exemplary. -- [med] [category: portability] 16 shipped files use the `process` global with zero `from 'node:process'` imports anywhere. Fine on Bun/Node; on Deno the global only exists via the npm-compat layer (and natively only from Deno 2.0). The stated floor is "Deno ≥ 1.40", where a plain ESM import of these modules has no `process` global. Fix: either import `process` from `node:process` (works on all three) or document that Deno support means `deno run npm:@developerz.ai/aitm` only. -- [med] [category: portability] `src/mcp/oauth.ts:107-109` — `fileURLToPath(join(dirname(import.meta.url), '..', 'templates', ...))`: `path.join` on a `file:///` URL string collapses `///`→`/`, which happens to survive URL re-parsing on POSIX but breaks on Windows (drive-letter paths) — and the path never exists in dist anyway (see templates finding). Fix: `fileURLToPath(new URL('../templates/…', import.meta.url))`, plus ship or delete the templates. - -### 4. Test pairing - -- [low] [category: test] Only 3 of ~70 shipped files lack a paired test: `src/github/errors.ts` (25 lines, error classes), `src/github/schema.ts` (33 lines, types), `src/credentials/defaults.ts` (38 lines, constants). All near-pure declarations; house rule says "no exceptions", so either add trivial tests or amend the rule for type/constant-only files. (`subagents/prompts/prompt-snapshots.test.ts` is a test-only file with no source pair — fine.) -- [med] [category: test] `.github/workflows/ci.yml:39-44` — CI deliberately does **not** run `bun test` (documented Bun `node:test` shim bug, oven-sh/bun#5090); Bun job runs only install/lint/typecheck. This contradicts CLAUDE.md "Tests must pass under both `bun test` and `node --test` … runtime portability is enforced by CI." package.json still advertises `"test": "bun test"`. Fix: update CLAUDE.md's testing claim to match reality, or restore a `bun test` job scoped to files unaffected by the bug; `test:node` and `test:integration` are real and run in CI (`ci.yml:73` + integration job). - -### 5. Export hygiene - -- [low] [category: arch] Default exports: **zero**. `any`: **zero** in shipped code (one comment mention, `subagents/worker.ts:977`). `as unknown as`: **zero** (two comment mentions explaining why it's avoided: `compaction/compaction-step.ts:26`, `openrouter/model-limits.ts:21`). House rules fully held. -- [low] [category: arch] `src/index.ts` — barrel is curated ("Keep this list narrow") but leaks web-search implementation details: `decodeDdgHref`, `parseDuckDuckGoHtml`, `DEFAULT_STEALTH_HEADERS`, `DEFAULT_IMPERSONATE_TARGETS`. These are DuckDuckGo-scraper internals; any change is now a public-API break. Fix: drop them from the barrel (tests can import the module file directly). - -### 6. Out-of-scope creep - -- [high] [category: scope] `src/mcp/oauth.ts:76-77, 182-194` — spins up inbound HTTP: `net.createServer()` for port probing and `http.createServer(...).listen(port, 'localhost')` as an OAuth loopback-redirect listener, plus `openBrowser()`. CLAUDE.md v1 exclusions ban "Webhooks or any inbound HTTP" and instruct "stop and surface it". Mitigations: localhost-only, ephemeral, exists to serve aitm's *MCP-client* role (which is in scope), and the Provider-section "No OAuth" rule is about provider credentials, not MCP. Still, it is shipped inbound-HTTP code in a codebase whose rules say there is none. Surface for an explicit decision: either amend CLAUDE.md's exclusion to "no inbound HTTP *except* the localhost MCP OAuth loopback", or drop remote-OAuth MCP servers for v1. -- Clean otherwise: no mailbox/inbox code, no MCP *server* exposure (`McpServer` types in `mcp/schema.ts` are client-side config for external servers), no webhook endpoints, no Docker/devcontainer artifacts anywhere under `packages/aitm/`. - -## Structural recommendations - -- **Extract a leaf `domain/` module** holding `PrGroup`, `Task`, `TaskComplexity`, `Role`, `WorkerDelivery`, tool I/O types. This single move dissolves the state↔plan, state↔subagents, tools↔subagents, and config↔credentials↔mcp dir-level cycles — every cycle found is a shared-type cycle, not a logic cycle. -- **One composition root, not two.** Move the wiring halves of `cli/commands.ts` and `loop/run-loop-adapter.ts` into a dedicated `src/composition/` (or `bootstrap/`) module; `RunLoopInput`/`RunMergeFlowInput` move with it, killing the cli↔loop cycle and restoring "CLI = arg parsing and exit codes only". -- **Hoist all default constants into config-adjacent leaves** (`DEFAULT_MAX_CI_FIX_ATTEMPTS`, `DEFAULT_LLM_STEP_TIMEOUT_MS`, `DEFAULT_MCP_DEFER_TOOLS_OVER`) so `config/` never imports from loop/subagents/mcp. -- **Refresh CLAUDE.md's module map and testing/provider claims** — 10 of 19 dirs are undocumented, the "provider wiring in one place" and "bun test enforced by CI" statements are both currently false; the map is the audit baseline and it has drifted further than the code. -- **Resolve the templates/oauth decision**: delete `src/templates/*.html` + fix the URL-path construction in `mcp/oauth.ts`, and get an explicit CLAUDE.md carve-out (or removal) for the OAuth loopback HTTP listener — it is the only real scope-rule conflict in the package. - -Overall shape: unusually strong conformance on the mechanical rules (zero `any`, zero default exports, zero Bun leaks, 96%+ test pairing). The system-level debt is concentrated in exactly two places — the double composition root with its cli↔loop cycle, and shared domain types scattered across `state/`/`subagents/`/`tools/` creating type-only cycles — plus documentation (CLAUDE.md) that has fallen behind a codebase that nearly doubled its module count. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/overview.md b/docs/plans/2026/07/23/101-aitm-audit-improvements/overview.md deleted file mode 100644 index 910f10b0..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/overview.md +++ /dev/null @@ -1,51 +0,0 @@ -# aitm audit — fixes & improvements - -## Goal -Fix the bugs, resource-lifecycle leaks, and architecture drift found by an 8-agent parallel audit of `packages/aitm` (2026-07-23), and add the small missing capabilities the audit surfaced. Raw per-agent reports live in [`findings/`](findings/) — each slice cites the items it executes. - -## Context -- Bun dev runtime; code must run unchanged on Bun, Node ≥20, Deno ≥1.40. ESM only. TS `strict`, no `any`, no `as unknown as`. Named exports only. Every module has a paired `*.test.ts`. -- Provider: OpenAI-compatible via `Credentials` (`OPENROUTER_API_KEY` / baseURL profiles). No Anthropic SDK. -- Audit verdict: mechanical house rules are held nearly perfectly (zero `any`/default exports/`Bun.*`). Debt clusters in: cancellation (one signal reaches one LLM call site), a double composition root (`cli/commands.ts` + `loop/run-loop-adapter.ts`), `mcp/oauth.ts` (largest problem cluster), and duplicated-but-diverged pipelines (`aitm start` vs `aitm merge-pr`). -- Reference patterns to copy: `subagents/worker.ts:984-1038` (correct abort wiring), `fs/atomic-write.ts` (correct cleanup), `mcp/stdio-process-registry.ts` (correct process reaping), `tools/web-fetch.ts` (correct fetch timeouts). - -## Findings index -| File | Area | -| --- | --- | -| [`findings/01-loop.md`](findings/01-loop.md) | loop/ | -| [`findings/02-subagents-orchestrator.md`](findings/02-subagents-orchestrator.md) | subagents/, orchestrator/ | -| [`findings/03-cli-config.md`](findings/03-cli-config.md) | cli/, config/ | -| [`findings/04-github-state-workspace-fs.md`](findings/04-github-state-workspace-fs.md) | github/, state/, workspace/, fs/ | -| [`findings/05-mcp-openrouter-credentials-agent-config.md`](findings/05-mcp-openrouter-credentials-agent-config.md) | mcp/, openrouter/, credentials/, agent-config/ | -| [`findings/06-observability-logger-compaction-plan-tools.md`](findings/06-observability-logger-compaction-plan-tools.md) | observability/, logger/, compaction/, plan/, tools/ | -| [`findings/07-resource-lifecycle-sweep.md`](findings/07-resource-lifecycle-sweep.md) | cross-cutting RAII | -| [`findings/08-architecture-sweep.md`](findings/08-architecture-sweep.md) | cross-cutting architecture | - -## Plan files (execute in order) -1. [`01-data-safety-state.md`](01-data-safety-state.md) — stop destroying user work/state: dirty-tree guard, run lock, init/no-resume clobber, schemaVersion. -2. [`02-config-trust-secrets.md`](02-config-trust-secrets.md) — trust boundaries + secret redaction: project bashRules, prototype pollution, scrubber gaps, git-exec bypass. -3. [`03-cancellation-resources.md`](03-cancellation-resources.md) — one cancellation + disposal convention: abortable sleep, signal threading, execa timeouts, Disposer, exit/flush. -4. [`04-mcp-oauth.md`](04-mcp-oauth.md) — MCP connect/close deadlines, oauth PKCE + lifecycle fixes; carries the inbound-HTTP scope decision. -5. [`05-loop-flows.md`](05-loop-flows.md) — loop correctness: no-changes burn loop, prContext.clear, self-review error masking, start/merge-pr pipeline unification. -6. [`06-github-client.md`](06-github-client.md) — gh wrapper robustness: ENOENT, poll retry, pagination, cursor drop, NODE_ENV sleep, domain errors. -7. [`07-subagents-orchestrator.md`](07-subagents-orchestrator.md) — subagent wiring: init forwarding, reviewer `git add -A`, commit-message fallback, injection envelopes, orchestrator dead-path decision. -8. [`08-compaction-observability.md`](08-compaction-observability.md) — compaction overflow guarantee + Logger actually wired + misc tool/plan fixes. -9. [`09-cli-config-ux.md`](09-cli-config-ux.md) — CLI/config paper cuts and missing UX: `--` sentinel, help drift, precedence, `config list --effective`. -10. [`10-architecture-refactors.md`](10-architecture-refactors.md) — structural moves: one composition root, `domain/` leaf types, module splits, dedup helpers, CLAUDE.md refresh. -11. [`11-tests-ci-docs.md`](11-tests-ci-docs.md) — remaining test pairs/coverage gaps, oauth test rewrite, CI-vs-CLAUDE.md testing claim. - -Slices 1–9 are independent of each other (disjoint files except noted `Depends on`). Slice 10 moves code that 1–9 touch — do it after. Slice 11 closes whatever gaps 1–10 didn't already cover with their own tests. - -## Done when -- All high-severity findings fixed with regression tests; med-severity fixed or explicitly deferred in `status.yml` notes. -- `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint` green. -- A single Ctrl-C cancels a run (LLM streams, sleeps, gh/git children) within seconds, verified by test. -- No resource acquired in `src/` lacks a guaranteed release on error/abort paths (Disposer or try/finally). -- CLAUDE.md module map, provider invariant, and testing claims match the code. - -## Risks / open questions -- **Decision (owner): oauth inbound HTTP.** `mcp/oauth.ts` ships a localhost HTTP listener; CLAUDE.md bans inbound HTTP. Options: amend CLAUDE.md with an RFC 8252 loopback exception, or drop remote-OAuth MCP servers for v1. Slice 04 blocks on this. -- **Decision (owner): orchestrator agent-as-tool path.** `Orchestrator.build` + `subagent-tools.ts` (~400 LOC) have zero production callers and have drifted. Delete or wire — slice 07. -- **Decision (owner): `src/templates/*.html`.** Never shipped in dist; delete + keep inline fallback, or add a build copy step — slice 04. -- Fixing `datetime` tool and `--no-resume` semantics changes behavior tests currently bless — update tests deliberately, not mechanically. -- Compat package (`ai-claude-compat`) needs a `signal` param on `runSubagent`/`agent.generate` for slice 03; that is a cross-package change, version-locked at 0.0.44. diff --git a/docs/plans/2026/07/23/101-aitm-audit-improvements/status.yml b/docs/plans/2026/07/23/101-aitm-audit-improvements/status.yml deleted file mode 100644 index 2c2ead54..00000000 --- a/docs/plans/2026/07/23/101-aitm-audit-improvements/status.yml +++ /dev/null @@ -1,45 +0,0 @@ -plan: 101-aitm-audit-improvements -title: aitm audit — fixes & improvements -status: in_progress # not_started | in_progress | blocked | complete | superseded -created_by: plan-author -worked_by: "" -owner: plan-owner -percent: 9 -current_focus: "03-cancellation-resources — PR 6 steps 1-4 (signal on SubagentInit/ScoutAgentInit; WorkerInput.signal passed from every production caller; signal threaded through the loop polls and grace sleeps; timeout + cancelSignal at all four execa chokepoints and AbortSignal.timeout on both catalog fetches) landed, PR 7 steps 1-2 (run-scoped Disposer wired into the adapter's finally and abort reaper; planner transcript closed in a finally; per-group conversations released via WorkLoopOrchestrator.releaseGroup; createLlmFetch returns a `{ fetch, close }` handle disposed at command scope and no longer clobbers a caller's dispatcher) and PR 7 step 3 (unified CLI shutdown: main's code → process.exitCode not a hard process.exit; one finally removes the signal handlers and flushes the reporter on the normal, error and first-signal paths; the second-signal force-quit still flushes bounded via forceExit) landed; 02-config-trust-secrets steps 1-6 and 01-data-safety-state steps 1-5 landed; 10-architecture-refactors step 1 (extract leaf src/domain/) landed — the four shared-type dir cycles state↔plan, state↔subagents, tools↔subagents, config↔credentials↔mcp are dissolved (remaining giant dir-SCC is the cli↔loop composition roots, step 2's job)" -slices: - - file: 01-data-safety-state.md - status: in_progress - percent: 62 - - file: 02-config-trust-secrets.md - status: in_progress - percent: 28 - - file: 03-cancellation-resources.md - status: in_progress - percent: 72 - - file: 04-mcp-oauth.md - status: not_started - percent: 0 - - file: 05-loop-flows.md - status: not_started - percent: 0 - - file: 06-github-client.md - status: not_started - percent: 0 - - file: 07-subagents-orchestrator.md - status: not_started - percent: 0 - - file: 08-compaction-observability.md - status: in_progress - percent: 10 - - file: 09-cli-config-ux.md - status: not_started - percent: 0 - - file: 10-architecture-refactors.md - status: in_progress - percent: 12 - - file: 11-tests-ci-docs.md - status: not_started - percent: 0 -evidence: [] -notes: "Decision #1 (oauth inbound-HTTP carve-out, slice 04): RFC 8252 loopback-only exception approved — allow http://127.0.0.1:PORT and http://[::1]:PORT for MCP OAuth redirects; remote inbound HTTP servers remain banned. Decision #2 (orchestrator agent-as-tool path, slice 07): DELETE — Orchestrator.build + subagent-tools.ts (~400 LOC) have zero production callers and have drifted; production uses WorkLoopOrchestrator port with direct finalizeCommit/openPr methods instead. Subagent-tools only used in tests. EXECUTED (slice 07, PR 0): deleted subagent-tools.ts + subagent-tools.test.ts and Orchestrator.build, plus OrchestratorBuildContext, OrchestratorTools, resolveMaxSteps, DEFAULT_MAX_STEPS and OrchestratorInit.maxSteps (the run-loop-adapter construction site dropped the field). ORCHESTRATOR_ROLE_PREFIX could NOT simply be removed — buildSystemPrompt still feeds the two surviving production model calls (finalizeCommit's commit-message refine and openPr's composePr), so it was REPLACED with COMPOSER_ROLE_PREFIX whose prose matches the real tool surface (author commit + PR prose, no subagent routing), which also closes the 'prompt contradicts the tool surface' drift the finding named; ModelProvider moved from the deleted file into orchestrator.ts. Decision #3 (templates, slice 04): DELETE HTML files, KEEP inline getDefaultHtml — src/templates/*.html are dead assets (never copied to dist because tsconfig.build.json only includes src/**/*.ts); inline fallback already correct. Decision #4 (dirty-tree guard, slice 01 step 1): REFUSE at run entry, opt out with `--allow-dirty` (CLI-only, never a config-file key) which restores the old discard-and-clean behaviour; no auto-stash — the refusal message points at `git stash -u` instead, so aitm never owns a stash the operator did not ask for. The refusal is typed (DirtyWorkingTree) and aborts the whole run rather than blocking each group. Decision #5 (run lock, slice 01 step 2): exclusive .ai-task-master/run.lock via open(wx) carrying {pid, host, startedAt, token}; acquired at run entry in runStart (covers resume) and runMergePr, released in try/finally. Stale locks are reclaimed automatically only when the recorded host is this machine AND kill(pid, 0) reports ESRCH — a holder on another host, or one that answers EPERM, is never stolen; no heartbeat (a crash-proof lock nobody can clear is worse than the race). release() only unlinks its own token, and cleanupOnSuccess() exempts run.lock so the holder alone drops it. Reclaim of a stale lock is itself serialized on a marker named for a fingerprint of the debris bytes (run.lock.reclaim-), created with the same open(wx): two runs judging the same dead holder would otherwise each unlink the other's replacement and both proceed, so exactly one process may clear a given record, and only while the bytes on disk still match the ones it judged dead — the loser refuses rather than loops, and a crash inside that window is recovered by the `rm run.lock` the refusal already prints. Decision #6 (init clobber guard, slice 01 step 3): StateStore.init refuses when state.json already exists, throwing typed StateAlreadyInitialized, unless the caller passes { force: true }; the probe is a plain check-then-atomicWrite, not create-exclusive, because run.lock already provides cross-process exclusion and a claim-first scheme would leave an empty state.json blocking the next start after a mid-init crash. Callers force only where a clobber is intended: runStart when a finished run is superseded or state.json is unparseable (a missing file needs no force), and merge-pr --no-resume (step 4 replaces that clobber with an in-place currentPr update). Decision #7 (merge-pr --no-resume, slice 01 step 4): UPDATE IN PLACE, do not refuse — the flag's contract is 'do not trust the persisted currentPr', so the re-resolved take-over PR is written through StateStore.update and the run keeps its plan, group stages, options, sessionCount and runId (refusing when prGroups is non-empty was the other option in the plan; it would make the flag unusable on exactly the runs it exists for). merge-pr no longer passes force at all: a missing state.json still synthesizes + init()s a take-over state, and a present-but-unreadable one is refused with the same 'fix or delete' exit as the resume path rather than being rewritten. Decision #8 (state schema versioning, slice 01 step 5): state.json carries schemaVersion, and state/migrations.ts lifts a file to CURRENT_SCHEMA_VERSION before RunStateSchema validates it — one step per version, keyed by the version it reads, replacing the four unconditional read-time coercions in state-store (coerceLegacyTasks/legacyTask/coerceLegacyStage/inferStage). v0 = the unversioned shape (string[] tasks, no PrGroup.stage); v1 = today's. A file whose version is newer than this build, or is not a version at all, is REFUSED (UnsupportedSchemaVersion), never rewritten — and that error deliberately does not carry the `:` prefix that runStart's isMissingOrInvalidState reads as 'corrupt, safe to discard', which would otherwise force-init over a live run purely because it came from a newer aitm; commands.ts also excludes the error type explicitly rather than trusting the message shape. Consequence: coercion now runs only for v0 files, so an off-schema in-memory write (string tasks) fails validation at write time instead of being silently repaired on the next read — three integration fixtures that relied on that were corrected to real Task[]. Decision #9 (project bashRules, slice 02 step 1): TIGHTEN-ONLY, do not strip the field — a project config's `deny` rules are honored (a repo narrowing the model's shell is always safe and is the legitimate use of the key) but its `allow` rules are dropped + warned, since first-match-wins puts an early allow ahead of DEFAULT_BASH_RULES and would hand a cloned repo back `git push --force` / `gh pr merge` / `git reset --hard`. The surviving project denies are now MERGED in front of the global rules instead of replacing them wholesale — wholesale replacement was itself a widening vector (a repo could drop the operator's own denies just by declaring one rule of its own). Effective order: project denies < global rules < built-in defaults. Only the user-owned ~/.aitm.json can still allow-override a built-in deny (the issue #113 escape hatch). Full strip (matching hooks/formatCommand) was the other option in the plan; it was rejected because it also kills the safe, useful direction of the key. The allow-drop lives in ConfigLoader.stripProjectBashAllowRules, called from stripUntrustedProjectFields so project-scope sanitizing stays in one place. Decision #10 (profile names, slice 02 step 2): REJECT the reserved names rather than support them as quoted keys — `__proto__`/`prototype`/`constructor` are refused by every ProfileManager command (assertProfileName, mirroring splitKey's FORBIDDEN_KEY_SEGMENTS check) and membership everywhere moved from `name in profiles` / `profiles[name]` to `Object.hasOwn`. Own-property lookup alone would have made an own `__proto__` key technically safe, but a profile whose name reads as a prototype member is a trap for every later consumer (and JSON round-trips of that key differ between parsers), so the name surface is closed instead. Before: `profile set __proto__ baseURL ` wrote onto Object.prototype in-process, `use __proto__`/`use constructor` passed the `in` guard and persisted a dangling activeProfile, and `add constructor` failed with a false 'already exists'. ConfigLoader.resolveActiveProfile got the same own-property guard so a config written before this fix resolves to the existing dangling-pointer warning instead of handing Object.prototype back as the active profile. Decision #11 (env-value scrubbing, slice 02 step 6): REGISTER LITERAL KEY VALUES at startup — logger/secret-registry.ts holds the exact provider keys this process was configured with, and scrubSecrets consults it before its shape patterns, so all three channels (logger, step-progress, error-reporter) are covered by construction through the one scrubber they already share rather than by three separate hooks. ConfigLoader.resolve is the collection point (the only module that reads the config files): env OPENROUTER_API_KEY, the global openrouterApiKey, and EVERY profile's key, not just the active one, since an inactive profile's key still reaches output via error messages or a mid-run switch. Project scope is deliberately excluded — its key is stripped upstream and never used, and registering an attacker-chosen literal would let a hostile repo blank arbitrary text out of the operator's logs. The registry is append-only for the process lifetime (a key that was live earlier must stay redacted in already-queued log lines and error events) and refuses values under 8 characters, so a placeholder or test stub cannot black out ordinary prose. Decision #12 (subagent cancellation, slice 03 / PR 6 step 1): AGENT-SCOPED signal — `SubagentInit.signal`/`ScoutAgentInit.signal` are forwarded into compat's `createSubagent` (new `SubagentConfig.signal`), which applies the signal to EVERY generate the agent makes, rather than threading it through each runner call. The per-call route was the other option; it cannot work for the Planner/Reviewer/scouts, whose generations are owned by `runWithSchemaRetry` (the caller never touches them), so it would have needed a second `signal` on `SchemaRetryOptions` plus registry reads in four runners to cover the same ground. Composition, not replacement: the run signal and a per-call `abortSignal` are merged through the existing `linkController` bridge (released once the call settles, so a run-scoped signal never accumulates listeners), and the configured per-step deadline stays armed — whichever fires first wins, and a cancel is still never relabelled a StepTimeoutError. Forwarding itself moved into ONE `forwardInit` helper: planner previously dropped `prepareStep` + `providerOptions` and reviewer dropped `providerOptions`, so a dial set at a create site was silently ignored per role. Decision #13 (editor-fanout cancellation, slice 03 / PR 6 step 2): PASS THE SIGNAL TWICE, from ONE expression per call site — `WorkerInput.signal` was a dead field, so a Ctrl-C stopped the Coordinator's generation while every editor leaf ran to completion (the leaves are raw `generateText` calls under the fanout's own AbortController, not agent steps, so `SubagentInit.signal` cannot reach them). The task path carries it through the `WorkLoopOrchestrator` port as `WorkerInvocation.signal` rather than having the adapter read its own `input.signal`: the WorkLoop is what owns run cancellation (its post-batch `signal?.aborted` check already claimed the abort reached in-flight LLM calls), and reading the adapter's copy would have left the port field just as dead one level up. The adapter falls back to `input.signal` when the invocation omits it, and uses that single `workerSignal` for BOTH the agent and the Worker input, so the two can never drift apart. The CI-fix, self-review and take-over sessions already held the run signal for their agent and now put it on their `WorkerInput` too. Decision #14 (loop-poll cancellation, slice 03 / PR 6 step 3): A CANCELLED POLL RETURNS A NON-VERDICT, callers re-check — `GitHubClient.waitForChecks(pr, signal?)` now takes the run signal (both `this.sleep` sites plus a `signal.aborted` check at the top of each poll iteration), and on abort returns `{ state: 'pending' }` rather than throwing. Throwing was the other option; it was rejected because the two existing catch sites already ascribe meaning to their errors (`CiFailed` → `--admin` force-advances to reviews, i.e. straight at the merge) and a third error type would have had to be excluded from each by hand. 'pending' is the honest answer — the poll never settled — but it is NOT a CI state, so every caller re-checks `signal.aborted` before branching: `handleWaitingCi` (else 'pending' reads as not-green → a persisted ci-failed stage a resume would 'fix' on a PR whose CI never failed), the take-over loop (else the fix Worker, Reviewer and force-push all run on a stopped run), and the prPerTask `autoMergeFlow` (else 'not failing' falls straight through to `gh pr merge`; it throws, since a silent return there records the group merged). Handlers signal a cancel by returning their CURRENT stage, never 'blocked': the group's persisted stage stays where it is, so a resume re-enters at the same point instead of needing a blocked state un-stuck, and `driveStages` checks the signal before dispatching ANY handler — the transitions past waiting-ci spend LLM calls or merge. Also threaded: the review grace (`StageDeps.sleep`), the take-over grace + cooldown, and `rebaseAndForcePush`, which refuses to start another AI conflict-resolution attempt on a cancelled run and aborts the half-applied rebase on the way out rather than leaving the operator's checkout mid-rebase. Decision #15 (execa chokepoint deadlines, slice 03 / PR 6 step 4): DEADLINE ALWAYS, SIGNAL WHERE THE RUN OWNS ONE — all four subprocess chokepoints (`github-client.defaultRunCmd`, `workspace/git-exec.runGit`, `orchestrator.defaultRunCmd`, `tools/fetch-html`'s exec seam) now map their options onto execa's `timeout` + `cancelSignal`. A default deadline is applied when the caller names none, per chokepoint and per workload: gh 5 min (slowest healthy call is a CI log download), git 10 min (a clone-less fetch on a large repo), the orchestrator's amend seam 1 min (purely local plumbing). One shared constant was the other option; rejected because a single number is either too tight for `git fetch` or too slack for `git commit --amend`, and the existing per-module `RunCmd` duplication is deliberate (the orchestrator only shells git, and importing from `github/` would invert the layering) — the dedup is slice 10's job, not this one. Nothing else bounded these: `CHECKS_TIMEOUT_MS` bounds waitForChecks ITERATIONS, never one hung child, so a wedged `gh api …/logs` blocked the run forever and a SIGINT could not kill an in-flight child (only the second-SIGINT force-exit did, orphaning it). The run signal is bound into `GitHubClient` ONCE, in the constructor via `withSignal`, rather than threaded through its twenty-odd call sites — the wrapper decorates whatever RunCmd it is given, so injected test stubs stay in charge and no call site can forget it; `waitForChecks` re-checks `signal.aborted` after the `gh` call too, since a killed child's truncated stdout would otherwise be reported as `gh pr checks failed` and turn a clean cancel into a run-ending error. A timed-out or cancelled child reports execa's `shortMessage` as its stderr, because a signal-killed process writes none of its own and every caller renders ` failed: `. `OrchestratorInit.signal` is new and covers the Orchestrator's OWN work (the two direct generateText calls plus the amend seam) — subagent tools keep cancelling through `OrchestratorBuildContext.signal`, which is per-group. `fetch_html` takes the tool call's `abortSignal` (its `--max-time` bounded curl but nothing killed it when the generation was cancelled), and `isFetchHtmlAvailable`'s probe got its own 5s deadline since it runs at wiring time, before any tool call exists to cancel. Also in this step: both OpenRouter catalog fetches (`client.listModels`, `reference-catalog`) now pass `AbortSignal.timeout(20s)` — `fillFromReference`'s try/catch guards a rejection, never a hang, so a stalled `/models` stalled startup. PR #286 review follow-up extended the same step three ways: those two catalog fetches also take the run signal (composed with the deadline in `catalogFetchSignal`, hand-rolled because Node 20.0–20.2 lacks `AbortSignal.any`, and released once the request settles — the deadline alone left a Ctrl-C waiting out 20s of a startup GET); `subagent-tools.makeWorkerTool` puts the run signal on its `WorkerInput` too, closing the same editor-fanout hole Decision #13 fixed on the task path; and `rebaseAndForcePush` now refuses BEFORE it fetches or rebases on an already-cancelled run, re-checks after the resolver clears conflicts and again before the force-push, and passes the signal to its git children — but deliberately NOT to `git rebase --abort`, since an already-aborted signal would kill the cleanup on spawn and strand a half-applied rebase in the operator's checkout. Decision #16 (run-scoped disposal, slice 03 / PR 7 step 1): ONE STACK, TWO DRAINS — the adapter's run-scoped acquisitions (the MCP manager, the background ProcessManager, and the abort listener itself) are registered on a `Disposer` that BOTH the adapter's `finally` and `reapOnAbort` drain, replacing the two hand-written teardown bodies that had already drifted apart: the reaper closed MCP fire-and-forget with no `.catch`, and the finally's `mcp.close()` hid behind an `mcpConnected` flag set only AFTER connectAll returned — so a transport constructor throwing mid-list (mcp-client.ts builds the config outside the per-server try) leaked every client that had already connected, stdio children included. The close is therefore registered BEFORE connectAll; close() is idempotent, so a run that never connects pays nothing. Each release now runs EXACTLY ONCE, from whichever exit reaches it first (the old finally's repeat of killAll/close was belt-and-braces, and Disposer queues a drain started while another is in flight, so the finally awaits the abort-time teardown instead of racing it). A disposal failure is written to stderr, never rethrown: a throw out of `finally` would replace the run's real result, and the abort reaper has no caller left to catch anything. Consequence: a seam-provided McpClientManager is now closed on the normal path too (an abort already closed it) — the adapter owns the run's manager for the run's duration, whoever constructed it. Also in this step: `plannerRecorder.end()` moved into the same `finally` as the heartbeat stop, since the planner stage is recorded but never resumed and a throw would leave an open record nothing ever closes — the worker / CI-fix / reviewer recorders deliberately keep the old shape, because an unfinished record is exactly what makes THOSE stages resumable. And `WorkLoopOrchestrator` gained an optional `releaseGroup(groupId)`, called from `runGroup`'s finally (so merged, blocked, awaiting-pr, cancelled and the rethrown dirty-tree precondition all report), letting the adapter's bridge drop that group's carried Coordinator conversation (issue #107 workerHandles) and CI-fix handle: a finished group is never rescheduled — `PlanGraph.ready()` only picks 'pending' — so those full ModelMessage[] histories were pure accumulation for the rest of the run. Decision #17 (keep-alive transport ownership, slice 03 / PR 7 step 2): RETURN A HANDLE, DISPOSE AT COMMAND SCOPE — createLlmFetch now returns `{ fetch, close }` instead of a bare fetch, and runStart/runMergePr register `close` on a Disposer of their own, drained next to the run-lock release. The adapter's disposer was the other option; it is too narrow — the transport is built before the loop starts and is used by the style digest and the planning phase too, so a release that dies with the loop would either fire early or (for merge-pr paths that never reach the adapter) never fire at all. Nothing had ever closed the undici Agent: one leaked pool per createLlmFetch call, each holding idle sockets for its 60s keep-alive window, masked only because cli.ts always process.exit()s — any embedding of the exported main() kept the event loop up. `close` calls the Agent's destroy(), NOT close(): close() waits for in-flight requests, and one stuck request would hang run teardown and with it the CLI's exit, while at run end nothing is in flight (every model call is awaited), so this is a socket release rather than a cancellation. It is idempotent, so a double drain cannot reject. A constructed Agent lacking destroy() is now rejected by the shape guard (degrading to the provider's default fetch) rather than handed out as an unreleasable pool. Second fix in the same call: the wrapper spread `{ ...init, dispatcher }` unconditionally, silently discarding any caller-supplied `init.dispatcher` (a proxy agent, a test transport) while still reporting success — the keep-alive dispatcher is now only filled in when the caller left it unset. `disposeQuietly` moved from run-loop-adapter.ts into disposer.ts on its second and third callers, so both scopes share one 'report, never rethrow out of a finally' implementation. Decision #18 (CLI shutdown unification, slice 03 / PR 7 step 3): EXIT-CODE NOT HARD-EXIT, ONE FLUSH PATH — the entrypoint now sets `process.exitCode` and lets the event loop drain instead of `process.exit(code)`, so buffered stdout/stderr (a long `config list` JSON, the end-of-run PR-links block in a `| tee`) and any pending state/log appends finish rather than being truncated mid-pipe; nothing keeps the loop alive at that point because the command's own Disposer has already destroyed the keep-alive Agent (Decision #17) and the loop stopped its heartbeat in its finally. A new `runEntrypoint(reporter, argv, proc?, run?)` owns the single teardown: `main`'s code — or 1 on a thrown error, which is captured + printed first — becomes `exitCode`, then ONE `finally` removes the signal handlers and flushes the reporter, covering the normal, error AND first-signal paths alike (the first Ctrl-C aborts and the flow unwinds to `cancelled` through the same return, so it needs no separate flush). Handlers are removed BEFORE that final flush so a late Ctrl-C during it can't re-abort or print a second 'Cancelling'. `installSignalHandlers` therefore returns that remover and takes an `onForceExit` hook; the second-signal force-quit routes through the new `forceExit(reporter, code)`, which races `reporter.flush()` against a 2s unref'd deadline and exits exactly once on whichever settles first — the crash report now survives a force-quit that previously bypassed `reporter.flush()`, but a wedged flush still cannot trap the user. `SignalProcess.exit` was relaxed from `never` to `void` (the handler `return`s explicitly after it now) so a test double can record a call without throwing, and `EntrypointProcess` adds `exitCode` for injection. UsageTracker + a process-level Logger flush are deliberately NOT hoisted to the entrypoint by this step: `UsageTracker.totals()` already flushes inside runStart on the normal + cancelled paths, and there is no process-level Logger instance to flush — turning off the hard exit is precisely what lets those async writes drain — while persisting spend ACROSS a force-quit crash is finding 06/2's own remaining task. Decision #19 (domain errors, slice 06 step 1 second half): DELETE the three consumerless errors, TYPE the rest. PrNotFound, ReviewThreadStale and GhAuthRequired were exported but never thrown; wiring them (the plan's other option) was rejected because each names an EXPECTED non-result already modeled WITHOUT a throw — getPrForBranch returns null for 'no PR yet on this branch' (createPr's idempotent open and the take-over PR resolver both branch on that null), authStatus returns an { ok } result the CLI preflight branches on, and ReviewThreadStale had no detection site at all, so throwing would force try/catch onto the happy path and regress the design. But the errors.ts header promised 'never raw stderr; always domain errors' while nearly every client throw was a bare Error embedding raw stderr, so the same change introduces GhCommandFailed (fields: command, exitCode, stderr) and routes all twelve non-zero-exit gh/git throw sites through it — its message is byte-identical to the old string, so operators and the existing / failed/ message assertions are unaffected while the failure is now branchable by type. The four remaining plain Errors are exit-0 conditions the header never addressed (unparseable / unexpected-shape JSON carrying the SyntaxError as cause, plus two impossible post-conditions) and stay as-is; GhCliMissing was already wired to the spawn-ENOENT path by the prior task in this PR group. errors.ts gets its first paired test (errors.test.ts: name / instanceof / message + the stderr-blank-falls-back-to-stdout case), replacing the incidental name assertions previously living in github-client.test.ts. Decision #20 (post-compaction overflow guarantee, slice 08 step 1 first task): VERIFY EACH STAGE FITS, ESCALATE UNTIL IT PROVABLY DOES. compaction-step.ts's prune fast-path returned the pruned messages whenever it freed >= PRUNE_FREED_THRESHOLD (20k chars ~ 5k tokens) WITHOUT re-checking the result fits — so a window 20k tokens over budget stayed ~15k over and was sent, the exact overflow compaction exists to prevent (finding 08, HIGH). Fix: Compactor gained usableInputTokensFor(modelId) (shared with shouldCompact via a new private resolveWindow so the trigger budget and the verification budget can never drift; CompactorLike's Pick widened to include it), and the step now builds a `fits(candidate)` predicate = estimateTokens(candidate) + overhead < usable, where overhead = max(0, liveInputTokens - estimatedInputTokens) carries the fixed system-prompt + tool-schema cost the char estimate cannot see onto every not-yet-sent candidate, and `<` mirrors shouldCompact's compact-AT-budget boundary. Ladder: prune -> if fits return it; else summarize the pruned prefix -> if summary+tail fits return it; else hard-truncate. The prune fast-path keeps the freed>=THRESHOLD gate ANDed with fits (a small prune that happens to fit still summarizes — cheap insurance, and it preserves the freed=0 control-flow tests), rather than dropping the threshold, which would make the tiny-message stub tests short-circuit before summarize. New exported pure truncateOldestToFit(messages, fits, keepLeading?) is the model-free backstop: it drops the oldest messages after an optional protected prefix (the pinned summary) until fits, cutting ONLY before a non-tool message so a tool-result is never orphaned from its tool-call, returning the largest fitting suffix (or, when the fixed overhead alone exceeds the budget so nothing can fit, the smallest structurally valid candidate) and never empty. Behavior change: a summarizer that throws or returns empty NO LONGER blanket-passes-through — it passes through only when the pruned context already fits, and hard-truncates when it is still over budget, since the backstop must not depend on the summarizer that just failed. Follow-on tasks 66-68 shipped in the same PR: task 66 pins the run's first user message (the original task brief) verbatim ahead of any summary — best-effort, so an oversized brief that would breach the budget is dropped and the overflow guarantee still wins; task 67 guards estimateTokens with the cycle-safe safeStringify (mirroring jsonLength) so a circular ref or BigInt can no longer crash the hot compaction path; task 68 caches the compacted result keyed on messages.length and reuses it on a same-length repeat (a within-step retry, or the step right after a compaction whose `messages` override `ai` did not persist) instead of paying a second prune+summarize round trip. Decision #21 (leaf src/domain/, slice 10 step 1): EXTRACT A LEAF, and move the two provider-default CONSTANTS with the types — not types alone. New src/domain/ holds the shared work-unit types (Task/TaskComplexity in task.ts, PrGroup/PrGroupStatus/GroupStage in pr-group.ts), Role (role.ts), WorkerDelivery/FileChange (worker-delivery.ts) and the model-tier domain (Capability + DEFAULT_MODELS + OPENROUTER_API_BASE_URL + isOpenRouterEndpoint in model.ts, moved wholesale out of the now-deleted credentials/defaults.ts). It imports only zod — a true leaf (madge: zero outgoing dir edges). This dissolves all four shared-type dir cycles the audit named (finding 08 §2): state↔plan and state↔subagents (plan/ and subagents/ read PrGroup/Task/WorkerDelivery from domain now, and subagents/ no longer imports state/ at all), tools↔subagents (GithubToolInput/Output moved to their tool at tools/github-thread-tool.ts and Reviewer imports them from there — the finding's own fix, tool I/O belongs WITH the tool, NOT in domain, matching datetime/web-fetch/web-search already colocated), and config↔credentials↔mcp. The one place this went past 'pure type moves': the config↔credentials 2-cycle had a VALUE edge (config-loader/provider-presets imported DEFAULT_MODELS/OPENROUTER_API_BASE_URL from credentials/defaults) and ResolvedConfig CANNOT leave config/ — credentials→config is the correct direction (credentials consumes the resolved config to build handles) — so the only way to sever config→credentials was to relocate those constants below config; moving them into domain/model.ts alongside Capability (which DEFAULT_MODELS is keyed by) was chosen, and credentials/defaults.ts + its test were deleted/folded into domain/model.test.ts. Deliberately NOT in scope, left for step 2 (task 98): the remaining giant dir-SCC is entirely cli↔loop, the two composition roots — excluding them, the targeted subgraph is acyclic. Pure relocation, zero behaviour change: prod typecheck + biome lint clean, test-typecheck delta 0 vs the pre-existing loose-double baseline, Bun 2217 / Node 2174 / integration 43 all pass 0 fail. task 96 (hoist DEFAULT_MAX_CI_FIX_ATTEMPTS/DEFAULT_LLM_STEP_TIMEOUT_MS/DEFAULT_MCP_DEFER_TOOLS_OVER so config never imports upward from loop/subagents/mcp) and task 97 (dir-level madge check in CI) remain in this PR group. Raw audit reports in findings/." -last_updated: 2026-07-24 diff --git a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/01-fuzzy-edit-fallback.md b/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/01-fuzzy-edit-fallback.md deleted file mode 100644 index c1dd94bd..00000000 --- a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/01-fuzzy-edit-fallback.md +++ /dev/null @@ -1,50 +0,0 @@ -# 01 — Fuzzy edit fallback (exact-first, guarded) - -> Part of [`overview.md`](overview.md). Depends on: none. **Highest leverage — build first.** - -## The mechanism - -**OpenCode** (`sst/opencode` `packages/opencode/src/tool/edit.ts`): -- `replace()` (`:682`) tries a cascade of `Replacer` generators in order until one yields a locatable span: `SimpleReplacer` → `LineTrimmedReplacer` → `BlockAnchorReplacer` → `WhitespaceNormalizedReplacer` → `IndentationFlexibleReplacer` → `EscapeNormalizedReplacer` → `TrimmedBoundaryReplacer` → `ContextAwareReplacer` → `MultiOccurrenceReplacer` (`:694`). -- `LineTrimmedReplacer` (`:248`) matches ignoring per-line leading/trailing whitespace; `BlockAnchorReplacer` (`:288`) matches a ≥3-line block by its first+last line as anchors, scoring the middle with Levenshtein similarity ≥ 0.65; `WhitespaceNormalizedReplacer` (`:427`) collapses runs of whitespace. -- Anti-clobber: every candidate span is re-checked — uniqueness `index === lastIndex` unless `replaceAll` (`:717`), and `isDisproportionateMatch` (`:731`, called `:709`) **throws** if the matched span is far larger than `oldString` (≥ `max(oldLines+3, oldLines*2)` lines, or > `max(len+500, len*4)` chars). So a loose matcher can never silently swallow a huge region. - -**aitm today** (`packages/ai-claude-compat/src/edit-tools.ts`): -- `applyEdit()` (`:124`) is exact-only: `content.split(oldString)`. 0 occurrences → `throw "oldString not found"` (`:135`); >1 without `replaceAll` → `throw "not unique"` (`:138`). No fuzzy fallback. -- Wrapped by `editFileTool` (`:38`) and `multiEditTool` (`:59`); both first pass through `readForEdit` (`:96`) which enforces read-before-edit + hash-staleness (`fileState.isStale`, `:116`) — **aitm's edge over OpenCode, keep it untouched.** -- Impact: the dominant weak-model failure aitm already codes around — `EMPTY_MANIFEST_REASON` (`worker.ts:242`), `editorNoChangeReason` (`worker.ts:426`), phantom-edit blocks — is frequently a *near-miss* `oldString` (indentation off, a tab vs spaces, trailing space). Today that fails the leaf → fails the whole PR group. A fallback lands it. - -**Contrast — Aider** (`Aider-AI/aider`, `aider/coders/`): Aider avoids brittle string-match by using coarser edit *formats* — `editblock_coder.py` (SEARCH/REPLACE with its own flexible matcher `search_replace.py`) and `udiff_coder.py` (unified diff, applied with fuzzy hunk placement), plus whole-file mode. Same lesson from the other end: **never require a byte-exact anchor.** aitm keeps its exact-string tool (cheap, precise) and only *degrades gracefully* — the OpenCode approach, not a format change. - -## Files to change -- New: `packages/ai-claude-compat/src/edit-replacers.ts` (+ `.test.ts`) — port the 3 highest-value replacers as pure generators: `lineTrimmedMatch`, `blockAnchorMatch`, `whitespaceNormalizedMatch`, plus `isDisproportionateMatch`. Named exports, no `any`. Port from `opencode/.../edit.ts:248,288,427,731` but rewrite to aitm house style (kebab file, camelCase fns, `type` shapes) — do not import OpenCode. -- `packages/ai-claude-compat/src/edit-tools.ts:124` — `applyEdit`: after the exact `split` finds `occurrences === 0`, run the fallback ladder instead of throwing immediately. Keep the identical/empty/uniqueness guards ahead of it byte-identical. -- `packages/ai-claude-compat/src/index.ts` — export the new module's public surface if the package re-exports per-file (match existing pattern). - -## Steps -1. **`edit-replacers.ts`**: each matcher is `(content: string, find: string) => SpanMatch | undefined` where `SpanMatch = { spans: readonly string[] }` — `spans` is *every distinct location* the matcher found, each the *actual substring of `content`* to replace (so the caller still does one literal `indexOf`/`split` on a real span — no regex substitution surprises; mirror OpenCode returning `content.substring(...)`), in file order. The full candidate list (not just the first) lets the caller enforce uniqueness across fuzzy-equivalent candidates rather than only literal repeats of one span, and lets it tell an identically-formatted `replaceAll` from a heterogeneous one. Include `isDisproportionateMatch(matched, oldString): boolean` verbatim in spirit (`edit.ts:731`). -2. **`applyEdit` fallback** (`edit-tools.ts:124`): restructure the tail: - - Keep `:127` empty-guard, `:131` identical-guard. - - `const occurrences = content.split(oldString).length - 1`. - - If `occurrences >= 1`: **unchanged** exact path (`:138`–`:148`) — exact match always wins, byte-identical. - - If `occurrences === 0`: a **whitespace-only** `oldString` is refused up front (its trimmed form matches every blank line and would yield an empty span that `split('')` splices between every character); otherwise run `[lineTrimmedMatch, blockAnchorMatch, whitespaceNormalizedMatch]` in order and take the first `{ spans }`: - - `if (spans.some(isDisproportionateMatch(_, oldString))) throw` (OpenCode's wording, `edit.ts:711`). - - `if (spans.length > 1 && !replaceAll) throw` the not-unique error — using the **chosen matcher's own candidate count**, so two indentation/whitespace-variant blocks that share no literal text are still caught (a literal `content.split(span)` would count only one and silently edit it). - - `if (spans.length > 1 && replaceAll && new Set(spans).size > 1) throw` — a `replaceAll` across *differently-formatted* fuzzy candidates is refused loudly, since replacing them would clobber lines the model never spelled out (and replacing only the first would silently leave the rest). Identically-formatted candidates still replace all. - - replace via the existing `split(span).join(newString)` / single-`indexOf` code path (reuse, don't duplicate). - - No matcher hits → the existing `oldString not found` throw (`:135`), now truthfully "not found even fuzzily". -3. **`multiEdit`** (`:59`) needs no change — it calls `applyEdit` per edit (`:71`), so the fallback flows through; keep atomic all-or-nothing. -4. **Descriptions**: leave the tool descriptions (`:41`, `:62`) as-is — they still instruct exact strings; the fallback is a silent safety net, not a new contract to advertise (avoids the model getting lazy about anchors). - -## Tests (`edit-replacers.test.ts`, extend `edit-tools.test.ts`) -- `lineTrimmedMatch`: `oldString` indented 2 spaces vs file indented 4 → returns the file's real span; whitespace-only diff. -- `blockAnchorMatch`: 4-line block, middle line reworded < 35% → matches; anchors mismatch → `undefined`. -- `isDisproportionateMatch`: 1-line `oldString` matching a 20-line span → `true` (guard fires). -- `applyEdit` integration: (a) indentation-off `oldString` now applies + correct `count`/`snippet`; (b) a fuzzy match that is disproportionate still **throws** (no clobber); (c) a fuzzy match with 2 candidates — including two differently-spaced lines that share no literal text — + no `replaceAll` throws not-unique; (d) exact-match cases byte-identical (regression); (e) a whitespace-only `oldString` is refused, not spliced between characters; (f) `replaceAll` replaces all identically-formatted fuzzy candidates but is refused when they are heterogeneously formatted. -- `edit-tools.test.ts`: read-before-edit + staleness gates (`:102`,`:116`) still fire ahead of any fuzzy logic. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- An edit whose `oldString` differs from disk only by leading/trailing whitespace or a collapsed-whitespace run succeeds and returns the correct numbered snippet. -- No fuzzy path can clobber: disproportionate span → throw; non-unique fuzzy span → throw; stale/unread file → throw (unchanged). -- Exact-match and error-wording regressions all pass on Bun and Node. diff --git a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/02-bash-timeout-notice.md b/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/02-bash-timeout-notice.md deleted file mode 100644 index f3d9a0d0..00000000 --- a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/02-bash-timeout-notice.md +++ /dev/null @@ -1,43 +0,0 @@ -# 02 — Bash timeout notice (killed ≠ failed) - -> Part of [`overview.md`](overview.md). Depends on: none. - -## The mechanism - -**OpenCode** (`sst/opencode` `packages/opencode/src/tool/shell.ts`): -- The run races `handle.exitCode` vs `abort` vs a `timeout` sleep (`:540`). On the timeout branch it sets `expired = true` and force-kills (`handle.kill({ forceKillAfter: "3 seconds" })`, `:552`). -- The result appends a **distinct, actionable** block (`:562`): `shell tool terminated command after exceeding timeout ms. If this command is expected to take longer and is not waiting for interactive input, retry with a larger timeout value in milliseconds.` — wrapped in `` (`:583`). The model can tell *killed-on-timeout* from *exited non-zero* and self-corrects. - -**aitm today** (`packages/ai-claude-compat/src/bash-tool.ts`): -- `execBash` (`:185`) runs `execa('bash', ['-c', command], { timeout, detached })` plus a manual `setTimeout` that group-SIGKILLs the process tree (`:204`) — needed because the cwd epilogue makes every command multi-statement, so a child could hold the stdout pipe open past execa's own timeout. -- On kill, the awaited subprocess rejects → the `catch (ExecaError)` branch (`:218`) returns `{ stdout, stderr: err.stderr || err.message, exitCode: err.exitCode ?? 1 }`. **The model sees a generic non-zero result with no signal that it was a timeout, and no hint to raise `timeoutMs`.** Worse, on SIGKILL the cwd epilogue never runs (documented `:99`), so cwd tracking silently freezes with no notice. -- `BashOutput` (`:42`) already carries an additive optional marker (`denied?`) — the same pattern extends cleanly. - -**Contrast — OpenCode also streams** (`shell.ts:486`) so a long command is visible mid-run; aitm is non-streaming (plan 102 §07 owns streaming). This slice is orthogonal: even once streaming lands, the model still needs the *termination cause* in the tool result. aitm already leads on cwd-persistence (the epilogue, `:106`) which OpenCode lacks — so this is a targeted gap-fill, not parity chase. - -## Files to change -- `packages/ai-claude-compat/src/bash-tool.ts`: - - `BashOutput` type (`:42`) — add optional `timedOut?: boolean` (additive, mirrors `denied?`). - - `execBash` (`:185`) — set a `killedByTimer` flag **only inside** the `setTimeout` callback (`:204`), and **clear the timer the instant the subprocess settles** (a `finally`), so a command that exits on its own — even one whose non-zero exit races the deadline — never trips the flag. On the catch path, stamp `timedOut: true` only when the flag is set. Deterministic — don't rely on execa's `.timedOut`/`.signal`, since our own group-kill, not execa's timeout, is what fires first; the flag, owned solely by the fired timer, is the single source of truth for "killed on timeout". - - `bashTool.execute` (`:241`) — propagate `timedOut` onto the returned `BashOutput`. - - `renderBashSection` (`:279`) — when `timedOut`, append a `` line mirroring OpenCode's wording, naming the effective timeout + the 600 000 ms ceiling (`MAX_BASH_TIMEOUT_MS`, `:96`) + a note that cwd tracking is paused for this call. - - `multiBashTool` (`:304`) — same propagation; a timed-out command already stops the sequence (non-zero exit), so `failedAt` + the notice explain the stop. - -## Steps -1. Thread the effective `timeout` (post-`Math.min(..., MAX_BASH_TIMEOUT_MS)`, `:255`) into `execBash` (currently passed as `timeout` arg — reuse) so the notice can quote the real value the model must exceed. -2. `execBash`: `let killedByTimer = false;` set it inside the existing timer callback (`:205`) right before `process.kill(-pid, 'SIGKILL')`, and `clearTimeout(timer)` in a `finally` once the awaited subprocess settles. Ownership is thus explicit at the exit boundary: a process that completes before the timer fires clears it and is never marked, while one the timer actually killed is. In `catch`, return `{ ...result, timedOut: killedByTimer }` (only when true, to keep clean-exit output byte-identical). -3. Notice text (single source, shared by both tools): `command exceeded the ms timeout and was terminated. If it needs longer and is not waiting for interactive input, retry with a larger timeoutMs (ceiling 600000). cwd tracking is paused for this call.` Append via `renderBashSection` only when `timedOut` — so `toModelOutput` (`:272`) carries it into context. -4. Do **not** change `denied` (exit 126) handling or the spill/`capStream` path — timeout is a separate axis; a command can be both truncated and timed-out and both notices should render. - -## Tests (`bash-tool.test.ts`) -- `sleep 5` with `timeoutMs: 100` → `exitCode !== 0`, `timedOut === true`, `renderBashSection` output contains the `100 ms` + `600000` + retry hint. -- Normal `false` (exit 1) → `timedOut` unset, no timeout notice. -- Boundary case (through the `exec` seam): a command that exits non-zero right around the deadline — the timer cleared on settle — is **not** marked `timedOut` and carries no notice; only a command the timer actually killed is. -- `multiBash` with a slow first command + `timeoutMs` small → sequence stops, `failedAt === 0`, the timed-out result carries the notice. -- cwd regression: a timed-out `cd /tmp && sleep 5` leaves the tracked cwd unchanged (epilogue didn't run) — assert the next call still runs from the prior cwd, and the notice warned about it. -- Use the `exec` test seam (`BashToolInit.exec`, `:62`) or a real `bash` gated behind an env check — keep portable (no `Bun.*`). -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- A command killed at its timeout returns `timedOut: true` and a model-visible notice naming the ceiling + retry hint; a normal non-zero exit does not. -- No change to clean-exit output bytes, `denied` handling, or cwd-persistence behavior. diff --git a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/03-editor-toolset-scoping.md b/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/03-editor-toolset-scoping.md deleted file mode 100644 index 9f737e6e..00000000 --- a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/03-editor-toolset-scoping.md +++ /dev/null @@ -1,41 +0,0 @@ -# 03 — Declarative editor toolset + transitive depth guard - -> Part of [`overview.md`](overview.md). Depends on: none. **Lowest leverage — hardening, not a feature.** Behavior byte-identical today; it makes an invariant explicit rather than incidental. - -## The mechanism - -**OpenCode** (`sst/opencode` `packages/opencode/src/tool/task.ts`, `src/agent/subagent-permissions.ts`): -- When the `task` tool spawns a subagent it derives the child's tool permissions from the parent, then adds **explicit denies** (`task.ts:143`): the child cannot call `todowrite` or `task` itself (no recursion) unless the agent def grants them, and every `experimental.primary_tools` entry is denied to the child. So "what can a delegated child do" is a computed allow/deny set, not a hand-maintained list. -- Depth is bounded structurally: `task` walks the `parentID` chain and refuses past `cfg.subagent_depth ?? 1` (`task.ts:104`) — no unbounded nesting even as agent graphs grow. - -**aitm today**: -- The editor leaf's toolset is produced by `editorToolSet` (`packages/aitm/src/subagents/worker.ts:574`) — a **destructure denylist**: it strips `explore`, `memory`, `bashOutput`, `killBash` by name and spreads the rest. Fragile: a runtime tool the adapter mounts *later* (e.g. a future MCP-sourced tool, or a new liveliness tool) is **not** stripped, so a leaf silently inherits a capability it should never have (nest surveys, manage background procs). It's exactly the implicit-denylist anti-pattern OpenCode avoids. -- aitm's generic-dispatch seam already does it right elsewhere: `makeAgentTool` (`packages/ai-claude-compat/src/agent-spawn.ts:76`) enforces an explicit `allowedTools` allowlist at **construction** and throws on an out-of-list tool or self-recursion (`:79`); `explore` pins `EXPLORE_ALLOWED_TOOLS` (`subagents/explore.ts:22`). Only the editor fanout skipped the pattern. -- Depth: `makeAgentTool` forbids *direct* self-recursion (`:79`) but nothing enforces a *transitive* bound (A→B→A). Harmless today (the Orchestrator→Worker→editor graph is fixed and acyclic), but the guard should be explicit before any generic delegate tool is added. - -## Files to change -- `packages/aitm/src/subagents/worker.ts:574` — replace `editorToolSet`'s destructure with an allowlist filter over an exported `EDITOR_TOOL_ALLOWLIST`. -- New (or beside `worker.ts`): `EDITOR_TOOL_ALLOWLIST` — the leaf's legitimate keys: `readFile`, `writeFile`, `editFile`, `multiEdit`, `grep`, `glob`, `bash`, `multiBash`, `webFetch`, `webSearch`, `datetime` (the `WorkerTools` surface, `worker.ts:74`, minus the manifest/CI-fix-only extras). -- `packages/ai-claude-compat/src/agent-spawn.ts` — add an optional `maxDepth` to `AgentToolOptions` (default `maxDepth = 1`, matching OpenCode's `subagent_depth` default) and refuse to spawn past it. Depth rides the AI SDK's `experimental_context` (a Symbol key that can't collide with a caller's own context and survives object spread), so a spawned child sees how many agent frames are above it with no change to the tool input schema or caller wiring. `maxDepth = 1` is a single level of delegation: it matches aitm's **actual** behavior today (no survey toolset carries an agent tool, so nesting never exceeds one level) — it is not a literal no-op for a hypothetical pre-existing multi-level nesting, of which there are none. A non-finite or ≤ 0 value falls back to the default, so the guard can never be disabled. - -> **Scope split:** the `editorToolSet` allowlist above is **deferred** — its region in `worker.ts` is under active concurrent change, and reworking it would rework unrelated in-flight edits. This slice ships only the additive depth guard (a clean, self-contained `agent-spawn.ts` change); the allowlist remains tracked on the issue for the owning stream. - -## Steps -1. **Allowlist filter** (`worker.ts`): `export const EDITOR_TOOL_ALLOWLIST = [...] as const;` then rewrite `editorToolSet(tools)` to return `Object.fromEntries(Object.entries(tools).filter(([k]) => (EDITOR_TOOL_ALLOWLIST as readonly string[]).includes(k)))` typed back to `WorkerTools`. Result is byte-identical for today's tool set (same keys survive), but any *new* key is excluded by default — the safe direction. Keep the doc-comment explaining WHY each stripped tool (`explore`/`memory`/`bashOutput`/`killBash`) is leaf-inappropriate. -2. **Depth guard** (`agent-spawn.ts`): read the incoming depth from `execute`'s `experimental_context` (default 0). If `depth >= maxDepth`, **return** a refusal line — not throw — mirroring the existing caught-provider-error path, so a capped delegation degrades to a message instead of aborting the parent step, and the refused `generateText` is never paid for. Otherwise spawn the child with `experimental_context` carrying `depth + 1`, so any agent-tool the child invokes keeps counting down the chain. The boundary is inclusive: `depth === maxDepth` rejects the child itself. A **run-time** guard — not the construction-time throw first sketched — because it also catches an indirect A→B→A cycle, where the offending tool is a different handle the static self-recursion check (`:79`) can't see. Since aitm mounts `explore` with a read-only trio that contains no agent-tool, this is a no-op today — it just makes "surveys can't nest" a tested invariant instead of an accident of wiring. -3. Do **not** add a new model-facing delegate tool, and do **not** parallelize PR groups — see Rejected below. - -## Tests (`worker.test.ts` / `agent-spawn.test.ts`) -- `editorToolSet`: given `WorkerTools` + an extra `mcpFoo` tool, the result excludes `mcpFoo` and `explore`/`memory`/`bashOutput`/`killBash`, and includes every `EDITOR_TOOL_ALLOWLIST` key present. -- Byte-identical regression: for exactly today's tool set, the returned keys equal the pre-change destructure output. -- `makeAgentTool` depth (through the real spawn chain — a child that invokes a nested agent-tool): at the default cap the nested delegate one level down is refused before it spawns (its model never runs) and the refusal line rides back to the child; a raised `maxDepth` lets it descend one level further; an invalid `maxDepth` falls back to the default (guard cannot be disabled); a spawned child preserves any caller `experimental_context` alongside the depth. -- Gates: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. - -## Done when -- The editor leaf toolset is derived from an explicit allowlist; a newly-mounted runtime tool is excluded by default (proven by test), and today's behavior is unchanged. *(Deferred — see the scope-split note above; tracked on the issue.)* -- Nested survey delegation at or past `maxDepth` is refused at run time (returns a refusal line; the parent step continues), and a non-finite/≤ 0 `maxDepth` cannot disable the guard. - -## Rejected (why not, so the executor doesn't reopen) -- **Model-driven generic `task` dispatch** (OpenCode's central pattern): aitm's dispatch is a deliberate fixed role pipeline (Orchestrator→Planner/Worker/Reviewer as tools, `orchestrator/subagent-tools.ts:105`) + a bounded editor pool. A generic write-capable delegate duplicates the fanout and adds coordination/recursion burden for no clear win. `explore` already covers read-only delegation. -- **Parallel independent PR groups** (the Planner returns a DAG, `subagent-tools.ts:108`): blocked by CLAUDE.md — single shared checkout, no worktrees. Concurrent groups would collide on the working tree (`git checkout -B` switches the whole tree). Out of scope until/unless the no-worktree rule changes. -- **Background subagents** (OpenCode `task.ts:216`): aitm is unattended (no human to notify/continue); the value of "launch and keep working" is low, and `SubagentHandle` continuation (`subagent.ts:874`) already covers resume for the CI-fix path. diff --git a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/overview.md b/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/overview.md deleted file mode 100644 index 7ac4d563..00000000 --- a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/overview.md +++ /dev/null @@ -1,38 +0,0 @@ -# OpenCode-inspired agent tooling for aitm - -## Goal -Steal three concrete mechanics from OpenCode (`sst/opencode`) and a contrast tool (Aider, `Aider-AI/aider`) to harden aitm's **file edits**, **bash**, and **subagent dispatch** — additive/surgical, no rewrite, matching CLAUDE.md. Each slice is one buildable module change with a verify command. - -## Why these three (and not the rest) -Research read the real source of both tools. Most OpenCode ideas aitm *already has or has planned*: -- aitm already: two-phase Worker (manifest `submit` + bounded editor pool, `worker.ts:729`), `runPool` concurrency cap (`pool.ts`), read-before-edit + hash-staleness (`edit-tools.ts:96`, `fs-tools.ts:85`), cwd-persistent bash via epilogue (`bash-tool.ts:106`), deny/allow command rules (`command-rules.ts`), a read-only generic-dispatch seam (`explore` / `makeAgentTool`, `agent-spawn.ts`). -- Already claimed by **plan `2026/07/18/102-aitm-liveliness-tools-team-caching`**: oversized-output spill (`02`), background bash (`02`), streaming (`07`), editor-team fanout (`05`). **Do not re-propose these** — the slices below are orthogonal to plan 102 and complement it. - -The three genuine, non-overlapping gaps, highest-leverage first: - -| # | Mechanism | OpenCode does | aitm today | This plan adds | -| --- | --- | --- | --- | --- | -| 01 | **File edit** | 9-strategy fuzzy-replace cascade w/ disproportion guard (`edit.ts:682`) | exact `split/join` only — any near-miss throws `oldString not found` (`edit-tools.ts:124`) | fuzzy **fallback** ladder after exact fails | -| 02 | **Bash** | timeout → `` "retry with a larger timeout" (`shell.ts:562`) | timeout SIGKILLs, model gets a bare `ExecaError` — can't tell timeout from failure (`bash-tool.ts:204`) | typed `timedOut` + actionable notice | -| 03 | **Subagent dispatch** | child toolset derived by allowlist + explicit denies + no-recursion (`task.ts:143`, `subagent-permissions.ts`) | editor leaf toolset stripped by hardcoded destructure denylist (`worker.ts:574`) | declarative allowlist + transitive depth guard | - -## Context -- Stack (CLAUDE.md): Bun dev; must run unchanged on Node ≥20 / Deno ≥1.40 (no `Bun.*` in shipped code); ESM only; strict TS, no `any`, named exports, kebab-case files; `ai` package `ToolLoopAgent` + subagents-as-tools; OpenRouter only; every module ships a paired `*.test.ts`; tests pass under `bun test` AND `node --test`. No worktrees — single shared checkout. Out of scope (hard): MCP-server, webhooks, Docker. -- Both engines live in **`packages/ai-claude-compat/src`** (the Claude-Code-style tool surface) — slices 01 & 02 change compat; slice 03 changes compat + `packages/aitm/src/subagents/worker.ts`. -- OpenCode reference (read-only, cite only): `sst/opencode` `packages/opencode/src/tool/{edit,shell,task}.ts`, `src/agent/subagent-permissions.ts`. Aider contrast: `Aider-AI/aider` (whole-file / unified-diff edit formats — see slice 01 §Contrast). -- The failure surface these attack is aitm's own: `EMPTY_MANIFEST_REASON` (`worker.ts:242`), `editorNoChangeReason` / phantom-edit blocks (`worker.ts:426`), `appliedPhantomReason` (`worker.ts:439`) — a leaf that *narrates* an edit or emits a near-miss `oldString` fails the whole PR group and is misdiagnosed as "model too weak". - -## Plan files (execute in order; all independent) -1. [`01-fuzzy-edit-fallback.md`](01-fuzzy-edit-fallback.md) — **highest leverage.** Port OpenCode's replacer cascade as an exact-first *fallback* in `applyEdit`; keep aitm's staleness/uniqueness contracts. -2. [`02-bash-timeout-notice.md`](02-bash-timeout-notice.md) — surface a killed-on-timeout command as a typed, actionable result instead of a bare error. -3. [`03-editor-toolset-scoping.md`](03-editor-toolset-scoping.md) — replace the ad-hoc editor tool-strip with an allowlist; add a transitive subagent-depth guard. - -## Done when -- A leaf whose `oldString` differs only by leading whitespace/indentation now lands the edit (was: whole-group `blocked`), guarded so a wildly-oversized fuzzy match still refuses. -- A bash command killed at its timeout returns `timedOut: true` and a notice naming the ceiling + retry hint; a normal non-zero exit does not. -- The editor leaf toolset is derived from an explicit allowlist (a newly-mounted runtime tool is excluded by default, not by remembering to destructure it); behavior byte-identical for today's tool set. -- All gates green on both runtimes: `bun test`, `bun run test:node`, `bun run typecheck`, `bun run lint`. Every touched module keeps its paired `*.test.ts`. - -## Risks / open questions -- Slice 01 is the only behavior-widening change: fuzzy matching can mis-target. Mitigations are load-bearing — exact match always wins, fuzzy runs only on 0 exact hits, every fuzzy hit re-checks uniqueness + `isDisproportionateMatch`, and the existing numbered-snippet self-verify already rides the result. Ship the exact-match path byte-identical; only the *throw* branch gains fallbacks. -- Relationship to plan 102: no file overlap — 01/02 touch `edit-tools.ts` / `bash-tool.ts` logic that 102 does not; 03 touches `worker.ts:574` (`editorToolSet`), which 102 §05 leaves alone. If 102's spill store lands first, slice 02's notice composes with it (spill handles *size*, this handles *termination cause*). diff --git a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/status.yml b/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/status.yml deleted file mode 100644 index 105a6cd0..00000000 --- a/docs/plans/2026/07/23/101-opencode-inspired-agent-tooling/status.yml +++ /dev/null @@ -1,32 +0,0 @@ -plan: 101-opencode-inspired-agent-tooling -title: "OpenCode-inspired agent tooling for aitm" -status: in_progress # not_started | in_progress | blocked | complete | superseded -created_by: plan-author -worked_by: "" -owner: plan-owner -percent: 33 # 0–100, overall completion -current_focus: "02" # next slice to pick up after 01 lands -slices: - - file: 01-fuzzy-edit-fallback.md - status: in_review # implemented; PR #271 open, awaiting CodeRabbit - percent: 90 - issue: 268 - pr: 271 - - file: 02-bash-timeout-notice.md - status: not_started - percent: 0 - issue: 269 - - file: 03-editor-toolset-scoping.md - status: not_started - percent: 0 - issue: 270 -evidence: - - "PR #271 — slice 01 fuzzy-edit fallback (edit-replacers.ts + applyEdit); green Bun+Node, 2077 pass" -notes: > - Research plan from studying sst/opencode + Aider (Aider-AI/aider) - vs aitm. Three non-overlapping OpenCode-inspired mechanics: 01 fuzzy edit fallback (edit-tools.ts, - highest leverage — attacks the phantom-edit/empty-manifest failure surface), 02 bash timeout notice - (bash-tool.ts), 03 declarative editor toolset + depth guard (worker.ts / agent-spawn.ts). Orthogonal - to plan 2026/07/18/102-aitm-liveliness-tools-team-caching (spill/background-bash/streaming/editor-fanout) — no file overlap. - All slices additive/surgical, CLAUDE.md-compliant, tested on Bun + Node. -last_updated: 2026-07-23 # slice 01 implemented, issues 268-270 filed diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 00000000..68c09d26 --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,26 @@ +# Plans + +Execution plans written by `/planx` (`.claude/commands/planx.md`) for another AI to implement. Plan +only, no code. + +The tree currently holds no plan documents. The earlier internal plans (bug hunts, audit +remediation, improvement plans and their trackers) were removed from the public tree under #384, +because they were the team's working documents rather than user documentation. Git history is +untouched. Where a source comment still mentions a slice or a numbered step from one of them, the +comment itself carries the reasoning that matters. + +## Layout + +``` +docs/plans///
/<1NN>-/ +├── overview.md # the map: goal, context, slices in order, done-when, risks +├── 01-.md # one separable slice +├── 02-.md +└── status.yml # live tracker: status / percent / current_focus / slices +``` + +- `<1NN>` is a per-day counter starting at `101`. The slug is kebab-case, five words at most. +- Slices are separable so they can be built in parallel. Never a single `plan.md`. +- `status.yml` is the only tracker; the `.md` slices stay reference maps. +- Tracker fields name roles, never people, and no file carries a home directory or a machine's + workspace layout. This tree is public. diff --git a/packages/aitm/src/domain/pr-group.ts b/packages/aitm/src/domain/pr-group.ts index 2e4a769c..bb62f2c4 100644 --- a/packages/aitm/src/domain/pr-group.ts +++ b/packages/aitm/src/domain/pr-group.ts @@ -16,7 +16,7 @@ export type PrGroupStatus = z.infer; // Per-group persisted position in the PR lifecycle so a crashed/paused run resumes mid-PR // without redoing prior stages. Per-group (not global) because aitm runs groups concurrently. -// Drives WorkLoop.runGroup's stage dispatcher (slice 03). See docs/plans .../03-pr-lifecycle-stages.md. +// Drives WorkLoop.runGroup's stage dispatcher. export const GroupStageSchema = z.enum([ 'pending', 'working', diff --git a/packages/aitm/src/loop/mutex.ts b/packages/aitm/src/loop/mutex.ts index 202b3b91..0c70a02a 100644 --- a/packages/aitm/src/loop/mutex.ts +++ b/packages/aitm/src/loop/mutex.ts @@ -7,7 +7,7 @@ // concurrently-ready groups (PlanGraph.ready() can return several): the single in-place checkout // holds one branch at a time, so the git-mutating section must run for one group at a time even when // the driver dispatches a batch. Non-git phases (CI waits, PR polling) stay outside the lock and -// still overlap. See src/loop/work-loop.ts and docs/plans/.../02-parallel-team-shared-checkout.md. +// still overlap. See src/loop/work-loop.ts. export class Mutex { // Tail of the serialization chain. Each runExclusive appends its body after the current tail; the diff --git a/packages/aitm/src/loop/work-loop.ts b/packages/aitm/src/loop/work-loop.ts index 212b2a89..d89520ea 100644 --- a/packages/aitm/src/loop/work-loop.ts +++ b/packages/aitm/src/loop/work-loop.ts @@ -221,7 +221,7 @@ export type WorkLoopDeps = { // run-loop-adapter.ts). Checked at each loop iteration boundary so a cancelled run reports // `{ kind: 'cancelled' }` (exit 2) instead of surfacing whatever abort-induced group failure // `runGroup`'s catch produced as `blocked` (exit 1). Optional — omitted → no cancellation check, - // byte-identical to pre-signal behavior. See docs/plans/.../02-signal-cancellation-cleanup.md. + // byte-identical to pre-signal behavior. signal?: AbortSignal; // Run-level cost/token budget check (issue #190). Consulted at each group-batch boundary BEFORE new // work is dispatched (never mid-commit); an exceeded result stops the run and blocks with the @@ -383,7 +383,7 @@ export class WorkLoop { // Driver-owned checkout lock: the shared single in-place checkout holds one branch at a time, so // the git-mutating checkout→edit→commit critical section (runOneTask) must run for one group at a // time even when run() dispatches a batch of ready() groups. Non-git phases (CI waits, PR polling) - // stay outside it and still overlap. A no-op at concurrency 1. See docs/plans/.../02-*.md (DECISION 1). + // stay outside it and still overlap. A no-op at concurrency 1. private readonly checkoutMutex = new Mutex(); // Group start times for the `group … merged in Ns` total (claudetm parity), keyed by group id — // set once at runGroup entry, read wherever a group reaches its merged terminal (driveStages' diff --git a/packages/aitm/src/workspace/task-commit-marker.ts b/packages/aitm/src/workspace/task-commit-marker.ts index d4207f1d..6c38db44 100644 --- a/packages/aitm/src/workspace/task-commit-marker.ts +++ b/packages/aitm/src/workspace/task-commit-marker.ts @@ -1,4 +1,4 @@ -// docs/plans/2026/07/18/101-parallel-agent-bug-hunt/03-review-loop-idempotency.md — duplicate +// Guards against a duplicate // task-commit on resume (durability #7). A crash between the Worker's commit landing // (orchestrator.ts finalizeCommit) and WorkLoop persisting the task as done leaves the branch with // the commit but state.json still showing the task undone; a naive resume re-runs the Worker and diff --git a/packages/aitm/test/integration/ci-fix-loop.test.ts b/packages/aitm/test/integration/ci-fix-loop.test.ts index 6eb44d26..2c2037e3 100644 --- a/packages/aitm/test/integration/ci-fix-loop.test.ts +++ b/packages/aitm/test/integration/ci-fix-loop.test.ts @@ -25,7 +25,7 @@ // Test 5 — WorkLoop/autoMerge, real remote: fix lands on origin before the PR merges: // Real bare `origin` remote. runCiFix pushes a real commit to it; mergePr's stub captures the // remote branch's HEAD sha at the moment it fires. Asserts that sha already equals the local -// fix commit — the push happened before, not after, the merge (docs/plans/.../03-*.md). +// fix commit — the push happened before, not after, the merge. // // Test 6 — WorkLoop/autoMerge: unfixable PR never merges red, stays blocked across a resumed WorkLoop: // waitForChecks always fails; runCiFix always lands a (real, useless) commit. With diff --git a/packages/aitm/test/integration/concurrent-groups.test.ts b/packages/aitm/test/integration/concurrent-groups.test.ts index 94f69223..688e61db 100644 --- a/packages/aitm/test/integration/concurrent-groups.test.ts +++ b/packages/aitm/test/integration/concurrent-groups.test.ts @@ -1,7 +1,6 @@ // End-to-end: two independently-ready PR groups driven through one WorkLoop.run() against the -// single shared in-place checkout (worktrees removed — audit 02, DECISION 1). Exercises the three -// concurrency-safety guarantees from docs/plans/2026/07/17/101-aitm-audit-remediation/ -// 02-parallel-team-shared-checkout.md: +// single shared in-place checkout (worktrees removed). Exercises the three +// concurrency-safety guarantees of that shared checkout: // // 1. Branch-before-editor-fanout + the driver's checkout mutex: each group's commits land only // on its own branch — group B's branch never carries group A's files. diff --git a/packages/aitm/test/integration/crash-durability.test.ts b/packages/aitm/test/integration/crash-durability.test.ts index 2f5a9f56..d9c6b079 100644 --- a/packages/aitm/test/integration/crash-durability.test.ts +++ b/packages/aitm/test/integration/crash-durability.test.ts @@ -10,7 +10,7 @@ // instance afterward — the same thing a resumed process does — and asserts it reads the last // completed write, never a partial one. // -// docs/plans/2026/07/17/101-aitm-audit-remediation/07-tests.md success criterion 4: "mid-write +// Success criterion: "mid-write // crash loses no completed rename, leaves no orphan temp; corrupt transcript line skips+warns". import assert from 'node:assert/strict'; @@ -317,7 +317,7 @@ test('crash-durability: state write and transcript append crash together; resume // PR-lifecycle crash boundary: kill between the PR-open side effect and the stage persist // --------------------------------------------------------------------------- // -// docs/plans/2026/07/18/101-parallel-agent-bug-hunt/01-pr-lifecycle-idempotency.md — the crash this +// The crash this // models is a `kill -9` that lands after `gh pr create` (an external side effect on GitHub, which // survives the crash) but before WorkLoop persists the PR number to state.json. Before the fix // (github-client.ts createPr / stage-handlers.ts handlePrOpen), a resume in this window called @@ -533,7 +533,7 @@ test('crash-durability: kill between the PR-open side effect and the stage persi // Task-commit crash boundary: kill after the Worker's commit lands, before completeTask persists // --------------------------------------------------------------------------- // -// docs/plans/2026/07/18/101-parallel-agent-bug-hunt/03-review-loop-idempotency.md, durability #7. +// Durability #7. // The crash this models is a `kill -9` that lands after WorkLoop.runOneTask's finalizeCommit (a // real `git commit --amend`, on GitHub-independent local disk state that survives the crash) but // before completeTask persists the task as done in state.json. Before the fix, a resume in this @@ -771,7 +771,7 @@ test('crash-durability: kill after a task commit lands but before completeTask p // persists // --------------------------------------------------------------------------- // -// docs/plans/2026/07/18/101-parallel-agent-bug-hunt/03-review-loop-idempotency.md, durability #5. +// Durability #5. // The crash this models is a `kill -9` that lands after the Reviewer's reply is posted (an external // side effect on GitHub, which survives the crash, exactly like `gh pr create` in the PR-open // boundary above) but before handleAddressingReviews's own PrContextStore.recordAddressedThreads @@ -938,7 +938,7 @@ test('crash-durability: prPerTask + no-automerge is rejected before any side eff // Dirty-tree crash boundary: a run must never destroy work it did not create // --------------------------------------------------------------------------- // -// docs/plans/2026/07/23/101-aitm-audit-improvements/01-data-safety-state.md step 1. Before the +// Data safety, step 1. Before the // fix, the FIRST checkout acquire of a run silently ran `git reset --hard` + `git clean -fd` over // whatever sat in the tree — indistinguishable, from aitm's point of view, from a crashed prior // run's own leftovers. An operator mid-edit (or dirt a dead run left that the operator had since @@ -1039,7 +1039,7 @@ test('crash-durability: a dirty tree at run entry is refused untouched; committi // Concurrent-run crash boundary: a second invocation while the lock is held must cost nothing // --------------------------------------------------------------------------- // -// docs/plans/2026/07/23/101-aitm-audit-improvements/01-data-safety-state.md step 2. StateStore +// Data safety, step 2. StateStore // mutates from a write-behind cache of the last state IT wrote, so two overlapping `aitm` // invocations over one `.ai-task-master/` do not merely interleave — they last-writer-wins over // each other's plan, group stages and PR numbers. The fix (state/run-lock.ts) makes the SECOND @@ -1142,7 +1142,7 @@ test('crash-durability: a concurrent run while the lock is held is refused untou // `--no-resume` crash boundary: a mid-plan run must survive a crash in the take-over write itself // --------------------------------------------------------------------------- // -// docs/plans/2026/07/23/101-aitm-audit-improvements/01-data-safety-state.md step 4. Before the +// Data safety, step 4. Before the // fix, `merge-pr --no-resume` re-initialised state wholesale, discarding a mid-plan run's plan, // group stages, session count and runId for one distrusted field (`currentPr`). The fix // (cli/commands.ts) re-points `currentPr` in place via `StateStore.update` instead. This test diff --git a/packages/aitm/test/integration/public-tree.test.ts b/packages/aitm/test/integration/public-tree.test.ts index af08fc0b..33d163f2 100644 --- a/packages/aitm/test/integration/public-tree.test.ts +++ b/packages/aitm/test/integration/public-tree.test.ts @@ -320,14 +320,19 @@ describe('the public tree', () => { assert.ok(tracked.includes(SELF), 'the scan does not see this file'); const offenders: string[] = []; let checked = 0; - for (const path of tracked.filter((p) => PLAN_TRACKER.test(p))) { + const trackers = tracked.filter((p) => PLAN_TRACKER.test(p)); + for (const path of trackers) { const file = readText(root, path); if (!file.read || file.text === null) continue; checked += 1; const wrong = trackerPeople(file.text); if (wrong.length > 0) offenders.push(`${path} (${wrong.join(', ')})`); } - assert.ok(checked > 0, 'the tracker rule checked no plan tracker'); + // Every tracker git lists must be read and checked. The tree may hold none (the plans were + // removed under #384), so the bound is "all of them", not "at least one". The test below pins + // the pattern to the layout docs/plans/README.md documents, so a drifted pattern cannot turn + // this into a scan of nothing. + assert.equal(checked, trackers.length, 'the tracker rule could not read every plan tracker'); assert.deepEqual( offenders, [], @@ -459,4 +464,16 @@ describe('the guard itself', () => { assert.deepEqual(trackerPeople(roles.replace('""', '"someone"')), ['worked_by']); assert.deepEqual(trackerPeople('worked_by: ""\nowner: plan-owner\n'), ['created_by']); }); + + it('matches the tracker path the plan layout writes, and nothing else', () => { + assert.equal(PLAN_TRACKER.test('docs/plans/2026/11/14/101-some-plan/status.yml'), true); + assert.equal(PLAN_TRACKER.test('docs/plans/2026/11/14/101-some-plan/overview.md'), false); + assert.equal(PLAN_TRACKER.test('packages/aitm/docs/plans/x/status.yml'), false); + const layout = readFileSync( + new URL('../../../../docs/plans/README.md', import.meta.url), + 'utf8', + ); + assert.match(layout, /docs\/plans\/\/\/
\/<1NN>-\//); + assert.match(layout, /status\.yml/); + }); }); diff --git a/packages/aitm/test/integration/sigint-cancellation.test.ts b/packages/aitm/test/integration/sigint-cancellation.test.ts index 569f122b..e72c00d9 100644 --- a/packages/aitm/test/integration/sigint-cancellation.test.ts +++ b/packages/aitm/test/integration/sigint-cancellation.test.ts @@ -1,7 +1,6 @@ // Integration: a SIGINT mid-`aitm start` must (a) reap the MCP server it spawned — a REAL child // process, not an in-memory stub, so a leaked handle would show up as an actual leftover PID — and // (b) surface `{ kind: 'cancelled' }` (exit code 2) instead of silently completing or blocking. -// docs/plans/2026/07/18/101-parallel-agent-bug-hunt/02-signal-cancellation-cleanup.md. // // Fidelity boundary (matches every other file in this suite, e.g. start-flow.test.ts): the LLM // boundary is stubbed (style digest, Planner, Worker — no real model call, no real git checkout).