kimi-plugin-cc 2.4.1 → 2.4.3

package/docs/windows-validation.md

@@ -0,0 +1,39 @@
+# Windows community validation
+
+Windows remains unsupported; this is a narrow, credential-free diagnostics lane, not a support announcement. Contributions that reproduce native CLI and Git Bash behavior are welcome in [issue #14](https://github.com/linxule/kimi-plugin-cc/issues/14).
+
+## What is covered
+
+Community [PR #22](https://github.com/linxule/kimi-plugin-cc/pull/22) preserves structured spawn causes and distinguishes argument/resource exhaustion from a missing executable. Its author’s commits remain in the merge history.
+
+The added command-line guard rejects an oversized Windows command before spawn. It counts UTF-16 units, argument quoting and the terminating null. The new error is `CLI_COMMAND_LINE_TOO_LONG`; it identifies prompt size rather than suggesting reinstall/setup. It carries counts, not prompt contents.
+
+The Windows CI lane compiles the runtime, checks quoting with a real short Node subprocess, and sends a 103 KB prompt through the compiled client to prove refusal before spawn. It uses no credentials or provider calls.
+
+## Reproduce the no-model controls
+
+From a source checkout with Node 22.5+ and Bun:
+
+```powershell
+bun install --frozen-lockfile
+bunx tsc -p tsconfig.build.json
+node --test tests/windows/spawn-preflight.mjs
+```
+
+These controls do not start Kimi or modify its configuration. The checked-in distribution contains the vendored JavaScript required by the compiled client.
+
+## Evidence that would help next
+
+For a native Kimi or Git Bash report, include:
+
+- Windows, Node, Bun, Kimi and plugin versions; terminal/shell and install method.
+- Whether a short invocation works with the same executable and environment.
+- Whether a large review now refuses with `CLI_COMMAND_LINE_TOO_LONG`, without starting Kimi, rather than the misleading binary-unavailable error.
+- Whether a smaller command still produces ENOENT, EACCES or another structured spawn code, especially through `.cmd` or shell wrappers.
+- Sanitized error codes, numeric size fields, test output and an artificial reproducer—not credentials, raw config or a private repository diff.
+
+Do not bypass the managed hook to make a reproduction pass. Native model calls, if a contributor chooses to exercise them, use that contributor's existing configuration and quota; CI does not perform them.
+
+## Still open
+
+The print prompt is still passed in argv. Upstream 2.3.2's audited print entry point has no supported stdin prompt input; an unused stdin helper is not a transport contract. Large reviews above the limit still cannot run through this route. Do not close #14 based only on better error classification or the no-model Windows checks. A new prompt transport needs its own upstream source audit and exact-binary verification, without silently changing prompt/session lineage or hook enforcement.

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "kimi-plugin-cc",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "Kimi for Claude Code and Codex: code questions, independent reviews, bounded fixes, autonomous goals, parallel tasks, and MCP tools through the local Kimi Code CLI.",
   "type": "module",
   "engines": {
     "node": ">=22.5.0"
   },
   "scripts": {
-    "check": "bun run build && bun run check:surfaces && bunx tsc --noEmit && bun test && git diff --exit-code -- dist plugins/kimi-codex && UNTRACKED=\"$(git ls-files --others --exclude-standard -- dist plugins/kimi-codex)\" && { [ -z \"$UNTRACKED\" ] || { echo \"drift gate: untracked dist/codex files (stage them and re-run check):\"; echo \"$UNTRACKED\"; exit 1; }; }",
+    "check": "bun run build && bun run check:contracts && bun run check:surfaces && bunx tsc --noEmit && bun test && git diff --exit-code -- dist plugins/kimi-codex && UNTRACKED=\"$(git ls-files --others --exclude-standard -- dist plugins/kimi-codex)\" && { [ -z \"$UNTRACKED\" ] || { echo \"drift gate: untracked dist/codex files (stage them and re-run check):\"; echo \"$UNTRACKED\"; exit 1; }; }",
     "check:surfaces": "bun run scripts/generate-surfaces.ts --check",
     "generate:surfaces": "bun run scripts/generate-surfaces.ts",
     "build": "rm -rf dist && bunx tsc -p tsconfig.build.json && mkdir -p dist/vendor/shell-quote dist/vendor/smol-toml && cp runtime/vendor/shell-quote/LICENSE dist/vendor/shell-quote/LICENSE && cp runtime/vendor/smol-toml/*.js runtime/vendor/smol-toml/LICENSE dist/vendor/smol-toml/ && echo '{\"type\":\"module\"}' > dist/package.json",
     "companion": "node --import tsx runtime/companion.ts",
     "test": "bun test",
     "smoke:real": "KIMI_PLUGIN_CC_SMOKE=1 bun test tests/runtime/real-binary-smoke.test.ts --path-ignore-patterns '**/worktrees/**'",
-    "check:package": "node scripts/check-package.mjs"
+    "check:package": "node scripts/check-package.mjs",
+    "check:contracts": "node scripts/check-contract-size.mjs"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",
@@ -60,6 +61,8 @@
     "scripts/companion.sh",
     "scripts/review-gate-hook.sh",
     "docs/safety.md",
+    "docs/swarm-recovery.md",
+    "docs/windows-validation.md",
     "docs/migration.md",
     "docs/models.md",
     "docs/session-visibility.md",

package/plugins/kimi-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "kimi",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "Kimi for Codex: code questions, independent reviews, bounded fixes, autonomous goals, parallel tasks, and MCP job controls through the local Kimi Code CLI.",
   "author": {
     "name": "linxule"

package/plugins/kimi-codex/dist/cli-client.js

@@ -7,6 +7,7 @@
 import { spawn } from "node:child_process";
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
+import { assertPromptFitsCommandLine } from "./prompt-size.js";
 import { createHookEscapeMonitor } from "./hook-escape.js";
 import { RuntimeError, formatError } from "./errors.js";
 import { assertNoUnsafeExperimentalSelector, assertExecutionPlanMatchesSpawn, } from "./kimi-engine.js";
@@ -29,6 +30,14 @@ const DESCENDANT_SNAPSHOT_TIMEOUT_MS = 1_000;
 /** Hard bound for each batched identity revalidation pass. */
 const IDENTITY_REVALIDATION_TIMEOUT_MS = 250;
 const DESCENDANT_SNAPSHOT_TIMEOUT = Symbol("descendant-snapshot-timeout");
+function spawnErrorDetails(error) {
+    const cause = error;
+    return {
+        spawn_code: cause?.code,
+        spawn_errno: cause?.errno,
+        spawn_message: formatError(error),
+    };
+}
 export async function runCliPrompt(opts) {
     // Pre-aborted signal: refuse to spawn at all.
     if (opts.signal?.aborted === true) {
@@ -60,6 +69,7 @@ export async function runCliPrompt(opts) {
         });
     }
     const args = buildArgs(opts);
+    assertPromptFitsCommandLine(opts.command, args);
     const env = buildKimiCliEnvironment(opts);
     if (opts.logPath !== undefined) {
         await mkdir(path.dirname(opts.logPath), { recursive: true }).catch(() => {
@@ -82,8 +92,8 @@ export async function runCliPrompt(opts) {
     }
     catch (err) {
         throw new RuntimeError("CLI_SPAWN_FAILED", `Failed to spawn kimi: ${formatError(err)}`, "cli-client.spawn", err instanceof Error
-            ? { cause: err, details: { command: opts.command, args } }
-            : { details: { command: opts.command, args } });
+            ? { cause: err, details: { command: opts.command, args, ...spawnErrorDetails(err) } }
+            : { details: { command: opts.command, args, ...spawnErrorDetails(err) } });
     }
     // Pre-attach an 'error' listener immediately. Bun (and Node) can emit
     // 'error' asynchronously between spawn returning and our Promise body
@@ -550,8 +560,8 @@ export async function runCliPrompt(opts) {
         child.on("error", (err) => {
             appendLogLine({ event: "process_error", message: formatError(err) });
             settle("reject", new RuntimeError("CLI_PROCESS_ERROR", `kimi subprocess error: ${formatError(err)}`, "cli-client.process", err instanceof Error
-                ? { cause: err, details: errorDetails() }
-                : { details: errorDetails() }));
+                ? { cause: err, details: { ...errorDetails(), ...spawnErrorDetails(err) } }
+                : { details: { ...errorDetails(), ...spawnErrorDetails(err) } }));
         });
         if (earlyErrors.length > 0) {
             const captured = earlyErrors[0];
@@ -562,7 +572,7 @@ export async function runCliPrompt(opts) {
                     early: true,
                     additional_count: earlyErrors.length - 1,
                 });
-                settle("reject", new RuntimeError("CLI_PROCESS_ERROR", `kimi subprocess error: ${formatError(captured)}`, "cli-client.process", { cause: captured, details: errorDetails() }));
+                settle("reject", new RuntimeError("CLI_PROCESS_ERROR", `kimi subprocess error: ${formatError(captured)}`, "cli-client.process", { cause: captured, details: { ...errorDetails(), ...spawnErrorDetails(captured) } }));
             });
         }
         child.on("close", async (exitCode, signal) => {
@@ -643,8 +653,8 @@ export async function runCliPrompt(opts) {
         }
         catch (err) {
             settle("reject", new RuntimeError("CLI_PROCESS_ERROR", `kimi subprocess stream setup failed: ${formatError(err)}`, "cli-client.streams", err instanceof Error
-                ? { cause: err, details: errorDetails() }
-                : { details: errorDetails() }));
+                ? { cause: err, details: { ...errorDetails(), ...spawnErrorDetails(err) } }
+                : { details: { ...errorDetails(), ...spawnErrorDetails(err) } }));
         }
     });
 }

