Skip to content
Canonical

External repo survey — kunchenguid tooling family (ID-92 research input)

External repo survey — kunchenguid tooling family

Section titled “External repo survey — kunchenguid tooling family”
  • Task: ID-92 — Workflow efficiency hardening
  • Subtask: {92.1} RESEARCH (supporting input, satisfies C2 external-source requirement self-referentially)
  • Authored: 07/06/2026 — three parallel survey agents, repos cloned shallow + read at mechanism level
  • Source account: https://github.com/kunchenguid — repos: axi, gh-axi, chrome-devtools-axi, lavish-axi, treehouse, no-mistakes, gsh, acp-mock, acpx
  • Provenance caveat: kunchenguid/acpx is a stale personal fork (2026-05-01) of openclaw/acpx (live upstream: 2,830 stars, pushed 2026-06-05). kunchenguid is an openclaw/acpx contributor; acp-mock is an original companion repo. acpx analysis below is from the fork snapshot, representative of upstream architecture.

Theme key (from 92.1 details digest): A1 unbounded tool outputs · A2 orchestrator-as-workhorse · A3 recurring-issue thrash · B1 subtask-not-backlog · B2 sandbox/allowlist carryover · B3 roadmap context at session start · B4 fresh-context transcript retro review · B5 structured docket prompts · C1 spec-chain right-sizing · C2 external-source research.

Survey 1 — AXI family (axi, gh-axi, chrome-devtools-axi, lavish-axi)

Section titled “Survey 1 — AXI family (axi, gh-axi, chrome-devtools-axi, lavish-axi)”

axi

Section titled “axi”
  • What it is: The family’s meta-repo — “Agent eXperience Interface”: 10 design principles for agent-native CLI tools that treat token budget as a first-class constraint, plus two benchmark harnesses (490 browser runs, 425 GitHub runs) proving the approach against MCP, and a shared SDK.
  • Architecture/mechanism:
    • .agents/skills/axi/SKILL.md — the canonical 10-principle spec: TOON output (~40% token savings vs JSON), minimal default schemas (3-4 fields + --fields escape), truncation-with-receipt (--full escape hatch + total-size hint), pre-computed aggregates, definitive empty states, structured errors on stdout + idempotent mutations, SessionStart ambient context, content-first no-args home view, contextual next-step suggestions, per-subcommand help.
    • packages/axi-sdk-js/ (866 LOC): runAxiCli framework (cli.ts), TOON rendering (output.ts), AxiError + exit-code mapping (errors.ts), and hooks.ts (577 LOC) — idempotent, marker-based SessionStart hook install/repair across Claude Code (~/.claude/settings.json), Codex (hooks.json + config.toml feature flag), and OpenCode (managed plugin), with executable-path repair after reinstall and a dev-entrypoint guard.
    • bench-github/ + bench-browser/: condition-matrix harness — conditions in config/conditions.yaml (each condition = a different CLAUDE.md/AGENTS.md injected into a fresh workspace), tasks in config/tasks.yaml with per-task grading_hint, agent invoked with stream-json capture, JSONL usage parsing (src/usage.ts), LLM judge (src/grader.ts), results to JSONL + report.
    • Headline result (bench-github/published-results/STUDY.md): AXI 100% success @ $0.050/task vs GitHub MCP 82-87% @ $0.147-0.148; MCP schemas consume 137-176K input tokens vs 46-47K for CLI. Key causal finding: “each extra turn re-sends the entire growing context, so the savings from a smaller initial context are consumed by accumulation across additional turns” — lazy tool loading (ToolSearch) was a net negative (2-turn discovery overhead + new failure mode: can’t find the tool; 22-turn spirals on merged_pr_ci_audit).
  • Workflow ideas worth stealing:
    • Truncation-with-receipt contract: never omit, never dump — preview + (truncated, N chars total) + exact escape-hatch command. Directly applicable as a wrapper discipline for our Bash diff/search outputs.
    • Pre-computed aggregates: include count: 30 of 847 total and derived summaries (“3/3 passed”) so the agent never paginates or re-counts.
    • Definitive empty states (“0 closed tasks found”) to stop verify-by-rerun loops.
    • The benchmark harness itself: conditions-as-CLAUDE.md-variants × tasks × repeats × LLM judge × JSONL token accounting is a directly reusable template for measuring our own workflow interventions (e.g., A/B-ing a size-guard hook) instead of adopting on intuition.
    • The turn-count-dominates-cost finding as quantitative backing for batching/fewer-roundtrips design.
  • Theme mapping: truncation-with-receipt → A1; aggregates + definitive empties → A1+A3 (kills follow-up-call and verify-rerun thrash); turn-cost finding → A2 (quantifies why orchestrator inline loops with growing context are the most expensive shape); bench harness → novel — outside themes (an evaluation instrument for ID-92-style efficiency work, complementary to the evaluate-workflow lane); ToolSearch-is-net-negative finding → novel (directly relevant to our deferred-tool/MCP loadout decisions).
  • Maturity/caveats: 822 stars, 28 forks, created 2026-03-21, pushed 2026-06-05, active. Benchmarks are self-published by the author (single repo target, Sonnet 4.6 only), but methodology and raw trajectories are committed.

gh-axi

