kimi-plugin-cc 2.4.0 → 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,18 +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 { runCliPromptWithBudget } from "../cli-client.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";
@@ -24,26 +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+.
+// kimi-code 0.18.0+. Exact 2.3.2 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
@@ -87,7 +76,7 @@ export function resolveSwarmWriteMaxConcurrency(requested) {
  * subagent, so slimming this text does not move the safety boundary. The optional
  * `cap` is a SOFT subagent-count hint (the hook cannot enforce a count). The HARD
  * concurrency ceiling is separate: --max-concurrency →
- * KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY (see executeSwarmJob / cli-client buildEnv).
+ * KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY (see executeSwarmJob / cli-client buildKimiCliEnvironment).
  * The --budget wall-clock ceiling is the always-on hard bound on the whole run.
  */
 export function buildSwarmPrompt(objective, cap) {
@@ -252,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");
         }
@@ -343,7 +332,7 @@ async function runWriteSwarm(parsed, objective, context) {
         }
         finally {
             if (preserveWorktree) {
-                context.stderr.write(`[kimi-plugin-cc] swarm-write patch capture failed; worktree retained at ${worktreePath}.\n`);
+                context.stderr.write(`[kimi-plugin-cc] swarm-write patch capture or session cleanup failed; worktree retained at ${worktreePath}.\n`);
             }
             else {
                 await removeWorktree(repoIdentity.repoRoot, worktreePath);
@@ -360,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
@@ -465,44 +423,183 @@ writeMode) {
         }
     }
     const handlers = createCliCancellationHandlers();
+    const budgetDeadline = Date.now() + budgetMs;
+    let activationOptions;
+    let preactivated;
+    let deactivationRequired = false;
+    let cleanupAttempted = false;
+    let cleanupFailure;
+    let finalText;
+    let recovery;
+    const commandLabel = writeMode ? "swarm-write" : "swarm";
+    const recoveryCleanupTimeoutMs = 2_000;
+    const cleanupSignal = (timeoutMs) => AbortSignal.any([
+        handlers.signal,
+        AbortSignal.timeout(Math.max(1, timeoutMs)),
+    ]);
+    const attemptDeactivation = async (identity, fallbackStage, timeoutMs = Math.max(1, budgetDeadline - Date.now())) => {
+        cleanupAttempted = true;
+        try {
+            await deactivateSwarmSession({
+                ...activationOptions,
+                ...identity,
+                signal: cleanupSignal(timeoutMs),
+            });
+            deactivationRequired = false;
+            return undefined;
+        }
+        catch (error) {
+            return error instanceof RuntimeError
+                ? error
+                : new RuntimeError("SWARM_SESSION_CLEANUP_FAILED", "Swarm session cleanup failed without a safe diagnostic payload.", fallbackStage);
+        }
+    };
     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,
+            command: executionPlan.command,
+            prefixArgs: executionPlan.prefixArgs,
+            executionPlan,
+            commandLabel,
+            model: job.model ?? undefined,
+            thinkingEffort: job.thinking_effort ?? undefined,
+            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" });
+            const activationController = new AbortController();
+            const onParentAbort = () => activationController.abort();
+            let activationTimedOut = false;
+            handlers.signal.addEventListener("abort", onParentAbort, { once: true });
+            if (handlers.signal.aborted)
+                onParentAbort();
+            const activationTimer = setTimeout(() => {
+                activationTimedOut = true;
+                activationController.abort();
+            }, Math.max(1, budgetDeadline - Date.now()));
+            activationTimer.unref();
+            try {
+                preactivated = await preactivateSwarmSession({
+                    ...activationOptions,
+                    signal: activationController.signal,
+                });
+                deactivationRequired = true;
+                store.updateRunningJob(job.job_id, {
+                    kimi_session_id: preactivated.sessionId,
+                    kimi_session_id_source: "preactivated",
+                });
+            }
+            catch (error) {
+                const activationDidTimeOut = activationTimedOut;
+                clearTimeout(activationTimer);
+                handlers.signal.removeEventListener("abort", onParentAbort);
+                const details = error instanceof RuntimeError ? error.details : {};
+                const sessionId = typeof details.session_id === "string" ? details.session_id : undefined;
+                const workspaceId = typeof details.workspace_id === "string" ? details.workspace_id : undefined;
+                const hasSessionIdentity = sessionId !== undefined && workspaceId !== undefined;
+                if (error instanceof RuntimeError &&
+                    error.code === "SWARM_SESSION_CLEANUP_FAILED" &&
+                    details.process_cleanup_unverified === true) {
+                    cleanupFailure = error;
+                }
+                if (hasSessionIdentity) {
+                    store.updateRunningJob(job.job_id, {
+                        kimi_session_id: sessionId,
+                        kimi_session_id_source: "preactivated",
+                    });
+                }
+                if (hasSessionIdentity && !handlers.cancelling) {
+                    const sessionCleanupFailure = await attemptDeactivation({ sessionId, workspaceId }, "swarm.activation-cleanup", recoveryCleanupTimeoutMs);
+                    if (sessionCleanupFailure)
+                        cleanupFailure = sessionCleanupFailure;
+                }
+                else if (hasSessionIdentity && cleanupFailure === undefined) {
+                    cleanupFailure = new RuntimeError("SWARM_SESSION_CLEANUP_FAILED", "Swarm session cleanup was not completed after activation was cancelled.", "swarm.activation-cleanup", { details: { cancelled: true, cleanup_unverified: true } });
+                }
+                if (activationDidTimeOut && !handlers.cancelling) {
+                    throw new ResponseTimeoutError(budgetMs, "swarm.activation", commandLabel, undefined, error);
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(activationTimer);
+                handlers.signal.removeEventListener("abort", onParentAbort);
+            }
+        }
+        const promptBudgetMs = budgetDeadline - Date.now();
+        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({
-            // Read mode spawns in the user's cwd; WRITE mode spawns in the throwaway
-            // worktree so coder subagents edit there (job.cwd stays the user's real
-            // cwd for lineage). This is the load-bearing isolation seam.
-            cwd: writeMode?.spawnCwd ?? job.cwd,
+            cwd: activationOptions.cwd,
             env: context.env,
             command: executionPlan.command,
             prefixArgs: [...executionPlan.prefixArgs],
             executionPlan,
             prompt,
-            // "swarm" → read-only-plus-AgentSwarm allowlist; "swarm-write" → the same
-            // PLUS rescue-grade write confinement to the trusted worktree root. The
-            // label drives the hook for the coordinator AND every spawned subagent.
-            commandLabel: writeMode ? "swarm-write" : "swarm",
-            // Always exported as KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY. kimi-code
-            // 0.18.0+ enforces this hard peak ceiling; older read-only binaries ignore
-            // it and retain only the wall-clock hard bound. Write mode requires
-            // 0.18.0+. Distinct from --cap, the soft total-count prompt hint.
+            commandLabel,
             swarmMaxConcurrency: maxConcurrency,
-            // Trusted allowlist root for the swarm-write hook (forge-proof; ignored
-            // by other labels). Only set in write mode.
             trustedWorkspaceRoot: writeMode?.workspaceRoot,
             model: job.model ?? undefined,
             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,
-        }, budgetMs, "swarm.prompt");
+        }, promptBudgetMs, "swarm.prompt");
+        if (recovery)
+            recordRecoveryEvent(store, recovery, { kind: "print-exit" });
         store.updateRunningJob(job.job_id, observedExecutionFields(result));