package/plugins/kimi-codex/dist/commands/cancel.js

@@ -36,6 +36,14 @@ export async function runCancel(argv, context) {
             (context.mcpCompanionIdentity === undefined || context.mcpKimiIdentity === undefined)) {
             throw new RuntimeError("MCP_CANCEL_REQUIRES_BINDING", `MCP job ${job.job_id} requires MCP job-control cancellation with recorded identities; use tasks/cancel or kimi_job_cancel.`, "mcp.cancel");
         }
+        const recovery = store.getSwarmRecovery(job.job_id)?.record;
+        if (recovery) {
+            const identity = recovery.owner;
+            const verified = identity && identity.pid === job.pid ? await revalidateProcessIdentities([identity]) : undefined;
+            if (!verified?.complete || verified.groupChanged?.length || verified.identities.length !== 1) {
+                throw new RuntimeError("SWARM_RECOVERY_REQUIRED", `Recorded swarm ownership is no longer live or verifiable. Preview companion.sh recover-swarm ${job.job_id}; no process was signalled.`, "cancel.identity");
+            }
+        }
         if (job.pid === null && job.kimi_pid === null) {
             throw new RuntimeError("CANCEL_NOT_SUPPORTED", `Job ${job.job_id} does not have a recorded process id to cancel.`, "cancel.runtime");
         }