Section titled “gh-axi”
  • What it is: AXI reference implementation — wraps the gh CLI with TOON output, minimal schemas, pre-computed CI summaries, structured error translation, and next-step suggestions. The benchmark’s winning condition (100% success, cheapest).
  • Architecture/mechanism:
    • Subprocess wrapper: src/gh.ts shells out to gh ... --json <minimal-keys>, projects through per-command FieldDef schemas (src/toon.ts), renders TOON.
    • src/body.ts — token-cost cleaning applied only when truncation is needed: GitHub URLs → PR#123/Issue#456 refs, image embeds → [image: alt], >80-char markdown URLs stripped, quoted-reply blocks collapsed to [quoted text removed], then truncate at 500 chars with --full hint.
    • src/commands/pr.ts:646-661 — check rollup pre-aggregated to “N passed, M failed, K skipped, T total” instead of returning rows; prDiff truncates at DIFF_TRUNCATE_LIMIT and emits truncated: true, original_length: N + a ready-to-run --full command; run.ts caps logs at 20,000 chars with the same receipt shape.
    • src/errors.ts — regex pattern table mapping raw gh stderr to structured codes (REPO_NOT_FOUND, RATE_LIMITED…) each with fix-suggestions (“Wait 60s”, “use gh api REST which has a separate budget”); raw stderr never leaks.
    • src/suggestions.ts (498 LOC) — declarative (domain, action, state, isEmpty) → next-step-command table; carries disambiguating flags (-R owner/repo) forward only when repo wasn’t inferable from git.
    • src/commands/home.ts — no-args dashboard: parallel fetch of top-3 issues + top-3 PRs for the cwd repo; this is also what the SessionStart hook prints.
    • .airlock/lint.sh — changed-files-only lint/format keyed off AIRLOCK_BASE_SHA/AIRLOCK_HEAD_SHA.
  • Workflow ideas worth stealing:
    • The body-cleaning pass (URL shortening, image/quote stripping) before truncation — cheap, lossless-for-decision-making compression of pasted GitHub content; applicable to anything we persist into context from gh pr view/issue bodies.
    • Diff/log truncation with original_length receipt — exactly the A1 --stat-first shape, done at the tool boundary so no agent discipline is required.
    • Error-translation table with embedded remediation commands — converts recurring-failure stderr into a one-shot fix path instead of a flag→diagnose→retry loop.
    • Idempotent mutations (close-already-closed → exit 0 no-op) — removes a whole class of error-handling turns.
  • Theme mapping: body cleaning + diff/log caps → A1 (filter-at-source, size guards); error table + idempotent no-ops → A3 (root-cause-at-source for recurring tool-failure thrash); home dashboard via SessionStart hook → B3 (session-start context read-in, machine-generated and directory-scoped); suggestion table → B5-adjacent (structured next-action prompts generated from state, the same idea as docket prompts but tool-emitted).
  • Maturity/caveats: 47 stars, last pushed 2026-05-23. Small (1,289 LOC core + 4,183 LOC commands), well-tested (per-module test mirror + help-examples.test.ts guard). Wraps gh, so requires it installed/authed.

chrome-devtools-axi

Section titled “chrome-devtools-axi”
  • What it is: Browser automation CLI wrapping chrome-devtools-mcp behind a persistent local HTTP bridge — won the browser benchmark (100% @ $0.074, 4.5 turns vs MCP’s 6-7.6).
  • Architecture/mechanism:
    • Three-layer: short-lived CLI → persistent bridge daemon (src/bridge.ts, HTTP on :9224, PID file in ~/.chrome-devtools-axi/) → chrome-devtools-mcp over stdio. Bridge keeps the MCP session + Chrome alive across CLI invocations; deep health check (/health?deep=1) does a real list_pages CDP round-trip to detect a dead browser behind a live MCP server, and recycles stale bridges.
    • Stale-ref protection (src/generation.ts + src/snapshot.ts): a snapshot-generation counter persisted to disk; every uid= ref in snapshot output is stamped g<N>:; action commands validate the stamp and fail loudly with STALE_REF when the page re-rendered, instead of silently acting on a stale tree.
    • Two truncation strategies (src/snapshot.ts): truncateSnapshot (16K, cut at line boundary) for accessibility trees; truncateText (8K, 40% head + 60% tail with (N chars omitted, T total) marker) for eval output where the tail matters.
    • run command (src/run.ts): reads a multi-step script from stdin, injects a page global (open/eval/wait/snapshot/click/fill/...), executes as a temp .mjs — N browser steps collapse into one tool call with only the script’s console.log returning to context.
    • src/suggestions.ts: parses snapshot refs and emits state-aware next steps (after fill → find the submit-looking button and suggest clicking it).
  • Workflow ideas worth stealing:
    • Generation-stamped handles + fail-loud staleness — a general pattern for any agent-held reference to mutable state (our review queues, ledger snapshots): make handles carry the version they were minted in and reject stale ones at the boundary rather than silently no-op’ing.
    • Head+tail truncation for command output — better than head-only for build/test logs where the failure is at the end; concrete shape for an A1 output guard.
    • The script-batching run mode — the “give the workhorse a composable primitive so a loop becomes one call” pattern; the same shape would apply to a gh-axi-style batch for our repetitive multi-call sequences.
    • Daemon lifecycle discipline: PID file + version handshake + deep health probe + stale recycle — reusable for our own long-lived helpers (dev server, bridge processes).
  • Theme mapping: head+tail/snapshot truncation → A1; run script batching → A2 (moves loop iterations out of conversation turns entirely — each avoided turn avoids a full context re-send); STALE_REF fail-loud → A3 (converts a silent-failure→confusion→thrash loop into an immediate, self-describing retry signal); state-aware suggestions → B5-adjacent.
  • Maturity/caveats: 83 stars, pushed 2026-05-23. 6,854 LOC, 16 test files including bridge/lifecycle tests. Single-author but complete.

lavish-axi

