kimi-plugin-cc 2.4.5 → 2.5.2

package/plugins/kimi-dsh/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-dsh/dist/commands/registry.js

@@ -0,0 +1,74 @@
+import { RuntimeError } from "../errors.js";
+const passthroughOutput = "passthrough";
+const parsedOutput = "parsed";
+const DEFAULT_ESCALATION_MS = 1_500;
+/**
+ * Build cancellation config from the display name used verbatim in messages
+ * and the uppercase stem used in error codes.
+ */
+function makeCancellationConfig(prefix) {
+    const { displayName, errorCodeStem } = prefix;
+    return {
+        escalationMs: DEFAULT_ESCALATION_MS,
+        errorCodes: {
+            cancelledDuringStart: `${errorCodeStem}_CANCELLED_DURING_START`,
+            cancelled: `${errorCodeStem}_CANCELLED`,
+        },
+        cancelMessages: {
+            duringStart: `${displayName} cancelled during startup.`,
+            afterPrompt: `${displayName} cancelled by user request after prompt completion.`,
+            afterArtifact: `${displayName} cancelled by user request after artifact write.`,
+            default: `${displayName} cancelled by user request.`,
+        },
+        cancelledSummary: `${displayName} cancelled by user request.`,
+        failedSummary: `${displayName} failed.`,
+    };
+}
+/**
+ * Single source of truth for per-command behavior. Only commands using the
+ * managed-cancellation flow participate; `setup` and `task` do not.
+ *
+ * Display-name casing is part of the user-visible contract: `Ask` and `Rescue`
+ * are title-cased, while `review`, `challenge`, and `review_gate` are lowercase.
+ */
+export const COMMAND_REGISTRY = {
+    ask: {
+        outputMode: passthroughOutput,
+        cancellation: makeCancellationConfig({ displayName: "Ask", errorCodeStem: "ASK" }),
+    },
+    review: {
+        outputMode: passthroughOutput,
+        cancellation: makeCancellationConfig({ displayName: "review", errorCodeStem: "REVIEW" }),
+    },
+    challenge: {
+        outputMode: passthroughOutput,
+        cancellation: makeCancellationConfig({ displayName: "challenge", errorCodeStem: "CHALLENGE" }),
+    },
+    rescue: {
+        outputMode: passthroughOutput,
+        cancellation: makeCancellationConfig({ displayName: "Rescue", errorCodeStem: "RESCUE" }),
+    },
+    review_gate: {
+        outputMode: parsedOutput,
+        cancellation: makeCancellationConfig({ displayName: "review_gate", errorCodeStem: "REVIEW_GATE" }),
+    },
+};
+/**
+ * Convenience accessor for managed commands (review/challenge/rescue/
+ * review_gate/ask). Identical to direct lookup, with a defensive
+ * runtime guard: TypeScript narrows `commandType` to `ManagedCommandType`,
+ * but a stale SQLite row, corrupted job artifact, or future command
+ * type added without a registry entry could still reach here at
+ * runtime. A bare `COMMAND_REGISTRY[commandType]` would return
+ * `undefined` and surface as an unclassified `TypeError` at the
+ * destructure call site. Throwing a classified `RuntimeError` here
+ * keeps the failure path within the command-layer error model so
+ * /kimi:status and /kimi:result render it correctly.
+ */
+export function getManagedCommandConfig(commandType) {
+    const config = COMMAND_REGISTRY[commandType];
+    if (!config) {
+        throw new RuntimeError("UNKNOWN_COMMAND_TYPE", `No registry entry for command type "${String(commandType)}". This indicates a stale job record or an unregistered command.`, "commands.registry");
+    }
+    return config;
+}

package/plugins/kimi-dsh/dist/commands/repair-sessions.js