@@ -75,7 +83,10 @@ export async function runCancel(argv, context) {
         }
         await assertMcpCompanionIdentity(job, context.mcpCompanionIdentity);
         await assertMcpKimiIdentity(job, context.mcpKimiIdentity);
-        signalJobProcesses(job, "SIGTERM");
+        if (recovery)
+            await assertMcpCompanionIdentity(job, recovery.owner);
+        // The live swarm owner owns child teardown, including web phases after print exit.
+        signalJobProcesses(job, "SIGTERM", { companion: true, kimi: !recovery });
         const cancelled = await waitForCancellation(paths, job.job_id);
         if (cancelled) {
             return `${JSON.stringify({
@@ -84,10 +95,10 @@ export async function runCancel(argv, context) {
                 message: "Cancellation completed.",
             }, null, 2)}\n`;
         }
-        const companionMatches = await assertMcpCompanionIdentity(job, context.mcpCompanionIdentity, true);
+        const companionMatches = await assertMcpCompanionIdentity(job, recovery ? recovery.owner : context.mcpCompanionIdentity, true);
         const kimiMatches = await assertMcpKimiIdentity(job, context.mcpKimiIdentity, true);
         if (companionMatches || kimiMatches) {
-            signalJobProcesses(job, "SIGKILL", { companion: companionMatches, kimi: kimiMatches });
+            signalJobProcesses(job, "SIGKILL", { companion: companionMatches, kimi: !recovery && kimiMatches });
         }
         await withJobStore(paths, async (forcedStore) => {
             const current = forcedStore.getJob(job.job_id);

package/plugins/kimi-codex/dist/commands/recover-swarm.js

@@ -0,0 +1,135 @@
+import { RECOVER_SWARM_SUPPORTED_FLAGS } from "../parsing.js";
+import { randomUUID } from "node:crypto";
+import { lstat, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createCliCancellationHandlers } from "../cli-cancellation.js";
+import { RuntimeError } from "../errors.js";
+import { captureWorktreePatch, resolveRepoIdentity } from "../git.js";
+import { verifyHookInstalled } from "../hooks/install.js";
+import { markJobFailed } from "../jobs.js";
+import { JobStore } from "../job-store.js";
+import { executionPlanFromPersisted, prepareKimiExecutionPlan } from "../kimi-engine.js";
+import { resolveKimiHome } from "../kimi-home.js";
+import { ensurePluginPaths, resolvePluginPaths } from "../paths.js";
+import { probeProcessIdentity } from "../process-tree.js";
+import { deactivateSwarmSession } from "../swarm-activation.js";
+import { assertRecoveryOwnerGone, finishRecoveryRecord, recordRecoveryEvent, recoverLaunch, recoveryError } from "../swarm-recovery.js";
+export async function runRecoverSwarm(argv, context) {
+    const positional = argv.filter((arg) => !arg.startsWith("-"));
+    if (positional.length !== 1 || argv.some((arg) => arg.startsWith("-") && arg !== RECOVER_SWARM_SUPPORTED_FLAGS) || argv.filter((arg) => arg === RECOVER_SWARM_SUPPORTED_FLAGS).length > 1) {
+        throw new RuntimeError("INVALID_ARGS", `Usage: companion.sh recover-swarm <job-id> [${RECOVER_SWARM_SUPPORTED_FLAGS}]. Defaults to preview.`, "swarm.recovery.args");
+    }
+    const jobId = positional[0];
+    const apply = argv.includes(RECOVER_SWARM_SUPPORTED_FLAGS);
+    const paths = resolvePluginPaths(context.env);
+    await ensurePluginPaths(paths);
+    const repo = await resolveRepoIdentity(context.cwd);
+    const store = new JobStore(paths);
+    let claim;
+    const handlers = createCliCancellationHandlers();
+    const signal = AbortSignal.any([handlers.signal, AbortSignal.timeout(30_000)]);
+    try {
+        const job = store.getJob(jobId);
+        const saved = store.getSwarmRecovery(jobId);
+        if (!job || job.repo_id !== repo.repoId || !saved || saved.record.schema !== 1 || saved.record.jobId !== jobId) {
+            throw recoveryError("No recovery record owned by this repository. Older runs require manual inspection.");
+        }
+        let record = saved.record;
+        const summary = () => ({ job_id: jobId, mode: apply ? "apply" : "preview", recovery_complete: record.complete,
+            session_id: record.session?.sessionId ?? null, session_cleanup_pending: record.sessionDirty,
+            launches: record.launches, worktree: record.workspaceRoot, patch_path: record.patchPath,
+            next_step: record.complete ? "No recovery is needed. Retained worktrees may be inspected and removed manually."
+                : `Inspect this record; use companion.sh recover-swarm ${jobId} --apply only after the original job has stopped.` });
+        const settleAbandonedJob = async () => {
+            if (job.status === "running")
+                await markJobFailed(store, paths, job, new RuntimeError("SWARM_OWNER_DISAPPEARED", "The original swarm companion stopped without reporting a result; resource recovery completed, not the task.", "swarm.recovery"), "Abandoned swarm resources recovered; task did not complete.", { phase: "failed" });
+        };
+        if (!apply)
+            return `${JSON.stringify(summary(), null, 2)}\n`;
+        if (record.complete) {
+            if (job.status === "running") {
+                await assertRecoveryOwnerGone(record);
+                await settleAbandonedJob();
+            }
+            return `${JSON.stringify(summary(), null, 2)}\n`;
+        }
+        await assertRecoveryOwnerGone(record);
+        if (saved.owner !== null) {
+            const owner = JSON.parse(saved.owner);
+            const live = await probeProcessIdentity(owner.pid);
+            if (!live.complete || live.identity?.startToken === owner.startToken)
+                throw recoveryError("Another recovery owner is alive or cannot be verified.");
+        }
+        const self = await probeProcessIdentity(process.pid);
+        if (!self.complete || !self.identity)
+            throw recoveryError("Cannot establish recovery ownership on this host.");
+        claim = JSON.stringify(self.identity);
+        if (!store.claimSwarmRecovery(jobId, saved.owner, claim)) {
+            claim = undefined;
+            throw recoveryError("Another recovery acquired this job.");
+        }
+        // Another owner may have completed and released the claim between our first read
+        // and the CAS (null -> owner -> null). Never overwrite that newer journal.
+        record = store.getSwarmRecovery(jobId).record;
+        if (record.complete) {
+            await settleAbandonedJob();
+            return `${JSON.stringify(summary(), null, 2)}\n`;
+        }
+        const expectedRoot = job.operation_kind === "swarm-write"
+            ? path.join(paths.worktreesDir, job.repo_id, `swarm-write-${job.job_id}`) : null;
+        if (record.workspaceRoot !== expectedRoot || record.cwd !== (expectedRoot ?? job.cwd)
+            || record.kimiHome !== resolveKimiHome(context.env, record.cwd)) {
+            throw recoveryError("Recovery workspace or Kimi home differs from the recorded job. Use its original home and repository; do not guess a session.");
+        }
+        if (expectedRoot) {
+            const st = await lstat(expectedRoot);
+            if (!st.isDirectory() || st.isSymbolicLink())
+                throw recoveryError("Recovery worktree must be the original non-symlink directory.");
+            const parent = await realpath(path.dirname(expectedRoot));
+            if (await realpath(expectedRoot) !== path.join(parent, path.basename(expectedRoot)))
+                throw recoveryError("Recovery worktree path is redirected.");
+        }
+        const persist = () => store.saveSwarmRecovery(jobId, record);
+        for (const launch of record.launches)
+            await recoverLaunch(launch, persist, signal);
+        if (record.sessionDirty) {
+            if (!record.session || !/^[\w-]+$/.test(record.session.sessionId) || !/^[\w-]+$/.test(record.session.workspaceId))
+                throw recoveryError("Recovery session identity is missing or invalid.");
+            const installed = await verifyHookInstalled(context.env);
+            if (!installed.installed)
+                throw recoveryError(`Managed hook verification failed: ${installed.reason ?? "unknown"}. Recovery does not install or relax hooks.`);
+            const plan = executionPlanFromPersisted(job);
+            const current = await prepareKimiExecutionPlan({ operationKind: plan.operationKind, cwd: record.cwd, env: context.env });
+            if (current.command !== plan.command || current.kimiVersion !== plan.kimiVersion || JSON.stringify(current.prefixArgs) !== JSON.stringify(plan.prefixArgs))
+                throw recoveryError("The exact recorded CLI is not selected. Restore that certified binary before session cleanup.");
+            signal.throwIfAborted();
+            await deactivateSwarmSession({ cwd: record.cwd, env: context.env, command: current.command,
+                prefixArgs: current.prefixArgs, executionPlan: current, commandLabel: expectedRoot ? "swarm-write" : "swarm",
+                trustedWorkspaceRoot: expectedRoot ?? undefined, ...record.session, signal,
+                onRecoveryEvent: (event) => recordRecoveryEvent(store, record, event) });
+        }
+        signal.throwIfAborted();
+        if (expectedRoot) {
+            // Capture without applying or deleting. A crash after the write leaves a recoverable artifact.
+            const patch = await captureWorktreePatch(expectedRoot, signal);
+            const patchPath = path.join(paths.artifactsDir, `swarm-recovered-${jobId}-${randomUUID()}.patch`);
+            await writeFile(patchPath, patch, { flag: "wx", mode: 0o600 });
+            record.patchPath = patchPath;
+        }
+        finishRecoveryRecord(store, record);
+        if (!record.complete)
+            throw recoveryError("Recovery remains incomplete; evidence and worktree were retained.");
+        await settleAbandonedJob();
+        return `${JSON.stringify(summary(), null, 2)}\n`;
+    }
+    finally {
+        handlers.dispose();
+        try {
+            if (claim !== undefined)
+                store.claimSwarmRecovery(jobId, claim, null);
+        }
+        finally {
+            store.close();
+        }
+    }
+}

package/plugins/kimi-codex/dist/commands/status.js

@@ -22,6 +22,6 @@ export async function runStatus(argv, context) {
             throw new RuntimeError("JOB_NOT_FOUND", "No matching job was found for status.", "status.lookup");
         }
         const job = await reconcileHistoricalJobProvenance(store, found);
-        return `${JSON.stringify({ ...job, thinking_effort_requested: job.thinking_effort ?? null, hook_escapes: parseHookEscapes(job.hook_escapes), budget_source: renderBudgetSource(job) }, null, 2)}\n`;
+        return `${JSON.stringify({ ...job, swarm_recovery: store.getSwarmRecovery(job.job_id)?.record ?? null, thinking_effort_requested: job.thinking_effort ?? null, hook_escapes: parseHookEscapes(job.hook_escapes), budget_source: renderBudgetSource(job) }, null, 2)}\n`;
     });
 }

