Support Kimi Code CLI as a builder (PIR #1201)

[mohidmakhdoomi]

PIR Review: Support Kimi Code CLI as a builder

Fixes #1201

Re-integration notice (2026-08-09). This PR was parked on two upstream blockers, both now merged (#1317/#1267, #1356/PIR #1233), and main moved 900+ commits — including Spec 1313, which made afx send mailbox-first. kimi itself moved 0.27.0 → 0.34.0. The branch has been merged up and the feature substantially redesigned against what changed underneath it. The delivery mechanism, the resume mechanism, and the pacing seam are all different from what earlier reviewers saw; the summary below describes the current design, and "What changed since your last review" near the end lists the deltas. Re-review from scratch rather than from memory.

Summary

Adds the Kimi Code CLI (kimi, ≥ 0.33.0) as a supported builder harness — shell.builder: "kimi" / builderHarness: "kimi" / --builder-cmd kimi now produce a working builder instead of the #1062 false-Claude fallthrough (which appended --append-system-prompt and a positional prompt, both rejected by kimi, and could route a stale Claude --resume <uuid> into it).

Kimi has no system-prompt flag and takes no positional prompt, so role and task travel on two different channels:

• Role → --agent-file (kimi 0.31.0+). getWorktreeFiles writes an agent-definition file into the worktree whose body wraps the role around ${base_prompt} — the token that interpolates kimi's own default system prompt, so the role extends rather than replaces it. This is the claude --append-system-prompt analogue.
• Task → the Spec 1313 mailbox. The generated launch script queues the task with afx send, and the render gate delivers it onto a verified-empty composer. Never a direct PTY write, so a boot screen, a busy line, or kimi's folder-trust dialog holds the message rather than corrupting or losing it.

Crash restarts resume with the documented, cwd-scoped kimi -c — no session id is ever baked into generated bash. Kimi as an architect remains out of scope (stage 2); buildRoleInjection throws and doctor warns, so misconfiguration fails loudly rather than falling through to claude flags.

The finding that shaped the design

kimi -c does not fail when there is nothing to continue. It prints No sessions to continue under "<cwd>"; starting a fresh session. and starts one anyway — and that session never saw --agent-file, so it runs silently roleless. That is the #929 hazard class, arriving through a documented flag.

So the launch loop only takes -c after an inlined node -e store probe proves a conversation exists for this cwd, and the probe fails closed: any error (no store, unreadable dir, malformed JSON) exits non-zero and the loop relaunches fresh with the role, which is always safe. Tests execute that probe against fixture stores and cross-check its verdict against the TypeScript discovery it mirrors, so the hand-written snippet cannot silently drift from findLatestKimiSessionId.

The probe asks "would kimi -c continue this?", not "does a directory exist" — a distinction review had to teach me (see below). Kimi lists a cwd's sessions before continuing one, and that listing drops archived sessions and ids it does not recognize, so a session we call resumable but kimi skips lands right back on the roleless path. Both filters now apply on both sides of the mirror.

The same probe makes the script's entry self-configuring, so afx spawn --resume and a Tower-side terminal re-create need no second script shape — and a re-run never re-queues the task into a live conversation.

⚠️ Please look here first: two edits to shared, just-merged gate logic

servers/render-gate.ts is Spec 1313 code that landed recently. This PR touches its classifier in two places. Both are opt-in per profile, and neither can change behaviour for claude, codex or agy — argued below and pinned by tests.

1. The marker exemption follows the matched span instead of column 0

-      if (row === markerRow && col === 0) continue; // the marker glyph itself
+      if (col < markerEnd) continue; // the marker glyph itself

Why: kimi draws its composer inside a rounded box, so its prompt marker sits at column 3 (│ > ), not the row start. Under the column-0 rule the > glyph counts as user text, so a genuinely empty Kimi composer classifies user-text forever — i.e. holds all of its mail, permanently.

2. A profile may declare an upper bound for the composer region

GateProfile gains an optional regionStartPatterns. Kimi sets it to the box top; every other profile leaves it unset and keeps scanning from the marker row exactly as before.

This one fixes a false CLEAN, and it was found by review, not by me. KIMI_MARKER matches │ >, findMarkerRow takes the last match, and the scan started at that row. So a draft whose final line begins with > — a pasted quote, a markdown blockquote — puts the marker on the continuation row, leaving the real draft text above the scanned region. Measured on real kimi 0.34.0:

 ╭──────────────────────────────
 │ > implement the whole feature
 │   >
 ╰──────────────────────────────

→ classified {clean: true, detail: "empty"}. A queued message would then have been typed on top of unsent user input — the exact corruption Spec 1313 removes by construction. Committed as the kimi-multiline-bare fixture, captured rather than constructed.

The bound is exclusive, mirroring the region end, and that is load-bearing rather than stylistic: the box-top row's right corner ╮ is not in the classifier's ignorable-glyph set, so an inclusive bound counted it as user text and held every idle kimi composer forever. The fixture suite caught that on the first attempt.

Why other profiles cannot reach it: they declare no regionStartPatterns, so the region starts at markerRow; and since findMarkerRow returns the last match, no row below it can match either. The set of marker-matching rows in their region is exactly {markerRow} — the previous behaviour, by construction. A test asserts all three declare no region start, and that text above the composer still classifies clean for claude and codex.

Why it is a no-op for every other app, argued and then pinned by tests:

profile	marker	span	effect
claude	^[❯›]	1	col < 1 ≡ col === 0 — literally the old rule
codex	^[❯›]	1	same
agy	^>	2	extra cell is the space, already skipped by the whitespace rule that runs before the marker check
kimi	^\s*│\s*>	4	the case this exists for

Guardrail tests (render-gate.test.ts, "marker-span exemption is a no-op…"): the exact span per shipped profile; a tightest-possible 1-char draft in the first cell the exemption could wrongly reach, per profile, all still busy (over-skipping is the only direction that could cause harm — a false CLEAN); proof that agy's span can never over-reach a typed character (>x doesn't match its marker at all); and a direct before/after demonstration that a span-2 kimi profile classifies the real 0.34.0 idle capture user-text while the shipped span-4 one classifies it clean. Every pre-existing claude/codex/agy fixture still passes unchanged.

Undocumented-surface reliance (audited against kimi 0.34.0, 2026-08-09)

Two surfaces, both dated so the reliance can be re-checked on each Kimi major:

1. Session store ~/.kimi-code/sessions/wd_*/session_*/state.json. This has already drifted once: 0.33.0 renamed workDir → cwd, moved timestamps from ISO strings to epoch ms, and dropped lastPrompt. Readers accept both shapes, and codev doctor asserts the load-bearing facts explicitly and names the one that broke rather than reporting "something changed".

2. Workspace-trust record ~/.kimi-code/workspace-trust/wd_<basename>_<sha256(root)[:12]> → {root, trustedAt}. This is the maintainer veto point, so here is the full argument.

   kimi 0.33.0 added a startup "Trust this folder?" dialog. A builder worktree is always a brand-new directory; the dialog renders before any composer, and its only non-trusting option exits kimi — so an unattended builder would sit on it forever. The spawn path therefore pre-writes the trust record.

   • No sanctioned bypass exists. kimi --help has no flag; a full strings sweep of the 0.34.0 binary for KIMI_* env vars and for trust config keys found nothing (every "trust" hit was KaTeX/V8/OpenSSL noise). I looked for a supported knob first, as requested, and there isn't one.
   • What trust actually gates is narrow: whether project-level MCP servers (.mcp.json, .kimi-code/mcp.json) load from the folder. It does not gate tool execution or writes.
   • Scope: written only for a worktree Codev itself created, for a builder the human explicitly spawned, already running --yolo. It grants strictly less than launching the builder already authorized, and never touches a directory the user did not hand us.
   • Fail-soft: on any error the dialog simply appears, the gate holds the task message (no composer marker → busy), and mailbox escalation surfaces it. Never a silent misdelivery.
   • Drift is detected, not silent: codev doctor validates our derivation against kimi's own records (each record carries the root it was written for, so the expected filename is recomputable). A scheme change surfaces as a named warning instead of silently stranding every new builder on the dialog.

   My reviewers split on this one, so you should see both sides rather than just my case. Codex argued it is a real security boundary: --yolo governs approval of the agent's tool calls, whereas workspace trust governs whether repository-controlled MCP configuration is loaded and its processes started at all — so a builder spawned on a fork PR or other untrusted branch could have attacker-controlled MCP config loaded without a human ever seeing the decision. Claude reviewed the same code and reached the opposite conclusion: a --yolo builder in a Codev-created worktree already holds strictly more authority than MCP loading confers. I find Claude's reading more persuasive for the worktrees Codev creates, but Codex's fork-PR scenario is the case where the two arguments genuinely diverge, and that is a policy call I do not think is mine to settle.

   If you'd rather not ship the hash write at all, the fallback is that Kimi builders require one human keypress at first launch; say the word and I'll cut it. A narrower option, if you want the automation but not the blanket: refuse the pre-write when the worktree carries project-level MCP configuration.

Corrections to claims this PR previously made

• "Kimi has no hook seam, so Builder worktree write-guard: prevent writes anchored at the main checkout root #1018 write-guard parity is impossible" — obsolete. Kimi documents blocking PreToolUse hooks ([[hooks]] in config.toml, exit code 2 blocks, 18 events as of 0.32.0). Parity is achievable. I have scoped it as follow-up rather than growing this PR further, but that is your call — say so and I'll add it here. Until it lands, a Kimi builder can write outside its worktree, and the docs now say exactly that.

Two decisions that are yours, not mine

A. The version floor moves 0.27.0 → 0.33.0, which drops working installs

This is a real compatibility reduction and I want it visible rather than buried in a diff. The reasoning chain:

1. --agent-file requires ≥ 0.31.0. Below that the role does not inject at all and the builder runs silently roleless — the worst available failure mode, and not one a user would notice quickly.
2. The folder-trust dialog appears at 0.33.0, which is what the trust pre-write exists to handle. On 0.31–0.32 there is no dialog, so that machinery is inert — but it also means those versions are a genuinely different startup path from the one I exercised.
3. 0.33.0 is an engine boundary: it made agent-core-v2 the default. Every live measurement backing this PR — store shape, trust behaviour, the render-gate composer profile — was taken on 0.34.0, i.e. on that engine. 0.31–0.32 run the old engine and are unmeasured.
4. Kimi ships weekly, and its store has already renamed a load-bearing field once inside this PR's lifetime. Under that cadence a narrow, evidence-backed floor is safer than a wide compatibility claim I cannot stand behind.

So the floor sits at the oldest version the evidence actually covers, not the oldest that would nominally function. If you would rather accept 0.31.0 (functional minimum, unmeasured) or hold at 0.27.0 (maximum compat, definitely broken for role injection), say which and I'll change the one constant in doctor.ts plus the docs.

B. The .builder-kimi marker is deleted — this is not a revert of your July fix

Your July REQUEST_CHANGES found a real bug: the bare launch shape (no role, no prompt) never persisted .builder-kimi-session, so an override-spawned bare Kimi builder (--builder-cmd kimi in a claude-configured workspace) fell through to claude's 80ms Enter and its mail was swallowed. That fix — touch the marker in the bare branch — was correct and shipped.

This PR removes the marker entirely, so I want to be explicit that the property your finding protected is now stronger, not weaker.

The marker was a separate artifact that every launch shape had to remember to write. That is a standing obligation, and the bare shape is precisely the one that forgot it — which is why your review caught a bug rather than a typo. Adding the missing touch fixed that instance; it did not remove the class. A future fifth launch shape could forget it again.

Pacing now reads the harness name out of the generated .builder-start.sh, which is generated from the resolved harness. There is nothing to remember: any shape that launches kimi necessarily names kimi in command position, because that is the launch. The obligation is discharged by construction rather than by discipline, and it is still override-proof for exactly your scenario — a --builder-cmd kimi spawn against a claude-configured workspace resolves kimi, because the script was generated from the override.

Tests keep your scenario pinned directly (mailbox-pacing.test.ts: "resolves kimi for the BARE launch shape too — the shape the old marker probe missed", plus an explicit override-proofness test), and spawn-worktree.test.ts pins that both generated shapes put kimi in command position, so a refactor that hid it would fail rather than silently degrade pacing.

What changed since your last review

Was	Now	Why
Seed bootstrap: kimi -p seed → capture session.resume_hint → pinned kimi -S <id> loop	Role via --agent-file; task via the mailbox	Drops 3 undocumented surfaces; role rides a system prompt instead of a user turn
seed-kick.ts: sentinel watcher + grace + BEGIN written straight to the PTY, verified via state.json.lastPrompt	Deleted. Spec 1313's render gate is the readiness barrier	A direct PTY write is exactly what Spec 1313 forbids; the gate already answers "is this composer empty?"
Resume: explicit -S <discovered-id>	kimi -c behind a fail-closed store probe	Documented flag; no undocumented id in generated bash
Pacing via a .builder-kimi marker file	Harness read from the generated .builder-start.sh	The marker obliged every launch shape to write one — the bare shape didn't, which was your finding last round. The launcher is generated from the resolved harness, so it cannot be forgotten or overridden away
message-pacing.ts + seedKick on createTerminal	resolvePacingForSession in mailbox-wiring.ts; SeedKickRequest removed from the SDK	Spec 1313 replaced the routes the old pacing hooked into — it was wired to nothing after the merge

What the 3-way review round found (and what it changed)

Before opening this for re-review I ran gemini, codex and claude over the post-merge delta, asking them to attack the shared gate edit hardest. gemini APPROVE; codex and claude both REQUEST_CHANGES — and they were right. Full dispositions are committed at codev/projects/1201-*/1201-cmap-postpivot-dispositions.md; the two blocking ones are worth stating here because they say something about where the risk in this PR actually lives:

• The false CLEAN described above. Claude reproduced it on a constructed screen and flagged honestly that it had no live kimi to confirm the real multi-row geometry. I measured it — kimi renders exactly that shape. Claude also proposed a second input (a marker row inside a second box below the composer); measured, that one is not reachable, because kimi's / menu renders as unclosed │ rows with no ╰ beneath them, so anything inside it yields no-region-end → held. Both are now fixtures.
• The store probe diverged from the TypeScript it mirrors, and the cross-check test did not catch it because it compared two implementations of the same omissions. Codex found the dangerous direction: an archived session authorized -c, which kimi then refuses to continue, producing the silently-roleless session the guard exists to prevent. Claude found the safe-but-harmful direction: readdirSync on a stray non-directory threw ENOTDIR into the single outer try, so one .DS_Store in ~/.kimi-code/sessions/ disabled resume machine-wide, permanently and silently.

Also fixed from that round: shell metacharacters in a builder id or task path could execute when the launch script printed a recovery hint (all three reviewers, from different angles); a crash loop re-queued the same task every ~2s even though the mailbox persists held rows; and both drift probes reported healthy forever after a store migration, because "any record still matches" is satisfied by the pre-migration records.

The common thread: every one of these lives in a state a happy-path run does not produce — an empty composer and a clean store both behave correctly, which is precisely why three passing live demos missed them.

One more disclosure, since it affects how you should read the demo. Two demo steps were failing when I picked this back up, and the cause was the demo, not the product: its role told the model to prefix every reply with a token, which measures whether K3 honours a persistent output-format constraint rather than whether the role was injected. The --agent-file probe, run against a production-identical agent file, passed 7/7 including role survival across kimi -c. The demo now asks for a codeword instead — the same oracle the probe uses — and carries a comment explaining why, so the weaker check does not come back.

Verification

• pnpm build clean; full suite 4900 passed / 48 skipped / 0 failed.
• Live demo against real kimi 0.34.0, 7/7 (codev/spikes/pir-1201-kimi-builder-demo.mjs, runs the REAL dist modules): render gate classifies the live composer; --agent-file role honored in the interactive TUI; paced multi-line delivery submits; crash → store probe → kimi -c → role survives; probe fails closed on an empty store; trust pre-write idempotent.
• Pivot validation, 7/7 (pir-1201-kimi-agentfile-probe.mjs): --agent-file injects in both -p and the interactive TUI; TUI start mints no session, the first message mints exactly one; kimi -c resumes with the role binding intact and mints no second session.
• Gate fixtures are real 0.34.0 captures (pir-1201-kimi-gate-measure.mjs), committed raw — they carry only throwaway /tmp paths. Idle → clean; draft, multi-line draft, the bare-> multi-line draft, / menu, @ picker and the folder-trust dialog → busy (so a blind Enter can never confirm filesystem trust).

Out of scope

Kimi as architect (stage 2); ACP / kimi server adapter; #1018 write-guard parity (now achievable — see above).

[mohidmakhdoomi]

Architect Integration Review

Contributor-side review summary for maintainers (this PR was developed under the PIR protocol on our fork; we do not merge — that call is yours).

Process: Plan and dev-approval were human-gated pre-PR. The dev-approval gate included a full-path live demo through a locally installed build — a real afx spawn of a Kimi builder through Tower showing (1) seed-session bootstrap with session-id capture, (2) sentinel-gated, store-verified BEGIN delivery, (3) multiline afx send at the pinned Enter delay, and (4) inner-restart context retention via kimi -S — plus codev doctor's new kimi checks.

Consultation (CMAP, single advisory pass): gemini APPROVE, claude APPROVE, codex REQUEST_CHANGES. The codex finding was real and was accepted + fixed in 732f04b: seed-kick delivery confirmation was a substring match on lastPrompt, and the fresh-spawn seed prompt itself contains "BEGIN", so verification false-positived before the kick submitted — defeating the swallowed-Enter recovery. Fix is whitespace-normalized equality, with two pinning regression tests (both fail pre-fix), seed-kick suite 14/14, and a post-fix live demo re-run (5/5).

Architect verification of the post-CMAP fix (since PIR's single-pass consultation does not re-review fixes): I reviewed confirmed() in seed-kick.ts and the pinning tests directly — the equality predicate is correct, preserves the multiline-payload fallback (kimi flattens submitted newlines; normalization covers it), and the retry ladder (Enter re-send → one re-kick → loud warn) is intact. Known benign edge: a message raced into the session during the ~10s verify window causes one bounded re-kick, then a warning.

Scope: verified against issue #1201's builder-MVI checklist — no architect-parity changes (tower-utils/tower-instances/tower-terminals/session-manager/architect.ts untouched), no ACP adapter; kimi-as-architect fails loudly. Undocumented Kimi surfaces are labeled as observed, pinned to kimi >= 0.27.0 with a doctor smoke probe.

---

Architect integration review

[waleedkadous]

Outstanding work — this is one of the most disciplined external PRs we've received; the observed-vs-documented honesty around Kimi's store and the store-verified BEGIN ladder are exactly right. I'd like to see one change before merge: the bare launch path (no role, no prompt) doesn't persist .builder-kimi-session, so pacing resolution falls back to workspace config and an override-spawned bare Kimi builder gets Claude's Enter timing — the swallowed-Enter bug this PR fixes. Persisting a marker on every Kimi launch shape (plus a regression test for the override-spawn case, and softening the arch.md "exists iff Kimi-shaped" claim) closes it. I've added the area/tower label to #1201 for you.

[waleedkadous]

First, the thing that matters most: this sat un-re-reviewed for 26 days after you reported it green on Aug 9. That was our failure, not yours — you did the work, including a drift audit most contributors would have skipped, and the evidence discipline here (live demo against the real CLI, doctor drift-probes weighted by recency, honest documentation of the trust write) is exemplary. The 3-way integration review (gemini APPROVE; codex and claude REQUEST_CHANGES, both high confidence) confirms the design is right; the changes below are mostly a consequence of main moving underneath the branch while it waited.

Findings

1. Workspace-trust pre-write (security, verified against the branch). ensureKimiWorkspaceTrust writes ~/.kimi-code/workspace-trust/wd_… at spawn. Your arch.md note argues it grants strictly less than launching the builder already did — but the one thing the record gates (loading project-level MCP servers from .mcp.json / .kimi-code/mcp.json) is repository-controlled content, so a branch that commits an MCP config gets its processes loaded without the human ever seeing Kimi's dialog. That's the #1328 class. Refuse the pre-write when the worktree carries project-level MCP config, and/or gate it behind an explicit config opt-in.
2. Stale against three rebuilt seams. 1,603 commits behind and CONFLICTING: the write edge is now submitMessagePaced + in-lock precheck (#1365), gate details are consolidated under MailboxGateDetail/isUnverifiableVerdict (#1482), and marker anchoring moved to cursor-row/palette (#1474). Two of this PR's edits produce real post-merge defects against them — its new gate details bypass the #1482 consolidation and re-fork isClassifierStuck locally, so a stuck Kimi hold would render as "a human at the line" with no escalation. launchLoopTail is already on main.
3. Unmeasured under verified delivery. The 7/7 demo predates #1573/#1584 (echo-verification before delivered; zero re-writes). Kimi's echo behaviour is exactly the kind of thing that produced the #1583 loop — it needs measuring, not assuming.
4. The approved plan describes the retired design (seed-session / PTY-kick / -S, Kimi 0.27). The shipped architecture (mailbox + --agent-file + guarded -c + trust) was never re-approved, so the human-approved artifact no longer matches the code.
5. No PreToolUse write guard for Kimi builders (#1018 class) — documented, accepted as a follow-up by all three lanes.

What happens next — we'll do it, not you. Given the delay was ours and the conflicts are semantic (the delivery-path edits have to be re-derived against the converged code, not merged), I'm opening a PIR re-plan lane that builds on this branch: merge main, re-derive the write-edge and gate-detail integration, add the MCP-config refusal, update the plan to the shipped architecture for re-approval, and re-run the live demo under verified delivery. Your commits and authorship stay intact; the lane adds on top. If you'd rather drive it yourself, say so and I'll hand it back. Thank you for the patience — and for the audit that made this tractable.

[waleedkadous]

Re-plan lane opened: #1620 (PIR — plan re-approval and dev-approval gates, since the approved plan is stale and the trust change is security-relevant). It builds on this branch directly; nothing here is rebased or rewritten.

[waleedkadous]

Hi @mohidmakhdoomi — a heads-up and a request.

We are executing the re-plan described in #1620 directly on this branch: merging current main in (no rebase, no squash, your commits and authorship stay as they are), re-deriving the delivery-path integration against the write-edge, hold-verdict and marker-anchoring changes that landed while this sat, adding the workspace-trust refusals, and rewriting the 1201 plan to describe the shipped architecture. The 26-day gap that made this necessary is on us, not you.

One thing we cannot do on our side: we have no authenticated Kimi CLI here, and the CLI is now at 0.41.0, seven minors past the 0.34.0 you measured. So when our commits land, could you review the delta and re-run the live demo (codev/spikes/pir-1201-kimi-builder-demo.mjs) plus the render-gate captures on the current CLI? We will post a short, exact checklist here at that point so it is one pass for you rather than an open-ended ask.

Thank you for the original work — the design held up to a full 3-way review; only the branch had drifted.

[mohidmakhdoomi]

@waleedkadous although MoonshotAI/kimi-code#2767 remains unfixed (so --agent-file and --agent <custom_name> do not work), a potential workable approach is to create a Kimi agent profile (e.g. .kimi-code/agents/codev-builder.md) in the builder worktree, with name: agent + override: true + ${base_prompt} in the body → role present in the system prompt, Kimi's own default prompt interpolated ahead of it. This new agent profile replaces the default profile Kimi falls back to while keeping the role scoped to the builder worktree. This is documented behaviour (kimi's agents guide names it explicitly), not a back door. Then use launch the builder without --agent or --agent-file because the agent profile is the default Kimi cli binds anyway.