+        finalText = reassembleProseFromRecords(result.records);
+        let resultError;
         if (handlers.cancelling) {
-            throw new RuntimeError("SWARM_CANCELLED", "Swarm cancelled by user request.", "swarm.runtime");
+            resultError = new RuntimeError("SWARM_CANCELLED", "Swarm cancelled by user request.", "swarm.runtime");
+        }
+        else {
+            try {
+                assertCliResultSuccess(result, "swarm.runtime");
+                if (preactivated && result.sessionId !== preactivated.sessionId) {
+                    throw new RuntimeError("SWARM_SESSION_MISMATCH", "The resumed print session differs from the preactivated swarm session.", "swarm.session-provenance", { details: { expected_session_id: preactivated.sessionId, actual_session_id: result.sessionId ?? null } });
+                }
+            }
+            catch (error) {
+                resultError = error;
+            }
         }
-        assertCliResultSuccess(result, "swarm.runtime");
         warnHookEscapes(result, "swarm", context.stderr);
-        if (result.sessionId !== undefined &&
+        if (preactivated) {
+            cleanupFailure = await attemptDeactivation(preactivated, "swarm.cleanup");
+        }
+        if (resultError !== undefined)
+            throw resultError;
+        if (handlers.cancelling) {
+            throw new RuntimeError("SWARM_CANCELLED", "Swarm cancelled by user request.", "swarm.runtime");
+        }
+        if (cleanupFailure)
+            throw cleanupFailure;
+        if (!preactivated &&
+            result.sessionId !== undefined &&
             result.sessionId.length > 0 &&
             result.sessionId !== job.kimi_session_id) {
             store.updateRunningJob(job.job_id, { kimi_session_id_source: "announced", kimi_session_id: result.sessionId });
@@ -517,12 +614,14 @@ writeMode) {
         });
         warnIfSessionIdMissing(result, "swarm", job.job_id, context.stderr);
         const prose = reassembleProseFromRecords(result.records);