package/plugins/kimi-codex/dist/commands/swarm.js

@@ -1,19 +1,22 @@
+import { resolveKimiHome } from "../kimi-home.js";
+import { probeProcessIdentity } from "../process-tree.js";
+import { recordRecoveryEvent, finishRecoveryRecord } from "../swarm-recovery.js";
 import { allocateJobId } from "../job-id.js";
-import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createCliCancellationHandlers } from "../cli-cancellation.js";
 import { ResponseTimeoutError, runCliPromptWithBudget } from "../cli-client.js";
 import { deactivateSwarmSession, preactivateSwarmSession, requiresSwarmPreactivation, } from "../swarm-activation.js";
 import { executionPlanFromPersisted, observedExecutionFields, persistedExecutionPlanFields, prepareKimiExecutionPlan, } from "../kimi-engine.js";
 import { RuntimeError } from "../errors.js";
-import { captureWorktreePatch, createEphemeralWorktree, hasBornHead, isWorkingTreeDirty, pruneWorktrees, removeWorktree, resolveRepoIdentity, } from "../git.js";
+import { captureWorktreePatch, createEphemeralWorktree, hasBornHead, isWorkingTreeDirty, removeWorktree, resolveRepoIdentity, } from "../git.js";
 import { digestPrompt, markJobCancelled, markJobFailed, sweepStaleJobs } from "../jobs.js";
 import { JobStore } from "../job-store.js";
 import { classifyManagedCommandFailure } from "../kimi-errors.js";
 import { KIMI_SWARM_DEFAULT_BUDGET_MS } from "../kimi-timeouts.js";
 import { writeInvocationLogHeader } from "../logging.js";
 import { ensurePluginPaths, resolvePluginPaths } from "../paths.js";