@@ -0,0 +1,160 @@
+import { REPAIR_SESSIONS_SUPPORTED_FLAGS } from "../parsing.js";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { RuntimeError } from "../errors.js";
+import { resolveRepoIdentity } from "../git.js";
+import { digestPrompt } from "../jobs.js";
+import { resolvePluginPaths } from "../paths.js";
+import { syncKimiSessionTitle } from "../session-title.js";
+// Repair is deliberately finite and local. Stream logs may be very large, but
+// the spawn record follows the invocation header: read only a bounded prefix.
+const MAX_JOBS = 1000;
+const MAX_SPAWN_BYTES = 2 * 1024 * 1024;
+export async function runRepairSessions(argv, context) {
+    const seen = new Set();
+    for (const arg of argv) {
+        if ((arg !== "--apply" && arg !== "--all") || seen.has(arg)) {
+            throw new RuntimeError("INVALID_ARGS", `Usage: repair-sessions. Supported flags: ${REPAIR_SESSIONS_SUPPORTED_FLAGS}.`, "repair-sessions.args");
+        }
+        seen.add(arg);
+    }
+    const apply = seen.has("--apply");
+    const all = seen.has("--all");
+    const paths = resolvePluginPaths(context.env);
+    const repoId = all ? undefined : (await resolveRepoIdentity(context.cwd)).repoId;
+    const jobs = await readRepairJobs(paths.stateDbPath, repoId);
+    const sessions = new Set();
+    const results = [];
+    for (const job of jobs) {
+        if (sessions.has(job.kimi_session_id))
+            continue;
+        sessions.add(job.kimi_session_id);
+        const promptText = await readVerifiedPrompt(job, paths.logsDir, paths.worktreesDir);
+        const status = promptText === undefined
+            ? "unavailable-verified-prompt"
+            : await syncKimiSessionTitle({
+                env: context.env,
+                cwd: job.cwd,
+                sessionId: job.kimi_session_id,
+                title: "",
+                promptText,
+                dryRun: !apply,
+                preserveTitle: true,
+                requireNativeV2: true,
+                stderr: context.stderr,
+            });
+        results.push({ job_id: job.job_id, session_id: job.kimi_session_id, status });
+    }
+    const counts = {};
+    for (const { status } of results)
+        counts[status] = (counts[status] ?? 0) + 1;
+    return `${JSON.stringify({ mode: apply ? "apply" : "dry-run", scope: all ? "host" : "repository", sessions: results.length, counts, results }, null, 2)}\n`;
+}
+async function readRepairJobs(filename, repoId) {
+    try {
+        const stats = await lstat(filename);
+        if (!stats.isFile() || stats.isSymbolicLink()) {
+            throw new RuntimeError("SESSION_REPAIR_UNSAFE_STORE", "Repair requires a regular, non-symlink job database.", "repair-sessions.store");
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const require = createRequire(import.meta.url);
+    // Bind constructors before `new`: compiler emission must not turn the
+    // module-loader call into the constructor (new require(...).Database).
+    const db = (() => {
+        if (typeof Bun !== "undefined") {
+            const { Database } = require("bun:sqlite");
+            return new Database(filename, { readonly: true });
+        }
+        const { DatabaseSync } = require("node:sqlite");
+        return new DatabaseSync(filename, { readOnly: true });
+    })();
+    try {
+        // Never construct JobStore here: it performs migrations and stale-row
+        // reconciliation. Both preview and apply keep plugin job data read-only.
+        const columns = db.prepare("PRAGMA table_info(jobs)").all();
+        const names = new Set(columns.map((column) => column.name));
+        const required = ["job_id", "repo_id", "command_type", "operation_kind", "status", "kimi_session_id", "cwd", "kimi_version", "intended_engine", "observed_engine", "stream_log_path", "prompt_digest", "updated_at"];
+        if (required.some((name) => !names.has(name)))
+            return [];
+        const rows = db.prepare(`
+      SELECT j.job_id, j.repo_id, j.operation_kind, j.kimi_session_id, j.cwd, j.kimi_version, j.stream_log_path, j.prompt_digest
+      FROM jobs j
+      WHERE j.status = 'completed' AND j.intended_engine = 'native-v2' AND j.observed_engine = 'native-v2'
+        AND j.command_type != 'review_gate'
+        AND j.operation_kind IN ('ask', 'review', 'challenge', 'rescue', 'pursue', 'swarm', 'swarm-write')
+        AND j.kimi_session_id IS NOT NULL AND length(trim(j.kimi_session_id)) > 0
+        AND j.kimi_version IS NOT NULL
+        ${repoId === undefined ? "" : "AND j.repo_id = ?"}
+        AND NOT EXISTS (SELECT 1 FROM jobs active WHERE active.kimi_session_id = j.kimi_session_id AND active.status = 'running')
+      ORDER BY j.updated_at DESC, j.job_id DESC LIMIT ${MAX_JOBS + 1}
+    `).all(...(repoId === undefined ? [] : [repoId]));
+        if (rows.length > MAX_JOBS) {
+            throw new RuntimeError("SESSION_REPAIR_LIMIT", `More than ${MAX_JOBS} eligible jobs; narrow the repair to one repository.`, "repair-sessions.store");
+        }
+        return rows;
+    }
+    finally {
+        db.close();
+    }
+}
+async function readVerifiedPrompt(job, logsDir, worktreesDir) {
+    // All plugin stream logs are direct children. Refuse nested/escaped paths,
+    // symlinks and special files; opening nonblocking avoids FIFO hangs.
+    if (!path.isAbsolute(job.stream_log_path) || path.dirname(job.stream_log_path) !== logsDir)
+        return undefined;
+    try {
+        const root = await lstat(logsDir);
+        if (!root.isDirectory() || root.isSymbolicLink())
+            return undefined;
+        const file = await open(job.stream_log_path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stats = await file.stat();
+            if (!stats.isFile())
+                return undefined;
+            const buffer = Buffer.alloc(MAX_SPAWN_BYTES + 1);
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+            const prefix = buffer.subarray(0, bytesRead).toString("utf8");
+            const lines = prefix.split("\n");
+            // A prefix cut mid-record must never be treated as a complete JSON line.
+            if (bytesRead > MAX_SPAWN_BYTES)
+                lines.pop();
+            for (const line of lines.slice(0, 32)) {
+                if (!line.trim())
+                    continue;
+                const record = JSON.parse(line);
+                if (record.event !== "spawn") {
+                    if (record.direction === "meta")
+                        continue;
+                    return undefined;
+                }
+                const expectedCwd = job.operation_kind === "swarm-write"
+                    ? path.join(worktreesDir, job.repo_id, `swarm-write-${job.job_id}`)
+                    : job.cwd;
+                if (record.intended_engine !== "native-v2" || record.kimi_version !== job.kimi_version ||
+                    record.operation_kind !== job.operation_kind || record.cwd !== expectedCwd)
+                    return undefined;
+                if (!Array.isArray(record.args) || record.args.length < 2)
+                    return undefined;
+                const args = record.args;
+                const prompt = args[args.length - 1];
+                if (args[args.length - 2] !== "-p" || typeof prompt !== "string" || !prompt.trim())
+                    return undefined;
+                return digestPrompt(prompt) === job.prompt_digest ? prompt : undefined;
+            }
+            return undefined;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}

package/plugins/kimi-dsh/dist/commands/replay.js

@@ -0,0 +1,124 @@
+import { REPLAY_SUPPORTED_FLAGS } from "../parsing.js";
+import { access, stat, readFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { RuntimeError } from "../errors.js";
+import { resolveRepoIdentity } from "../git.js";
+import { withJobStore } from "../job-store.js";
+import { ensurePluginPaths, resolvePluginPaths } from "../paths.js";
+import { renderManagedJobOutput } from "../render.js";
+import { sweepStaleJobs } from "../jobs.js";
+const MAX_REPLAY_LOG_BYTES = 32 * 1024 * 1024;
+export async function runReplay(argv, context) {
+    const [jobId, ...rest] = argv;
+    if (!jobId || jobId.startsWith("-") || rest.length > 0) {
+        throw new RuntimeError("INVALID_ARGS", `replay expects exactly one job id: replay <job-id>. Supported flags: ${REPLAY_SUPPORTED_FLAGS}.`, "replay.parse");
+    }
+    const paths = resolvePluginPaths(context.env);
+    await ensurePluginPaths(paths);
+    const repoIdentity = await resolveRepoIdentity(context.cwd);
+    return withJobStore(paths, async (store) => {
+        await sweepStaleJobs(store, paths);
+        const job = store.getJob(jobId);
+        if (!job || job.repo_id !== repoIdentity.repoId) {
+            throw new RuntimeError("JOB_NOT_FOUND", `No job matched ${jobId} for replay.`, "replay.lookup");
+        }
+        const replayed = await replayJob(job);
+        return `${replayed.rendered}${replayed.rendered.endsWith("\n") ? "" : "\n"}`;
+    });
+}
+export async function replayJob(job) {
+    if (!job.stream_log_path) {
+        throw new RuntimeError("REPLAY_LOG_MISSING", `Job ${job.job_id} does not have a stored stream log path to replay.`, "replay.lookup");
+    }
+    try {
+        await access(job.stream_log_path, fsConstants.R_OK);
+    }
+    catch {
+        throw new RuntimeError("REPLAY_LOG_MISSING", `Job ${job.job_id} cannot be replayed because ${job.stream_log_path} is missing.`, "replay.lookup");
+    }
+    const stats = await stat(job.stream_log_path);
+    if (stats.size > MAX_REPLAY_LOG_BYTES) {
+        throw new RuntimeError("REPLAY_LOG_TOO_LARGE", `Job ${job.job_id} stream log is ${stats.size} bytes, which exceeds the ${MAX_REPLAY_LOG_BYTES}-byte replay ceiling.`, "replay.lookup");
+    }
+    const finalText = await replayFinalText(job.stream_log_path);
+    const rendered = renderManagedJobOutput(job, finalText);
+    return {
+        rendered: rendered.rendered,
+        output: rendered.output,
+        summary: rendered.summary,
+    };
+}
+async function replayFinalText(logPath) {
+    const contents = await readFile(logPath, "utf8");
+    const rawLines = contents.split("\n");
+    let sawSpawn = false;
+    let sawExit = false;
+    let sawV1Event = false;
+    let sawV04Direction = false;
+    let assistantContent = "";
+    for (let lineNumber = 0; lineNumber < rawLines.length; lineNumber += 1) {
+        const line = rawLines[lineNumber].trim();
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch (error) {
+            // A truncated trailing line is the expected shape when a worker
+            // was SIGKILL'd mid-write. Drop it silently so replay still works
+            // on the consistent prefix.
+            if (lineNumber === rawLines.length - 1)
+                continue;
+            throw new RuntimeError("REPLAY_LOG_INVALID", `Stream log ${logPath}:${lineNumber + 1} is malformed JSON: ${error.message}`, "replay.log", { cause: error });
+        }
+        if (typeof entry.event === "string")
+            sawV1Event = true;
+        if (Object.prototype.hasOwnProperty.call(entry, "direction"))
+            sawV04Direction = true;
+        const event = typeof entry.event === "string" ? entry.event : "";
+        switch (event) {
+            case "spawn":
+                sawSpawn = true;
+                break;
+            case "record": {
+                const record = entry.record;
+                if (typeof record !== "object" || record === null || Array.isArray(record)) {
+                    throw new RuntimeError("REPLAY_LOG_INVALID", `Stream log ${logPath}:${lineNumber + 1} record entry is not an object.`, "replay.log");
+                }
+                const role = record.role;
+                const content = record.content;
+                if (role === "assistant" && typeof content === "string") {
+                    assistantContent += content;
+                }
+                // Non-string content (null/undefined/object) silently skipped —
+                // these are diagnostic-only records we don't render.
+                break;
+            }
+            case "exit":
+                sawExit = true;
+                break;
+            case "process_error": {
+                const detail = typeof entry.message === "string" ? entry.message : "<unknown>";
+                throw new RuntimeError("REPLAY_LOG_PROCESS_ERROR", `Stream log ${logPath} captured a subprocess error and cannot be replayed: ${detail}`, "replay.log", { details: { logPath, line: lineNumber + 1 } });
+            }
+            default:
+                // Unknown / malformed-line / future events are diagnostics — skip.
+                break;
+        }
+    }
+    if (!sawSpawn) {
+        // Differentiate "this is a v0.4 wire log" from "this is a v1.0 log
+        // that died before reaching the spawn event". v0.4 logs had a
+        // `direction` field on every entry (out/in/meta/stderr); v1.0 logs
+        // use `event` instead.
+        if (sawV04Direction && !sawV1Event) {
+            throw new RuntimeError("REPLAY_LOG_UNREADABLE", `Stream log ${logPath} is a v0.4 wire log (no \`event\` key). v0.4 wire logs are not supported by the v1.0 replay command.`, "replay.log", { details: { logPath } });
+        }
+        throw new RuntimeError("REPLAY_LOG_NO_SPAWN", `Stream log ${logPath} contains no spawn event — the worker likely failed before launching kimi (e.g., synchronous spawn failure, early cancellation). No assistant content to replay.`, "replay.log", { details: { logPath } });
+    }
+    if (!sawExit && assistantContent.length === 0) {
+        throw new RuntimeError("REPLAY_LOG_INVALID", `Stream log ${logPath} did not capture any assistant content before truncation.`, "replay.log", { details: { logPath } });
+    }
+    return assistantContent;
+}