kimi-plugin-cc 2.4.1 → 2.4.2

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";
@@ -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/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.";

package/plugins/kimi-codex/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/plugins/kimi-codex/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;
         }

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

@@ -44,6 +44,11 @@ export function classifyManagedCommandFailure(error, commandType, jobId, options
     const details = { availability: classification.kind };
     if (error instanceof RuntimeError) {
         details.cause_code = error.code;
+        for (const key of ["spawn_code", "spawn_errno", "spawn_message"]) {
+            if (error.details[key] !== undefined)
+                details[key] = key === "spawn_message" && typeof error.details[key] === "string"
+                    ? truncateCauseMessageForDetails(error.details[key]) : error.details[key];
+        }
         if (error.code === "RESPONSE_TIMEOUT") {
             for (const key of ["budget_ms", "record_count", "partial_output_chars", "aborted", "settled_post_abort", "hook_escapes"]) {
                 if (error.details[key] !== undefined)
@@ -129,28 +134,29 @@ function classifyKimiAvailability(error) {
             authProbe: "failed",
         };
     }
-    if (error instanceof RuntimeError && error.code === "CLI_SPAWN_FAILED") {
-        return {
-            kind: "binary_unavailable",
-            summary: "the Kimi CLI is missing from PATH or not executable in this environment.",
-            nextStep: "Run `/kimi:setup` to verify the install, then expose `kimi` on PATH and retry.",
-            runtimeProbe: "failed",
-            authProbe: "failed",
-        };
-    }
-    // v1.0 cli-client surfaces async ENOENT (Bun) as CLI_PROCESS_ERROR with
-    // "spawn ... ENOENT" in the message. Map that to binary_unavailable so
-    // the failure message points users at /kimi:setup.
     if (error instanceof RuntimeError &&
-        error.code === "CLI_PROCESS_ERROR" &&
-        /\bENOENT\b/.test(message)) {
-        return {
-            kind: "binary_unavailable",
-            summary: "the Kimi CLI is missing from PATH or not executable in this environment.",
-            nextStep: "Run `/kimi:setup` to verify the install, then expose `kimi` on PATH and retry.",
-            runtimeProbe: "failed",
-            authProbe: "failed",
-        };
+        (error.code === "CLI_SPAWN_FAILED" || error.code === "CLI_PROCESS_ERROR")) {
+        const spawnCode = error.details.spawn_code;
+        const binaryUnavailable = typeof spawnCode === "string" && ["ENOENT", "EACCES", "ENOEXEC"].includes(spawnCode);
+        if (typeof spawnCode === "string" && !binaryUnavailable) {
+            return {
+                kind: "startup_failed",
+                summary: "the Kimi subprocess could not be started or used.",
+                nextStep: "Check the underlying process error; shorten the prompt or environment if an argument-size limit was exceeded, then retry.",
+                runtimeProbe: "failed",
+                authProbe: "failed",
+            };
+        }
+        // Keep opaque synchronous failures and legacy async ENOENT diagnostics compatible.
+        if (binaryUnavailable || error.code === "CLI_SPAWN_FAILED" || /\bENOENT\b/.test(message)) {
+            return {
+                kind: "binary_unavailable",
+                summary: "the Kimi CLI is missing from PATH or not executable in this environment.",
+                nextStep: "Run `/kimi:setup` to verify the install, then expose `kimi` on PATH and retry.",
+                runtimeProbe: "failed",
+                authProbe: "failed",
+            };
+        }
     }
     // v1.0 cli-client surfaces non-ENOENT process errors and non-zero
     // exits as CLI_PROCESS_ERROR / CLI_NONZERO_EXIT. Treat both as

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

@@ -18,6 +18,7 @@ export const RESCUE_SUPPORTED_FLAGS = "-m/--model <name>, --thinking <off|low|me
 export const REVIEW_SUPPORTED_FLAGS = "--base <ref>, -m/--model <name>, --thinking <off|low|medium|high>, --budget <30m|1h|90s>";
 export const JOB_LOOKUP_SUPPORTED_FLAGS = "--type <review|challenge|rescue|review_gate|ask>, --json";
 export const SETUP_SUPPORTED_FLAGS = "--check, --uninstall, --all (with --uninstall), --enable-review-gate, --disable-review-gate, --models [--json] (without other setup flags)";
+export const RECOVER_SWARM_SUPPORTED_FLAGS = "--apply";
 export const REPAIR_SESSIONS_SUPPORTED_FLAGS = "--apply, --all";
 export const REPLAY_SUPPORTED_FLAGS = "none (one job-id required)";
 /** Validate syntax only; upstream per-model supportEfforts remains authoritative. */

package/plugins/kimi-codex/dist/prompt-size.js

@@ -0,0 +1,18 @@
+import { RuntimeError } from "./errors.js";
+// Node/libuv's default CreateProcess argument quoting (UTF-16 code units).
+export function windowsCommandLineLength(command, args) {
+    const quotedLength = (value) => {
+        if (value.length > 0 && !/[\s"]/u.test(value))
+            return value.length;
+        return 2 + value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1').length;
+    };
+    return [command, ...args].reduce((size, value) => size + quotedLength(value) + 1, 0);
+}
+export function assertPromptFitsCommandLine(command, args, platform = process.platform) {
+    if (platform !== "win32")
+        return;
+    const size = windowsCommandLineLength(command, args);
+    if (size <= 32_767)
+        return;
+    throw new RuntimeError("CLI_COMMAND_LINE_TOO_LONG", "The Kimi prompt exceeds the Windows command-line limit; the CLI was not started. Narrow the review or split it into smaller scopes. A short ask prompt can reference a saved diff inside the workspace. Reinstalling Kimi or running setup will not fix this. The current print transport does not support stdin prompts.", "cli-client.pre-spawn", { details: { command_line_utf16_units: size, limit_utf16_units: 32_767, platform } });
+}

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

@@ -39,6 +39,7 @@ export async function preactivateSwarmSession(options) {
         await verifyMeta(web, prepared.expectedVersion, options.signal, failureCode);
         const model = await resolveProfileModel(web, options, failureCode);
         identity = await createSession(web, options, failureCode);
+        options.onRecoveryEvent?.({ kind: "session", ...identity });
         profileMutationAttempted = true;
         await postSwarmProfile(web, identity, true, model, options.signal, failureCode);
         await verifySwarmStatus(web, identity, true, model, options.signal, failureCode);
@@ -88,6 +89,7 @@ export async function deactivateSwarmSession(options) {
         await verifySwarmStatus(web, options, false, undefined, options.signal, failureCode);
         await shutdownWeb(web, options.signal, failureCode);
         await requireSwarmJournal(prepared.kimiHome, options, "exit", options.signal, failureCode);
+        options.onRecoveryEvent?.({ kind: "disabled" });
         throwIfAborted(options.signal, failureCode, "swarm-deactivation.complete");
     }
     catch (error) {
@@ -144,6 +146,7 @@ async function startWebChild(options, env, failureCode) {
         "error",
     ];
     let child;
+    options.onRecoveryEvent?.({ kind: "web-spawn" });
     try {
         child = spawn(options.command, args, {
             cwd: options.cwd,
@@ -153,6 +156,7 @@ async function startWebChild(options, env, failureCode) {
         });
     }
     catch {
+        options.onRecoveryEvent?.({ kind: "web-exit" });
         throw failure(failureCode, "swarm-activation.spawn", "Failed to spawn the Kimi web lifecycle process.");
     }
     let exited = false;
@@ -184,6 +188,7 @@ async function startWebChild(options, env, failureCode) {
         child,
         closePromise,
         descendants: [],
+        onRecoveryEvent: options.onRecoveryEvent,
         trackingStopped: false,
         lastSnapshotComplete: false,
         snapshotIncomplete: false,
@@ -198,6 +203,8 @@ async function startWebChild(options, env, failureCode) {
     try {
         const ready = await waitForReadyLine(owned, options.signal, failureCode);
         await refreshOwnedDescendants(owned);
+        if (owned.recoveryFailed)
+            throw failure(failureCode, "swarm-activation.recovery", "Cannot persist web ownership; refusing session mutation.");
         return Object.assign(owned, ready);
     }
     catch (error) {
@@ -610,12 +617,26 @@ async function refreshOwnedDescendants(owned) {
             owned.snapshotIncomplete = true;
             owned.lastSnapshotComplete = false;
         }
+        try {
+            owned.onRecoveryEvent?.({ kind: "web-processes", identities: [...(owned.rootIdentity ? [owned.rootIdentity] : []), ...owned.descendants], complete: owned.lastSnapshotComplete });
+        }
+        catch {
+            owned.recoveryFailed = true;
+        }
     })().finally(() => {
         owned.refreshPromise = undefined;
     });
     return await owned.refreshPromise;
 }
 async function teardownOwnedChild(owned) {
+    const quiescent = await teardownOwnedChildInner(owned);
+    if (quiescent && !owned.recoveryFailed) {
+        owned.onRecoveryEvent?.({ kind: "web-exit" });
+        return true;
+    }
+    return false;
+}
+async function teardownOwnedChildInner(owned) {
     await stopDescendantTracking(owned);
     const childPid = owned.child.pid;
     if (childPid === undefined)