-        let finalText = prose;
+        finalText = prose;
         if (writeMode) {
             const captured = await capturePatchArtifact(paths, job.job_id, writeMode.workspaceRoot, context.stderr, writeMode.onPatchCaptureFailure);
             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);
@@ -541,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",
@@ -549,46 +650,99 @@ writeMode) {
         }) ?? job);
     }
     catch (error) {
+        if (preactivated && deactivationRequired && activationOptions) {
+            if (handlers.cancelling) {
+                cleanupFailure = new RuntimeError("SWARM_SESSION_CLEANUP_FAILED", "Swarm session cleanup was not completed after cancellation.", "swarm.cleanup", { details: { cancelled: true, cleanup_unverified: true } });
+            }
+            else if (!cleanupAttempted) {
+                cleanupFailure = await attemptDeactivation(preactivated, "swarm.cleanup", recoveryCleanupTimeoutMs);
+            }
+            else if (error instanceof RuntimeError && error.code === "SWARM_SESSION_CLEANUP_FAILED") {
+                cleanupFailure ??= error;
+            }
+        }
+        if (cleanupFailure) {
+            writeMode?.onPatchCaptureFailure?.();
+            context.stderr.write(`[kimi-plugin-cc] swarm session cleanup also failed: ${cleanupFailure.message}\n`);
+        }
         let captureFailed = writeMode !== undefined && error instanceof RuntimeError && error.code === "SWARM_PATCH_CAPTURE_FAILED";
         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`);
             }
         }
-        const recoveryDetails = captureFailed && writeMode ? { worktreePath: writeMode.workspaceRoot } : {};
+        const recoveryDetails = {
+            ...(error instanceof RuntimeError && typeof error.details.exit_code === "number"
+                ? { exit_code: error.details.exit_code }
+                : {}),
+            ...((captureFailed || cleanupFailure) && writeMode ? { worktreePath: writeMode.workspaceRoot } : {}),
+            ...(cleanupFailure
+                ? {
+                    cleanup_error: {
+                        code: cleanupFailure.code,
+                        stage: cleanupFailure.stage,
+                        cancelled: handlers.cancelling,
+                        unverified: true,
+                    },
+                    ...(finalText !== undefined ? { rawOutput: finalText } : {}),
+                }
+                : {}),
+        };
         if (handlers.cancelling) {
+            const cancellationCause = classifyManagedCommandFailure(error, writeMode ? "rescue" : "review", job.job_id, {
+                preserveStage: true,
+            });
             const cancelledError = new RuntimeError("SWARM_CANCELLED", captureFailed && writeMode
                 ? `Swarm cancelled; patch capture failed and worktree retained at ${writeMode.workspaceRoot}.`
                 : "Swarm cancelled by user request.", "swarm.runtime", {
                 ...(error instanceof Error ? { cause: error } : {}),
-                details: recoveryDetails,
+                details: {
+                    ...(cancellationCause instanceof RuntimeError ? cancellationCause.details : {}),
+                    ...recoveryDetails,
+                },
             });
             return await markJobCancelled(store, paths, job, "Swarm cancelled by user request.", cancelledError, {
                 phase: "cancelled",
             });
         }
+        if (error === cleanupFailure && budgetDeadline <= Date.now() && !(error instanceof ResponseTimeoutError)) {
+            error = new ResponseTimeoutError(budgetMs, "swarm.cleanup", commandLabel, undefined, cleanupFailure);
+        }
         const classified = classifyManagedCommandFailure(error, writeMode ? "rescue" : "review", job.job_id, {
             preserveStage: true,
         });
-        if (captureFailed && writeMode) {
-            const withRecovery = classified instanceof RuntimeError
+        const withRecovery = captureFailed || cleanupFailure
+            ? classified instanceof RuntimeError
                 ? new RuntimeError(classified.code, classified.message, classified.stage, {
                     cause: classified,
                     details: { ...classified.details, ...recoveryDetails },
                 })
-                : new RuntimeError("SWARM_PATCH_CAPTURE_FAILED", classified.message, "swarm.patch-capture", {
-                    cause: classified,
-                    details: recoveryDetails,
-                });
-            return await markJobFailed(store, paths, job, withRecovery, "Swarm failed.", { phase: "failed" });
-        }
-        return await markJobFailed(store, paths, job, classified, "Swarm failed.", { phase: "failed" });
+                : new RuntimeError(cleanupFailure?.code ?? "SWARM_PATCH_CAPTURE_FAILED", classified.message, cleanupFailure?.stage ?? "swarm.patch-capture", { cause: classified, details: recoveryDetails })
+            : classified;
+        return await markJobFailed(store, paths, job, withRecovery, "Swarm failed.", { phase: "failed" });
     }
     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) => {