Section titled “lavish-axi”
  • What it is: Human-in-the-loop review surface for agent-generated HTML artifacts — agent writes HTML, CLI opens it in a local browser, human annotates elements/text-ranges/queues prompts, agent long-polls for the feedback. A local, CLI-native cousin of our Plannotator skills.
  • Architecture/mechanism:
    • CLI + detached express server (spawned on demand, version handshake — stale servers are shut down and browser chromes auto-reload onto the replacement; idle self-shutdown after 30 min or when the last session ends with nothing connected).
    • Sessions keyed by canonical (realpath’d) HTML file path — no opaque session IDs for the agent to track (src/session-store.js).
    • lavish-axi poll long-polls indefinitely (whitespace heartbeat bytes keep the HTTP response alive); --agent-reply posts the agent’s message into the browser chat before re-polling. SSE agent-presence states (waiting/listening/working) drive the browser UI so the human knows whether an agent is attached.
    • Protocol enforcement embedded in tool output: every poll/open response carries a next_step field with imperative instructions — “Do not respond to the user just yet. Now you must run lavish-axi poll <file> --agent-reply ...” plus explicit shell-timeout guidance (src/cli.js:157,216). The tool steers the agent through the loop; no skill memorization needed.
    • playbook <id> (src/playbooks.js): seven on-demand guidance docs (diagram/table/comparison/plan/diff/input/slides), each with choose/structure/design_rules/pitfalls — progressive disclosure of authoring guidance instead of one fat prompt.
    • Single-source skill generation: scripts/build-skill.js renders skills/lavish-axi/SKILL.md from the same createHomeOutput() that powers the no-args view and the SessionStart hook, with a --check mode wired into pnpm run check that fails CI on drift.
    • Contributor gate (CONTRIBUTING.md): human PRs to main must push through no-mistakes — a local git proxy that runs an AI review/test/lint pipeline in an isolated worktree, forwards the push only after checks pass, opens the PR, and writes a deterministic signature that a GitHub Action verifies.
  • Workflow ideas worth stealing:
    • next_step imperative fields in structured tool output — a concrete mechanism for keeping dispatched agents on-protocol mid-task (vs. hoping the brief was read). Directly applicable to our curator/executor dispatch surfaces: have the ledger/CLI tooling emit the next required action.
    • Generated-skill-with-CI-freshness-gate — same defect class our mcp-fixture-sync.test.ts guards; worth applying to skills that mirror CLI/runtime behavior (e.g., generate parts of run-knowledge-hub or eval-skill docs from source and --check them).
    • Playbook-per-artifact-shape — structurally identical to what B5 docket prompts want: a small catalog of typed, fetch-on-demand prompt templates rather than ad-hoc dispatch prose.
    • Annotate-the-artifact review loop for plans/specs — a lighter-weight human gate for spec review (the plan playbook explicitly targets pre-implementation review with annotatable open questions).
    • no-mistakes gate — an AI pre-review pipeline in an isolated worktree as a push gate rather than a PR-time gate.
  • Theme mapping: playbooks + next_step protocol fields → B5 (structured docket prompts, tool-emitted); plan playbook + annotation loop → C1 (a lighter spec-review chain for tasks that don’t warrant the full {N.1–N.4}); skill-freshness --check → A3 (fix-at-source for doc/skill drift, a recurring-issue class); SessionStart ambient sessions list → B2/B3 (carrying open-session state across sessions automatically); no-mistakes → B4-adjacent (fresh-context AI review of work product before it lands, albeit pre-push rather than transcript retro).
  • Maturity/caveats: 209 stars, most active of the family (pushed 2026-06-07). ESM JS with checkJs (no TS source), node:test, telemetry (Umami, opt-out via LAVISH_AXI_TELEMETRY=0). The Discord/marketing wrapper is heavier than the others.

Cross-repo synthesis (AXI family)

Section titled “Cross-repo synthesis (AXI family)”

The family is one thesis with a shared core and three surface adapters:

  • Common core (axi-sdk-js + the 10 principles): a CLI micro-framework giving every tool the identical agent contract — TOON-encoded stdout, structured AxiError + exit-code policy (0 incl. no-ops / 1 error / 2 usage), no-args home view showing live state, truncation-with-receipt + --full, suggestion lines after every output, and a marker-based idempotent SessionStart hook installer covering Claude Code/Codex/OpenCode with path-repair. Skills are generated from the same source as the home view and CI-checked for drift.
  • Per-surface adapters: gh-axi = stateless subprocess wrapper (gh JSON → minimal schema → TOON, error-pattern translation); chrome-devtools-axi = stateful daemon adapter (persistent bridge + generation-stamped refs because browser state is mutable between calls); lavish-axi = human-in-the-loop adapter (long-poll + SSE presence + next_step protocol steering because the “backend” is a person). The axi repo holds the spec, the SDK, and the measurement apparatus.
  • The transferable doctrine: (1) turn count dominates cost because every turn re-sends the growing context — so batch at the tool boundary (scripts, aggregates) rather than coaching the agent to be terse [A2]; (2) enforce output budgets at the source with truncation receipts and escape hatches, never via agent discipline [A1]; (3) convert recurring failure modes into structured, self-remediating signals (error tables, STALE_REF, definitive empty states, idempotent no-ops) so thrash loops can’t form [A3]; (4) inject compact, directory-scoped live state at SessionStart and put imperative next_step protocol into tool output rather than into briefs [B2/B3/B5]; (5) measure interventions with a conditions-matrix + LLM-judge harness before standardizing them — and note their evidence that lazy tool loading (ToolSearch-style) cost more than eager loading when most tools get used, which bears directly on our deferred-tool MCP configuration.

Survey 2 — treehouse, no-mistakes, gsh