-import { MAX_DURATION_MS, parseSwarmArgs } from "../parsing.js";
+import { parseSwarmArgs } from "../parsing.js";
 import { readArtifact, renderManagedJobOutput, writeArtifact } from "../render.js";
 import { hookRefusalDetails, hookRefusalRetryProtocol, maybeWarnHookMissing, verifyHookInstalled, } from "../hooks/install.js";
 import { assertCliResultSuccess, reassembleProseFromRecords, warnIfSessionIdMissing, warnHookEscapes } from "./cli-helpers.js";
@@ -25,27 +28,11 @@ import { buildKimiSessionTitle, syncKimiSessionTitle } from "../session-title.js
 // only the wall-clock hard bound. Read/write modes reuse review/rescue lineage,
 // and the mandatory PreToolUse hook enforces read-only policy or trusted-worktree
 // write confinement on the coordinator and every subagent. Write mode requires
-// kimi-code 0.18.0+. Exact 2.3.2 additionally activates a same-job session through
+// kimi-code 0.18.0+. Exact 2.3.2 and 2.3.3 additionally activates a same-job session through
 // a bounded loopback web lifecycle, then resumes it through the normal print path.
 const SWARM_SUMMARY_MAX = 120;
 const SWARM_AGENT_PROFILE = "<swarm>";
 const SWARM_WRITE_AGENT_PROFILE = "<swarm-write>";
