kimi-plugin-cc 2.4.1 → 2.4.2

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Kimi for Claude Code: code questions, reviews, fixes, parallel tasks, and MCP tasks through the local Kimi Code CLI.",
-    "version": "2.4.1"
+    "version": "2.4.2"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kimi",
   "description": "Kimi for Claude Code: code questions, independent reviews, bounded fixes, autonomous goals, parallel tasks, and MCP tasks through the local Kimi Code CLI, with PreToolUse safety hooks.",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "homepage": "https://github.com/linxule/kimi-plugin-cc",
   "repository": "https://github.com/linxule/kimi-plugin-cc",
   "license": "Apache-2.0",

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > **Post-1.0 release history (v1.0.1 -> present) lives in [ROADMAP-TO-GA.md § Post-GA audit log](./ROADMAP-TO-GA.md#post-ga-audit-log)** and the "Version" / "Upstream compat" lines of [AGENTS.md](./AGENTS.md). Docs-only kimi-code compat checkups that don't bump the plugin version (e.g. the 0.14.2 / 0.14.3 patches) are recorded there, not here. Notable releases are summarized below; the GA entry and full pre-GA detail follow.
 
+## 2.4.2 — 2026-10-26
+
+- Integrate community PR #22's structured spawn-error classification, preserving contributor history. Bound the additional diagnostic message. Known argument/resource exhaustion no longer receives reinstall advice.
+- Refuse oversized Windows command lines before spawn and add a credential-free compiled-runtime Windows CI lane. This improves diagnosis, not prompt transport; issue #14 remains open for native Windows/community verification and large-review support.
+- Add durable, preview-first `recover-swarm` for exact 2.3.2 interrupted runs, with verified process ownership, pre-mutation session identity, recovery locking, explicit uncertainty refusals and patch preservation. Stop age-based deletion of abandoned worktrees. Exact CLI certification remains unchanged through 2.3.2.
+- Shorten the agent contract sheet and enforce its 32 KiB limit during `check`.
+
+Thanks to **@Nitjsefnie** for PR #22.
+
 ## 2.4.1 — 2026-10-25
 
 - Certify exact kimi-code 2.3.2 for all eight operations using the 15-test/92-assertion source scan, plan-ON/OFF controls, and the final 19-test/125-assertion production smoke. Keep the no-plan construction and legacy-v1 boundary at 0.41.x. See [evidence](docs/upstream-2.3.2-certification.md).

package/README.md

@@ -42,7 +42,7 @@ You need:
 - Node.js 22.5 or newer
 - Kimi Code CLI 2.3.2 (certified; 2.3.1 and 2.3.0 are also certified)
 
-Windows is not currently supported. Check your versions in a terminal:
+Windows is not currently supported. Contributors can help with the [no-model Windows diagnostics checks](./docs/windows-validation.md). Check your versions in a terminal:
 
 ```sh
 node --version
@@ -105,10 +105,10 @@ Codex. Published releases are also available as
 both compiled plugin distributions. No Bun, TypeScript, or install scripts are
 needed to use the package. Kimi Code CLI and Node are still prerequisites.
 
-For an explicitly versioned local Claude Code plugin, this example pins the published 2.4.0 package; 2.4.1 is not yet published:
+For an explicitly versioned local Claude Code plugin, this example pins the published 2.4.2 package:
 
 ```sh
-npm install --prefix ~/.local/share/kimi-plugin-cc kimi-plugin-cc@2.4.0
+npm install --prefix ~/.local/share/kimi-plugin-cc kimi-plugin-cc@2.4.2
 claude --plugin-dir ~/.local/share/kimi-plugin-cc/node_modules/kimi-plugin-cc
 ```
 
@@ -174,7 +174,7 @@ Use these commands to follow a task:
 | Read the result | `/kimi:result` | `$kimi-result` |
 | Cancel work | `/kimi:cancel` | `$kimi-cancel` |
 
-Without a job ID, cancel stops the latest running task for this repository. If several tasks are running, check which one you want to stop first. Use cancel rather than interrupting the app so write-swarm can save its patch.
+Without a job ID, cancel stops the latest running task for this repository. If several tasks are running, check which one you want to stop first. Use cancel rather than interrupting the app so write-swarm can save its patch. For interrupted runs created by the unreleased recovery implementation, see [preview-first swarm recovery](./docs/swarm-recovery.md); it never applies a patch or deletes abandoned work.
 
 Canceling a task does not undo changes it has already made.
 

package/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/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/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/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/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";
@@ -30,22 +33,6 @@ import { buildKimiSessionTitle, syncKimiSessionTitle } from "../session-title.js
 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/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/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/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.";

package/dist/job-store.js

@@ -122,6 +122,8 @@ export class JobStore {
       CREATE INDEX IF NOT EXISTS jobs_repo_updated_idx
         ON jobs (repo_id, updated_at DESC);
 
+      CREATE TABLE IF NOT EXISTS swarm_recovery (job_id TEXT PRIMARY KEY, payload TEXT NOT NULL, recovery_owner TEXT);
+
       CREATE INDEX IF NOT EXISTS jobs_repo_type_updated_idx
         ON jobs (repo_id, command_type, updated_at DESC);
 
@@ -186,6 +188,17 @@ export class JobStore {
             throw translateSqliteError(error);
         }
     }
+    getSwarmRecovery(jobId) {
+        const row = this.db.get("SELECT payload, recovery_owner FROM swarm_recovery WHERE job_id = ?", jobId);
+        return row ? { record: JSON.parse(row.payload), owner: row.recovery_owner } : null;
+    }
+    saveSwarmRecovery(jobId, record) {
+        this.db.run("INSERT INTO swarm_recovery (job_id, payload) VALUES (?, ?) ON CONFLICT(job_id) DO UPDATE SET payload = excluded.payload", [jobId, JSON.stringify(record)]);
+    }
+    claimSwarmRecovery(jobId, expected, owner) {
+        this.db.run("UPDATE swarm_recovery SET recovery_owner = ? WHERE job_id = ? AND recovery_owner IS ?", [owner, jobId, expected]);
+        return this.db.get("SELECT changes() AS count").count === 1;
+    }
     close() {
         this.db.close();
     }

package/dist/jobs.js

@@ -85,6 +85,9 @@ export async function sweepStaleJobs(store, paths) {
     for (const job of store.listRunningJobsWithProcessHints()) {
         if (store.getMcpTask(job.job_id))
             continue;
+        // Recovery owns orphaned swarm resources; PID-only sweeping must not signal replacements.
+        if (store.getSwarmRecovery(job.job_id))
+            continue;
         if (!isStaleEnoughToSweep(job)) {
             continue;
         }