Section titled “Survey 2 — treehouse, no-mistakes, gsh”

treehouse

Section titled “treehouse”
  • What it is: Go CLI managing a pool of reusable, pre-warmed git worktrees per repo (~/.treehouse/) so each agent session gets instant isolation without losing installed deps/build cache. “Manage worktrees without managing worktrees.”
  • Architecture/mechanism:
    • Pool of detached-HEAD worktrees; on treehouse get: fetch origin, scan pool for a worktree that is not in-use AND not dirty, hard-reset it to whichever of local/origin default branch is ahead, drop user into a subshell (internal/pool/pool.go::Acquire)
    • In-use detection = live process scan via gopsutil cwd-matching (internal/process/detect.go::FindProcessesInWorktree) plus short-lived owner reservations in a flocked state file — no daemon, no long-term status flags, self-healing stale entries
    • On exit/return: terminates lingering processes left in the worktree (e.g. an orphaned opencode pid), resets, returns worktree to pool with node_modules/build cache intact
    • Lifecycle hooks post_create/pre_destroy run in the worktree dir; hooks are honoured ONLY from user-level config — repo-level treehouse.toml hooks are deliberately ignored as a supply-chain safety choice (internal/config/, README §Hooks)
    • Pool cap (max_trees = 16) with an actionable error naming the remediation when exhausted
  • Workflow ideas worth stealing:
    • Pooled reuse instead of create/destroy per dispatch: our KH gotchas say “agents start stale, first action is git fetch && git reset --hard” and every worktree dispatch re-pays bun install/.next cache. A reset-on-acquire pool (dirty-check + process-check + reset + post_create hook running bun install only when lockfile changed) makes subagent dispatch near-free.
    • Automated “safe to reclaim” check = dirty-detect + live-process-detect, replacing our manual “ALWAYS check worktree git status before removing it” gotcha.
    • Lingering-process termination on return — kills the orphaned-dev-server/daemon class of worktree leaks.
    • Repo-level-hooks-ignored-for-safety split (repo config = repo-safe settings only; executable hooks = user config only).
  • Theme mapping: A2 (lowers the marginal cost of spawning a subagent, removing the main excuse for orchestrator-inline work); B2 (pool persists environment/allowlist state across sessions — the worktree IS the carryover); novel — “in-use detection via process scan” has no theme but directly automates an existing KH manual gotcha.
  • Maturity/caveats: 55 stars, 3 forks, created 2026-03, last commit 2026-05-15. Small, clean, well-tested, Windows-supported. Single-author. Stable concept, low risk to imitate (we’d imitate the mechanism, not adopt the tool, since our dispatches are branch-based, not detached-HEAD).

no-mistakes

Section titled “no-mistakes”
  • What it is: a local git gate — git push no-mistakes lands in a local bare repo whose post-receive hook hands the branch to a daemon that runs a fixed 9-step AI validation pipeline (intent → rebase → review → test → document → lint → push → pr → ci) in a disposable worktree, forwarding upstream + opening the PR only after the gate passes.
  • Architecture/mechanism:
    • Bare gate repo per project + post-receive hook + daemon (SQLite state, Unix-socket JSON-RPC IPC); each run in a disposable worktree; new push to same branch cancels in-progress run (docs/src/content/docs/concepts/gate-model.md)
    • Findings model: every step returns findings with severity + action: auto-fix | ask-user | no-op; bounded auto-fix loops per step (review defaults to 0 = always human approval; test/lint/rebase/ci default 3); on limit-hit the step pauses for human action (docs/concepts/auto-fix.md, internal/pipeline/executor.go)
    • Round history: every fix attempt is a DB “round”; a sanitized history (prior fix summaries, what user chose to fix vs ignore) is injected into the next fix/review prompt with “Do NOT re-report findings under user_chose_to_ignore unless materially different” (internal/pipeline/steps/round_history.go)
    • Intent extraction: if intent isn’t supplied, it mines local Claude Code/Codex/OpenCode/RovoDev/Pi transcripts, scores sessions by file-overlap against the diff (internal/intent/matcher.go, decisive score 0.85), summarizes, then injects into every downstream prompt as explicitly untrusted data — RedactSecrets + StripAdversarial + BEGIN/END markers + “data, not instructions” guard (internal/pipeline/steps/intent_prompt.go)
    • AXI agent-facing CLI: TOON (token-efficient) on stdout, progress on stderr, explicit exit codes, every response ends with a help[] list of the next commands; explicit “minimal-call convention” — sizes responses so an agent needs one call, not pagination (internal/cli/axi.go); logs fetched per-step on demand (axi logs --step <name> --full), never streamed wholesale
    • Composable prompt fragments: executionContextPromptSection() (explains the worktree .git pointer-file so agents stop hunting for “the real checkout” — internal/pipeline/steps/execution_context.go), userIntentPromptSection(), roundHistoryPromptSection(), plus a WorktreeSteering preamble idempotently prepended to every agent invocation declaring a soft workspace-write boundary (internal/agent/steering.go)
    • Evidence discipline: test step records tested[], testing_summary, artifacts[]; evidence committed under .no-mistakes/evidence/<branch-slug>/ (the repo dogfoods this); PR body gets deterministic ## Risk Assessment / ## Testing / ## Pipeline sections regenerated from DB rounds as an issue→fix→verification narrative
    • Enforcement layer: .github/workflows/no-mistakes-required.yml greps the PR body for the pipeline signature marker — un-gated PRs fail CI (bots exempted); guard-generated-files.yml blocks hand-edits to generated files; both workflows are themselves pinned by Go unit tests (workflow_no_mistakes_required_test.go) so the marker string and exemptions can’t silently drift from the code that emits them
    • SKILL.md is generated from a Go single source of truth (internal/skill/skill.go → cmd/genskill), with --check drift gate in make lint and CI
  • Workflow ideas worth stealing:
    • Round-history injection with “don’t re-report user-ignored findings” — the cleanest anti-thrash mechanism surveyed; directly applicable to our checker/fixer re-dispatch loops and review annotations.
    • Bounded auto-fix budget per step with forced human pause at the limit — converts unbounded “>3x median requests” thrash into a structural ceiling.
    • AXI conventions: machine output on stdout / progress on stderr, one-call-sized responses, help[] next-actions, on-demand per-step log retrieval — a template for our own agent-facing CLIs (ast-dataflow, ledger tools).
    • Composable sanitized prompt fragments (execution-context, intent, round-history, steering) instead of monolithic briefs.
    • File-overlap transcript matching to attach “what was the human trying to do” to a diff — cheap, deterministic candidate selection before any LLM call.
    • CI check that PRs carry a machine-verifiable pipeline signature + unit tests pinning the CI workflow content itself.
    • Rebase-then-short-circuit: if the diff is empty after rebase, skip all remaining steps.
    • Generated-skill-with-drift-check mirrors our bun run build:plugin commit-after pattern but adds the CI --check gate.
  • Theme mapping: A3 — round history + auto-fix limits + dedupe-only-after-committed-fix is the flag→root-cause→bounded-retry loop made structural. A1 — TOON output, per-step on-demand logs, review ignore_patterns diff filtering (filter-at-source). A2 — whole-pipeline delegation: the orchestrating agent only makes approve/fix/skip decisions; all executor work (review/test/lint/fix) happens in agent subprocesses in an isolated worktree. B5 — composable prompt-fragment builders are exactly “structured docket prompts”. B4 — transcript mining (intent extraction) is the inverse of our retro-candidate transcript review, same machinery (discover sessions → file-overlap score → summarize with fresh context). B1 — “intent is required, pass it from the conversation, don’t re-derive” mirrors subtask-not-backlog discipline. C1 — per-run --skip=<steps> push options = sanctioned chain right-sizing per task shape.
  • Maturity/caveats: 751 stars, 39 forks, created 2026-04, extremely active (last commit day-of-survey). Very high test discipline (tests for its own CI workflows and Makefile). Fixed pipeline order is deliberately non-configurable; daemon+SQLite footprint is heavier than anything we’d adopt wholesale — steal mechanisms, not the tool.