-/**
- * Orphaned write-swarm worktrees older than this are reaped by the startup sweep.
- * Every normal run removes its own worktree in a finally; orphans can follow a
- * hard kill or failed cleanup.
- *
- * The sweep's only liveness signal is the worktree dir's mtime, which is frozen
- * at `git worktree add` time when a run edits only EXISTING files (in-place edits
- * never bump the containing dir's mtime). A live run can therefore look "idle" for
- * its entire wall-clock life. So the TTL MUST exceed the longest a run can live —
- * the hard `--budget` ceiling, `MAX_DURATION_MS` (24h) — or a concurrent run's
- * sweep could `git worktree remove --force` a still-live worktree out from under
- * its owner (ENOENT writes, lost patch). The +2h margin covers budget-expiry
- * teardown (AbortController fires → the finally removes the worktree well within
- * it). Orphans are still reaped, just after this longer, provably-safe delay.
- */
-export const WORKTREE_ORPHAN_TTL_MS = MAX_DURATION_MS + 2 * 60 * 60 * 1000;
 /**
  * Default concurrency setting when the user passes no `--max-concurrency`.
  * The plugin always exports KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY; kimi-code
@@ -254,7 +241,7 @@ async function runWriteSwarm(parsed, objective, context) {
         if (!(await hasBornHead(context.cwd))) {
             throw new RuntimeError("WRITE_SWARM_NO_HEAD", "/kimi:swarm --write needs a git repository with at least one commit (HEAD). This repo has an unborn HEAD; make an initial commit first.", "swarm.precondition");
         }
-        await sweepStaleWorktrees(paths, repoIdentity);
+        // Abandoned trees are recovery evidence, never age-based garbage.
         if (await isWorkingTreeDirty(context.cwd)) {
             context.stderr.write("[kimi-plugin-cc] /kimi:swarm --write bases its worktree on HEAD — your uncommitted changes are NOT visible to the swarm. Commit or stash them first if the swarm needs them.\n");
         }
@@ -362,37 +349,6 @@ function assertWriteSwarmPreconditions(repoIdentity) {
         throw new RuntimeError("WRITE_SWARM_NOT_A_REPO", "/kimi:swarm --write requires a git repository (it works in a throwaway worktree off HEAD). The current directory is not inside a git repo.", "swarm.precondition");
     }
 }
-/**
- * Reap orphaned write-swarm worktrees from prior crashed runs. Normal runs remove
- * their own worktree in a finally; orphans can follow hard kills or failed cleanup.
- * Prune stale admin entries (current repo), then force-remove on-disk worktree
- * dirs older than the TTL. Best-effort — never blocks the run.
- */
-async function sweepStaleWorktrees(paths, repoIdentity) {
-    await pruneWorktrees(repoIdentity.repoRoot);
-    // Only sweep THIS repo's namespaced subdir, so we never `rm` a worktree that a
-    // different repo still considers live (and never leave that repo a dangling
-    // admin entry). repoId is the realpath-stable hash from resolveRepoIdentity.
-    const repoWorktreesDir = path.join(paths.worktreesDir, repoIdentity.repoId);
-    const entries = await readdir(repoWorktreesDir, { withFileTypes: true }).catch(() => null);
-    if (entries === null)
-        return; // not created yet — nothing to sweep.
-    const now = Date.now();
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !entry.name.startsWith("swarm-write-"))
-            continue;
-        const full = path.join(repoWorktreesDir, entry.name);
-        try {
-            const st = await stat(full);
-            if (now - st.mtimeMs > WORKTREE_ORPHAN_TTL_MS) {
-                await removeWorktree(repoIdentity.repoRoot, full);
-            }
-        }
-        catch {
-            // best-effort per entry
-        }
-    }
-}
 /**
  * Capture the worktree change set as a `.patch` artifact (write mode). Returns
  * the artifact path + size, or null on capture failure. Called on EVERY terminal
@@ -474,6 +430,7 @@ writeMode) {
     let cleanupAttempted = false;
     let cleanupFailure;
     let finalText;
+    let recovery;
     const commandLabel = writeMode ? "swarm-write" : "swarm";
     const recoveryCleanupTimeoutMs = 2_000;
     const cleanupSignal = (timeoutMs) => AbortSignal.any([
@@ -499,6 +456,14 @@ writeMode) {
     };
     try {
         const executionPlan = executionPlanFromPersisted(job);
+        if (requiresSwarmPreactivation(executionPlan.kimiVersion)) {
+            const owner = await probeProcessIdentity(process.pid);
+            recovery = { schema: 1, jobId: job.job_id, ownerPid: process.pid, owner: owner.identity ?? null,
+                kimiHome: resolveKimiHome(context.env, writeMode?.spawnCwd ?? job.cwd),
+                cwd: writeMode?.spawnCwd ?? job.cwd, workspaceRoot: writeMode?.workspaceRoot ?? null,
+                launches: [], session: null, sessionDirty: false, complete: false, patchPath: null };
+            store.saveSwarmRecovery(job.job_id, recovery);
+        }
         activationOptions = {
             cwd: writeMode?.spawnCwd ?? job.cwd,
             env: context.env,
@@ -511,6 +476,7 @@ writeMode) {
             swarmMaxConcurrency: maxConcurrency,
             trustedWorkspaceRoot: writeMode?.workspaceRoot,
             expectedVersion: executionPlan.kimiVersion ?? undefined,
+            onRecoveryEvent: recovery ? (event) => recordRecoveryEvent(store, recovery, event) : undefined,
         };
         if (requiresSwarmPreactivation(executionPlan.kimiVersion)) {
             store.updateRunningJob(job.job_id, { phase: "turn-running" });
@@ -577,6 +543,8 @@ writeMode) {
         if (promptBudgetMs <= 0)
             throw new ResponseTimeoutError(budgetMs, "swarm.prompt", commandLabel);
         store.updateRunningJob(job.job_id, { phase: "turn-running" });
+        if (recovery)
+            recordRecoveryEvent(store, recovery, { kind: "print-spawn" });
         const result = await runCliPromptWithBudget({
             cwd: activationOptions.cwd,
             env: context.env,
@@ -591,9 +559,17 @@ writeMode) {
             thinkingEffort: job.thinking_effort ?? undefined,
             resumeSessionId: preactivated?.sessionId,
             logPath: job.stream_log_path,
-            onSpawn: (pid) => { store.updateRunningJob(job.job_id, { kimi_pid: pid }); },
+            onSpawn: async (pid) => {
+                store.updateRunningJob(job.job_id, { kimi_pid: pid });
+                if (recovery) {
+                    const probe = await probeProcessIdentity(pid);
+                    recordRecoveryEvent(store, recovery, { kind: "print-processes", identities: probe.identity ? [probe.identity] : [], complete: probe.complete });
+                }
+            },
             signal: handlers.signal,
         }, promptBudgetMs, "swarm.prompt");
+        if (recovery)
+            recordRecoveryEvent(store, recovery, { kind: "print-exit" });
         store.updateRunningJob(job.job_id, observedExecutionFields(result));
         finalText = reassembleProseFromRecords(result.records);
         let resultError;
@@ -644,6 +620,8 @@ writeMode) {
             if (captured === null) {
                 throw new RuntimeError("SWARM_PATCH_CAPTURE_FAILED", `Swarm patch capture failed; worktree retained at ${writeMode.workspaceRoot}.`, "swarm.patch-capture", { details: { worktreePath: writeMode.workspaceRoot } });
             }
+            if (recovery)
+                recovery.patchPath = captured.path;
             finalText = `${renderWriteSwarmHeader(captured)}\n\n---\n\n${prose}`.trimEnd();
         }
         const rendered = renderManagedJobOutput(job, finalText);
@@ -662,6 +640,8 @@ writeMode) {
         if (handlers.cancelling) {
             throw new RuntimeError("SWARM_CANCELLED", "Swarm cancelled after artifact write.", "swarm.runtime");
         }
+        if (recovery)
+            finishRecoveryRecord(store, recovery);
         return (store.markCompleted(job.job_id, {
             summary: `[${writeMode ? "swarm-write" : "swarm"}] ${shorten(objective, SWARM_SUMMARY_MAX)}`,
             phase: "done",
@@ -689,6 +669,8 @@ writeMode) {
         if (writeMode && !(error instanceof RuntimeError && error.code === "SWARM_PATCH_CAPTURE_FAILED")) {
             const captured = await capturePatchArtifact(paths, job.job_id, writeMode.workspaceRoot, context.stderr, writeMode.onPatchCaptureFailure);
             captureFailed = captured === null;
+            if (recovery && captured)
+                recovery.patchPath = captured.path;
             if (captured && !captured.empty) {
                 context.stderr.write(`[kimi-plugin-cc] swarm-write run ended early; partial patch captured at ${captured.path}.\n`);
             }
@@ -745,7 +727,22 @@ writeMode) {
     }
     finally {
         handlers.dispose();
-        store.close();
+        try {
+            if (recovery)
+                finishRecoveryRecord(store, recovery);
+            if (recovery && !recovery.complete) {
+                writeMode?.onPatchCaptureFailure?.();
+                context.stderr.write(`[kimi-plugin-cc] recovery record retained: companion.sh recover-swarm ${job.job_id} (preview).\n`);
+            }
+        }
+        catch (error) {
+            // A failed final journal commit cannot authorize removal of recovery evidence.
+            writeMode?.onPatchCaptureFailure?.();
+            throw error;
+        }
+        finally {
+            store.close();
+        }
     }
 }
 function shorten(text, max) {

package/plugins/kimi-codex/dist/companion.js

@@ -1,3 +1,4 @@
+import { runRecoverSwarm } from "./commands/recover-swarm.js";
 import { companionHelp } from "./help.js";
 import { runModelInventory } from "./commands/models.js";
 import { runCancel } from "./commands/cancel.js";
@@ -77,6 +78,9 @@ async function main(argv) {
         case "replay":
             context.stdout.write(await runReplay(rest, context));
             return;
+        case "recover-swarm":
+            context.stdout.write(await runRecoverSwarm(rest, context));
+            return;
         case "repair-sessions":
             context.stdout.write(await runRepairSessions(rest, context));
             return;
@@ -84,7 +88,7 @@ async function main(argv) {
             await runWorker(rest, context);
             return;
         default:
-            throw new RuntimeError("INVALID_COMMAND", `Unknown or missing companion subcommand: ${command ?? "<none>"}. Expected one of setup, review, task, ask, status, result, cancel, replay, repair-sessions.`, "companion");
+            throw new RuntimeError("INVALID_COMMAND", `Unknown or missing companion subcommand: ${command ?? "<none>"}. Expected one of setup, review, task, ask, status, result, cancel, replay, repair-sessions, recover-swarm.`, "companion");
     }
 }
 main(process.argv.slice(2)).catch((error) => {

package/plugins/kimi-codex/dist/git.js

@@ -85,12 +85,13 @@ async function runGit(args, cwd) {
     }
     return result.stdout;
 }
-async function runGitAllowFailure(args, cwd) {
+async function runGitAllowFailure(args, cwd, signal) {
     try {
         const { stdout, stderr } = await execFileAsync("git", args, {
             cwd,
             env: process.env,
             maxBuffer: 10 * 1024 * 1024,
+            signal,
         });
         return { ok: true, stdout, stderr };
     }
@@ -163,11 +164,11 @@ export async function createEphemeralWorktree(repoRoot, base, worktreePath) {
  *
  * Returns the patch text (empty string if the swarm changed nothing).
  */