gsh

Section titled “gsh”
  • What it is: a POSIX-compatible “generative shell” in Go (mvdan/sh + bubbletea): inline command prediction, #-prefix agent chat, and a JS-like agentic scripting language where agents/models/tools/middleware are first-class.
  • Architecture/mechanism:
    • Tiered model routing: gsh.models.lite (1B local model, 15s timeout) for predictions, workhorse for agent work, premium reserved (cmd/gsh/defaults/models.gsh) — cost tier picked by task shape, not globally
    • Staged prediction escalation (cmd/gsh/defaults/middleware/prediction.gsh): keep existing prediction if still a prefix-match → history prefix lookup (free) → only on the debounced trigger call the LLM; instant trigger never pays LLM cost
    • Filter-at-source context assembly: __predictionContext() is deliberately tiny — cwd + git status --short --branch + last 10 history commands with exit codes; commit-message prediction context is capped at git diff --stat + -U15 | head -1000 with an explicit “limited to avoid huge outputs” comment (middleware/vcs_commit.gsh)
    • Hard tool-output caps in the interpreter: exec 50KB truncation with a "truncated": true flag returned to the model (internal/script/interpreter/exec_tool.go:60-71); view_file 100KB with TruncateFromMiddle keeping head+tail and a (truncated) marker plus prompt text telling the model it saw a truncated file (view_file_tool.go); grep similarly capped
    • Per-turn cost footer: after every agent turn the REPL prints 523 in (80% cached) · 324 out · 1.2s (cmd/gsh/defaults/events/agent.gsh::onAgentEnd) — token/cache visibility at the granularity of a single exchange
    • Middleware-chain extensibility (gsh.use("command.input", fn)) — Neovim-style: all default behaviour (agent routing, prediction, rendering) is itself middleware the user can replace; ACP integration delegates to external agents (@claude)
    • Dogfoods two sibling gating systems for its own development: .airlock/ (staged pipeline with AIRLOCK_RISK_THRESHOLD: medium on the human-review gate) and .rovodev/prompts.yml (named reusable dispatch prompts: next = “implement only the next pending work item in the plan, cover with tests, mark done — leave NO implementation notes”; cm = conventional commit)
  • Workflow ideas worth stealing:
    • The exec/view_file truncation pattern — cap + explicit truncated: true signal + middle-out truncation that preserves head and tail — is the precise A1 guard shape (vs naive tail-truncation that loses the command’s prologue).
    • The --stat-first, head -1000-bounded diff context in vcs_commit.gsh is a worked example of our “—stat-first” guard.
    • Staged escalation (cache-hit → cheap deterministic source → LLM only on debounce) as a general dispatch-cost ladder.
    • Per-turn token/cache-ratio footer: if our orchestrator surfaced per-dispatch in/out/cached numbers this cheaply, A2 (orchestrator-as-workhorse) would be self-evident in-session instead of needing post-hoc transcript analysis.
    • .rovodev/next.md’s “do NOT leave any implementation notes while marking done” — a one-line ledger-hygiene guard worth copying into curator briefs.
    • Risk-threshold-gated human approval (AIRLOCK_RISK_THRESHOLD: never|low|medium|high) — a single knob for how much autonomy a pipeline gets.
  • Theme mapping: A1 — output caps, truncated-flags, stat-first diff context, 10-entry history window (all filter-at-source). C1 — tiered models + staged escalation is right-sizing applied at every call, the per-call analog of lighter spec chains. A2 — per-turn cost footer is the observability primitive that would make workhorse-drift visible live. B3 — __predictionContext is a minimal worked example of “what belongs in start-of-turn context” (state, not history dumps). Middleware-everything architecture: novel — outside themes; it’s an extensibility philosophy, not a workflow efficiency mechanism.
  • Maturity/caveats: 396 stars, 18 forks, oldest of the three (created 2024-11), last commit 2026-05-18 — development appears to have shifted toward no-mistakes. README self-describes as early-stage. The scripting language is bespoke; the transferable value is in the default scripts and interpreter guard patterns, not the language.

Cross-repo synthesis (treehouse / no-mistakes / gsh)

Section titled “Cross-repo synthesis (treehouse / no-mistakes / gsh)”

Common patterns (one author, one philosophy):

  1. Disposable/pooled worktree as the unit of agent work — agents never touch the primary tree; isolation is structural, not disciplinary. treehouse pools them; no-mistakes disposes them; both auto-detect in-use via process scanning.
  2. Bounded loops with forced human pauses — every automated fix cycle has an attempt budget; hitting it pauses rather than thrashing; prior-round memory prevents re-litigating ignored findings.
  3. Single source of truth + CI drift gates for agent-facing artefacts — generated SKILL.md with --check, unit tests pinning CI workflow strings, “guard generated files” workflow. Convention is enforced by machine, not memory.
  4. Token-frugality as a first-class design constraint — TOON output format, one-call-sized responses, hard output caps with truncation flags, stat-first diffs, tiered models, per-turn cost display.
  5. Untrusted-text hygiene — anything mined from transcripts is redacted, adversarial-stripped, delimiter-wrapped, and labelled “data, not instructions” before re-injection into prompts.

Most transferable single idea per repo:

  • treehouse → reset-on-acquire worktree pool with dirty/process-scan reclamation: removes the per-dispatch stale-start + dependency-reinstall tax and automates our manual “check git status before removing worktree” gotcha (A2 enabler, B2).
  • no-mistakes → round-history injection with per-step auto-fix budgets (“don’t re-report what the user chose to ignore; pause at the limit”): a drop-in structural fix for A3 recurring-issue thrash, implementable today in our checker/fixer dispatch briefs plus a ledger-side rounds record.
  • gsh → the A1 guard kit: hard output caps with explicit truncated: true model-visible flags, middle-out truncation, and --stat-first + head-bounded diff context — concrete reference implementations for our unbounded-tool-output guards.

Survey 3 — acp-mock, acpx

Section titled “Survey 3 — acp-mock, acpx”

acp-mock

Section titled “acp-mock”
  • What it is: A deterministic ACP (Agent Client Protocol) agent test double — a CLI process that speaks real ACP JSON-RPC over stdio via @agentclientprotocol/sdk but emits scripted session updates instead of calling an LLM. Purpose: E2E-test ACP clients “without spending tokens or trusting a live agent.”
  • Architecture/mechanism:
    • 3 source files: src/cli.ts (Commander → AgentSideConnection over ndJsonStream(stdout, stdin)), src/mock-agent.ts (full Agent interface: initialize/authenticate/newSession/setSessionMode/prompt/cancel), src/index.ts (test helpers mockAgentArgs/mockAgentCommand/readJsonLines).
    • Scripted turns: fixed text/JSON agent message, synthetic usage_update (static or cumulative per-prompt token growth — simulates context-fill), N tool_call/tool_call_update pairs, abortable --prompt-delay-ms (for cancellation testing), --append-file workspace side-effect into session cwd (for asserting real file mutations).
    • Trace replay: --replay-runtime-events <jsonl> re-emits a recorded normalized runtime-event trace as live ACP session/update notifications, with <cwd> placeholder substitution (replayTraceFile/traceEventToSessionUpdate in src/mock-agent.ts:215-286).
    • Hard invariant (AGENTS.md): stdout is protocol-only; lifecycle logging is opt-in JSONL via --event-log; parse errors → stderr + exit 2.
    • Cancellation discipline: per-session pendingPrompt: AbortController; prompt aborts any prior controller; catch branch checks signal.aborted to return {stopReason: "cancelled"} instead of rethrowing.
  • Workflow ideas worth stealing:
    • Deterministic agent double for harness CI — point any agent-client test at a scripted process and assert exact session updates, cancellation behavior, and workspace changes. Would slot under the mcp-eval L1/L4 lanes for testing dispatch plumbing without burning tokens.
    • Record-once/replay-anywhere: normalized JSONL runtime traces as a replayable session-transcript format (--replay-runtime-events), including usage updates — lets a fresh process re-experience a prior session deterministically.
    • no-mistakes PR provenance gate (.github/workflows/no-mistakes-required.yml): human-authored PRs must be pushed through a pipeline that runs review/test/lint and writes a deterministic signature into the PR body; CI fails any PR lacking the marker; release/dependabot bots exempt.
    • Helper/CLI/README tri-sync invariant stated in AGENTS.md — a written guard-contract, like our mcp-fixture-sync.test.ts pattern.
  • Theme mapping:
    • Trace replay + event-log JSONL → B4 (fresh-context review of a session transcript: a recorded trace is exactly the artifact a retro-reviewer replays).
    • Deterministic double w/ cumulative usage mode → A1-adjacent (lets you test context-growth/size-guard handling deterministically) and novel — outside themes: token-free harness CI.
    • no-mistakes gate → novel — outside themes: provenance/quality gate on PR submission path rather than post-hoc review.
  • Maturity/caveats: 2 stars, v1.1.0, created 2026-05-02, last push 2026-05-12. Tiny (3 files), complete and disciplined (release-please, CI, guard-generated-files workflow, TDD policy), but single-author and young. The ideas, not the dependency, are the value.