-export async function captureWorktreePatch(worktreePath) {
+export async function captureWorktreePatch(worktreePath, signal) {
     // Intent-to-add is required so untracked files surface in `git diff HEAD`.
     // An add -N failure aborts capture rather than returning a patch that omits
     // new files.
-    const intentToAdd = await runGitAllowFailure(["add", "-N", "--", "."], worktreePath);
+    const intentToAdd = await runGitAllowFailure(["add", "-N", "--", "."], worktreePath, signal);
     if (!intentToAdd.ok) {
         throw new RuntimeError("GIT_WORKTREE_INTENT_TO_ADD_FAILED", `git add -N (worktree capture) failed: ${intentToAdd.stderr || "unknown error"}`, "swarm.worktree", { details: { worktreePath } });
     }
@@ -176,6 +177,7 @@ export async function captureWorktreePatch(worktreePath) {
             cwd: worktreePath,
             env: process.env,
             maxBuffer: MAX_PATCH_BYTES,
+            signal,
         });
         return stdout;
     }

package/plugins/kimi-codex/dist/help.js

@@ -1,5 +1,5 @@
-import { hasHelpFlag, ASK_SUPPORTED_FLAGS, RESCUE_SUPPORTED_FLAGS, REVIEW_SUPPORTED_FLAGS, PURSUE_SUPPORTED_FLAGS, SWARM_SUPPORTED_FLAGS, JOB_LOOKUP_SUPPORTED_FLAGS, SETUP_SUPPORTED_FLAGS, REPAIR_SESSIONS_SUPPORTED_FLAGS, REPLAY_SUPPORTED_FLAGS, } from "./parsing.js";
-const SUBCOMMANDS = "setup, review, task, ask, status, result, cancel, replay, repair-sessions";
+import { hasHelpFlag, ASK_SUPPORTED_FLAGS, RESCUE_SUPPORTED_FLAGS, REVIEW_SUPPORTED_FLAGS, PURSUE_SUPPORTED_FLAGS, SWARM_SUPPORTED_FLAGS, JOB_LOOKUP_SUPPORTED_FLAGS, SETUP_SUPPORTED_FLAGS, REPAIR_SESSIONS_SUPPORTED_FLAGS, REPLAY_SUPPORTED_FLAGS, RECOVER_SWARM_SUPPORTED_FLAGS, } from "./parsing.js";
+const SUBCOMMANDS = "setup, review, task, ask, status, result, cancel, replay, repair-sessions, recover-swarm";
 const TASK_KINDS = "rescue, challenge, pursue, swarm";
 /** Help is a dispatch-only, side-effect-free exception to normal argument parsing. */
 export function companionHelp(argv) {
@@ -33,6 +33,7 @@ export function companionHelp(argv) {
         case "cancel":
             return usage(command, "[job-id] [options]", JOB_LOOKUP_SUPPORTED_FLAGS, command === "status" ? "Show job state as JSON." : command === "result" ? "Read a terminal artifact, optionally in a JSON envelope." : "Cancel a running job; without an id, target the repository's latest running job.");
         case "replay": return usage(command, "<job-id>", REPLAY_SUPPORTED_FLAGS, "Replay a completed job's persisted stream log.");
+        case "recover-swarm": return `Usage: companion.sh recover-swarm <job-id> [${RECOVER_SWARM_SUPPORTED_FLAGS}]. Preview durable swarm recovery; --apply stops verified orphans, disables the recorded session and captures a patch. Never resumes prompts or changes terminal job outcomes.`;
         case "repair-sessions": return usage(command, "[options]", REPAIR_SESSIONS_SUPPORTED_FLAGS, "Preview session metadata repair; --apply writes, --all selects all host-owned repositories.");
         case "worker": return "Usage: companion.sh worker <ask|rescue> <job-id>. Internal detached-worker entry point; launched by ask/rescue, not manually.";
         case "mcp": return "Usage: companion.sh mcp. Run the Kimi MCP stdio server; normally launched by Claude Code or Codex plugin configuration.";