acpx

Section titled “acpx”
  • What it is: Headless CLI client/multiplexer for ACP — lets agents/orchestrators drive other coding agents (codex, claude, gemini, cursor, copilot, +12 more in src/agent-registry.ts) over structured JSON-RPC instead of PTY scraping. Persistent sessions, prompt queueing, permissions, structured output, plus an experimental TypeScript workflow runtime (“flows”).
  • Architecture/mechanism:
    • Sessions scoped by (agentCommand, cwd, optional name), persisted in ~/.acpx/sessions/*.json; routing walks up from cwd to nearest git root; named parallel sessions via -s; soft-close (record kept, closed: true); crash detection → reconnect + session/load, fallback to session/new.
    • Single-writer queue ownership: the process running a prompt becomes queue owner; other invocations submit over Unix-socket IPC; ownership coordinated by lease file with {pid, socketPath, generation, heartbeatAt} (src/cli/queue/lease-store.ts); stale-heartbeat detection + generation increments prevent takeover races; idle TTL governs owner shutdown; target architecture is a detached warm owner daemon so callers exit at end_turn (docs/2026-02-25-warm-session-owner-architecture.md).
    • Flows (docs/2026-03-25-acpx-flows-architecture.md): defineFlow({name, startAt, nodes, edges}) with exactly 4 node kinds — acp (model judgment), action (runtime-supervised deterministic mechanics: shell, gh api, tests), compute (pure local transforms/routing), checkpoint (pause for human/external event). Routing is deterministic and lives outside the worker (“the worker is not the workflow engine”); node outcomes ok|timed_out|failed|cancelled are routable control-plane state separate from business output; per-node cwd keeps agent work inside disposable worktrees; one main ACP session shared across judgment steps with a hard rule: dead transport → reconnect + session/load same session, never silently start a fresh session.
    • Trace/replay run bundles (docs/2026-03-26-acpx-flow-trace-replay.md): self-contained ~/.acpx/flows/runs/<id>/ with manifest.json, append-only trace.ndjson (source of truth, seq + attemptId), derived projections (run.json/live.json/steps.json), bundled per-session record.json + raw events.ndjson, and content-addressed sha256 artifacts for all large payloads; each ACP node outcome carries explicit conversation-slice linkage (messageStart/End + eventStartSeq/EndSeq).
    • Output policy: text|json|quiet, --json-strict, and --suppress-reads which replaces read-tool payloads with [read output suppressed] (src/cli/output/read-suppression.ts).
    • Machine error contract (docs/ACPX_ERROR_STRATEGY.md): two-layer — stable enum code (NO_SESSION/TIMEOUT/PERMISSION_DENIED/…) + detailCode + origin + retryable hint + raw ACP envelope; cancellation is a normal completion (stopReason: "cancelled"), never an error path; one shared normalization module.
    • Conformance suite (conformance/): 21 data-driven JSON case files + profile + runner; runs against a mock ACP adapter by default or any real adapter command.
  • Workflow ideas worth stealing:
    • --suppress-reads filter-at-source + artifact externalization: spec rule “do not inline large or multi-line payloads” — node_outcome stores an outputArtifact ref (path + mediaType + bytes + sha256) and only tiny scalars go outputInline; session history stores truncated textPreview rows, never transcripts (src/session/conversation-model.ts:221).
    • acp/action/compute split with runtime-owned supervision: timeouts, heartbeats, retries, liveness, persistence all owned by the runtime, never the model turn; mechanics (git fetch, gh api, tests, codex review) run as supervised actions outside agent context.
    • Routable failure outcomes: timed_out/failed route via switch edges (e.g. review_loop timed out -> escalate to human) instead of thrashing or dying; default = fail loudly when a non-ok outcome has no route.
    • Pre-run permission resolution (docs/2026-03-28-acpx-flow-permission-requirements.md): a flow declares its minimum permission mode + whether it needs an explicit operator grant; runner resolves effective mode and its source and fails fast before any work if the grant is missing; granted mode propagates faithfully through queue-owner and session-reuse paths.
    • TUNING.md decision journal (examples/flows/pr-triage/TUNING.md): dated entries with Change / Reason / “What we decided NOT to do” / PR link, colocated with the flow definition — workflow tuning decisions captured at the artifact they tune.
    • pr-triage flow (examples/flows/pr-triage/pr-triage.flow.ts, 1,385 lines): full agentic SDLC lane — intent extraction → solution judgment → bug/feature classification → validation → refactor-depth classification (none/superficial/fundamental) → review loop → CI loop → conflict gates before validation AND before handoff → three terminal lanes (close with comment / ready-for-landing / needs-human-judgment).
    • AGENTS.md governance: bug-fix merge gate requiring (1) symptom evidence, (2) verified root cause with file/line, (3) fix touches implicated path, (4) regression test or documented manual proof; “no new node” default; scoped validation matrix (docs-only → check:docs only); harness-doc sync policy (any harness change must update SKILL.md + agents/{Agent}.md in the same PR).
    • Session identity triple (docs/2026-02-23-session-identity-spec.md): acpxRecordId (stable local record) vs acpxSessionId (wire session) vs agentSessionId (provider-native, never synthesized) — explicit naming for the three identities every dispatch layer conflates.
    • .pi/prompts/landpr.md: repo-local 17-step procedural landing prompt with goal invariant (“MERGED never CLOSED”), exact gh/git commands, validation gate selection by change scope, and post-merge verification.
    • Launch ownership (docs/2026-04-06-built-in-agent-launch-ownership.md): the dispatcher owns adapter resolution/version pinning/launch; resolve installed package entrypoint and run with process.execPath so children inherit the parent’s Node runtime.
  • Theme mapping:
    • --suppress-reads, artifact refs, textPreview truncation, --format quiet/json | jq → A1 (filter-at-source, size-bounded persistence; the artifact-ref pattern is the direct fix for multi-MB outputs landing in context).
    • acp/action/compute boundary + “the worker is not the workflow engine” + pr-triage’s 11-node acp/action interleave → A2 (the codified anti-pattern of our orchestrator-as-workhorse: deterministic mechanics never consume reasoning context).
    • Routable node outcomes, TUNING.md journal, 30-min-review timeout calibration (“elapsed time alone is not evidence of stuck”), bug-fix merge gate, perf-metrics counters/timings (src/perf-metrics.ts) + owner-takeover counts → A3 (root-cause-then-fix-at-source loop, plus the dispatch-latency observability needed to detect >3x-median thrash).
    • Pre-run permission requirement declaration + faithful propagation through owner/reuse paths → B2 (sandbox/allowlist carryover, but enforced as a fail-fast contract at dispatch time rather than a habit).
    • Run bundles with explicit per-node conversation-slice linkage + replay viewer → B4 (the exact substrate a fresh-context retro reviewer needs: self-contained, addressable transcript slices per workflow step, no live-state dependency).
    • README “Quick setup” paste-block + skills/acpx/SKILL.md + .pi/prompts/landpr.md → B5 (structured, versioned dispatch/docket prompts as repo artifacts).
    • Scoped CI/check matrix (docs-only skip code matrix), “no new node unless a real execution/timeout/artifact boundary”, “maintenance PRs accept standard repo checks” tuning entry → C1 (explicit right-sizing rules for validation/spec weight by task shape).
    • Coverage-roadmap doc (docs/2026-02-19-acp-coverage-roadmap.md) tracking implementation against the external evolving ACP spec → weak C2 (standing habit of diffing internal state against an external source of truth).
    • Queue-owner lease (generation + heartbeat + stale takeover), session identity triple, machine error contract with retryable, conformance suite, launch ownership → novel — outside themes: dispatch-infrastructure primitives (single-writer concurrency, identity discipline, retry-policy hints, protocol CI) with no current analog in our themes but direct applicability to subagent-fleet plumbing.
  • Maturity/caveats: upstream openclaw/acpx is real and active (2,830 stars, 276 forks, 7 open issues, pushed 2026-06-05); self-declared alpha with unstable interfaces; the kunchenguid fork surveyed is frozen at 2026-05-01. Flows are explicitly experimental; warm-owner daemon architecture is a design doc partially landed; conformance suite is a draft (21 cases). Heavy test investment (~70 test files) and unusually strong written governance for a young repo.

Cross-repo synthesis (acp-mock / acpx)

Section titled “Cross-repo synthesis (acp-mock / acpx)”
  • Relationship: acp-mock and acpx are two ends of the same ACP testing loop (kunchenguid is an openclaw/acpx contributor; acp-mock’s trace-replay consumes the same normalized runtime-event JSONL shape acpx emits, and acpx’s conformance runner defaults to a mock ACP adapter). Together they give a record-once/replay-anywhere cycle: acpx captures a live agent session into a self-contained run bundle → acp-mock re-emits that trace as a real protocol stream into any client under test, deterministically and token-free. The ACP spec (agentclientprotocol.com, Zed-ecosystem) is the contract both pin to.
  • Most transferable ideas, rough priority order:
    1. Artifact externalization + read suppression (A1) — “large payloads become content-addressed artifact refs; only small scalars inline” plus --suppress-reads is a complete, mechanism-level template for unbounded-tool-output guards: bound what enters context at the producer, keep full fidelity on disk, address it by hash.
    2. The acp/action/compute/checkpoint node taxonomy with routable outcomes (A2/A3) — a minimal vocabulary for splitting judgment from mechanics, where the runtime (not the model) owns timeouts/heartbeats/retries and timed_out is a routable edge, not a thrash loop. Reusable as dispatch-brief structure: every dispatch declares which lane it is (judgment vs mechanics) and what its non-ok route is.
    3. Self-contained replay bundles with explicit conversation-slice linkage (B4) — manifest + append-only trace + projections + bundled session events, with per-step messageStart/End/eventStartSeq/End pointers, is the storage contract a transcript-retro subagent should consume; our session archives lack exactly this addressability.
    4. Fail-fast pre-run permission/grant resolution (B2) — declare required permission mode in the work artifact, resolve effective mode + source before dispatch, propagate it through every reuse path; converts the sandbox-carryover habit into an enforced contract.
    5. TUNING.md-style colocated decision journals + the 4-point bug-fix evidence gate (A3) — cheap, high-leverage conventions for the flag→root-cause→fix-at-source loop.
    6. Single-writer queue-owner lease (pid + socket + generation + heartbeat, stale takeover) and the session identity triple — battle-shaped primitives for fleet concurrency (one writer per ledger/session) and for naming the local-record vs wire vs provider session identities our handoff docs currently blur.
    7. Scoped validation matrices and “no new node” defaults (C1) — written right-sizing rules that let routine task shapes take the light path without eroding the heavy path.