kimi-plugin-cc 2.0.7 → 2.2.0

package/dist/commands/cli-helpers.js

@@ -1,4 +1,9 @@
 import { RuntimeError } from "../errors.js";
+import { ResponseTimeoutError } from "../cli-client.js";
+import { observedExecutionFields } from "../kimi-engine.js";
+import { resolveKimiHome } from "../kimi-home.js";
+import { recoverSessionIdFromStore } from "../session-recovery.js";
+import { formatBudgetDuration } from "../render.js";
 /**
  * Reassemble prose final text from cli-client records.
  *
@@ -110,3 +115,78 @@ export function assertCliResultSuccess(result, stage) {
         });
     }
 }
+/** Timeout-only capture. Cancellation takes precedence, including while the
+ * asynchronous store scan is in flight. No title sync on failure. */
+export async function captureTimeoutPartialOutput(classified, store, job, env, cancellationSignal) {
+    if (cancellationSignal?.aborted)
+        return undefined;
+    const timeout = classified.cause;
+    if (!(timeout instanceof ResponseTimeoutError) || !timeout.partialResult)
+        return undefined;
+    const result = timeout.partialResult;
+    let sessionId = result.sessionId;
+    let source = sessionId ? "announced" : null;
+    const details = classified instanceof RuntimeError ? classified.details : timeout.details;
+    details.kimi_session_id_source = job.kimi_session_id_source;
+    // The persisted plan is plugin-owned. Recovery never runs on cancellation,
+    // v1, successful turns, teardown rejection, or an already-known resume id.
+    if (!sessionId && !job.kimi_session_id && job.intended_engine === "native-v2") {
+        // Without the system.version marker the row has no proven engine, and
+        // resume would refuse the id as lineage-unknown; do not advertise one.
+        if (result.observedEngine === null) {
+            details.session_recovery = "engine_unobserved";
+        }
+        else {
+            const recovered = await recoverSessionIdFromStore({
+                kimiHome: resolveKimiHome(env, job.cwd), cwd: job.cwd,
+                spawnedAt: result.spawnedAt, settledAt: result.settledAt, promptDigest: job.prompt_digest,
+                store, jobId: job.job_id,
+            });
+            sessionId = recovered.sessionId;
+            if (sessionId)
+                source = "recovered_session_dir";
+            else
+                details.session_recovery = recovered.reason;
+        }
+    }
+    if (cancellationSignal?.aborted)
+        return undefined;
+    // Best-effort metadata only. The row is still `running`, and a session id
+    // written here can collide with `jobs_running_session_idx` when a resume of
+    // the same session was started while this job ran. A store error must never
+    // prevent markJobFailed from running — the partial artifact matters more
+    // than the metadata, so swallow and fall through.
+    try {
+        store.updateRunningJob(job.job_id, observedExecutionFields(result));
+        if (sessionId) {
+            const updated = source === "recovered_session_dir"
+                ? store.claimRecoveredSessionId(job.job_id, sessionId)
+                : store.updateRunningJob(job.job_id, { kimi_session_id: sessionId, kimi_session_id_source: source });
+            if (updated?.kimi_session_id === sessionId && updated.kimi_session_id_source === source) {
+                details.kimi_session_id = sessionId;
+                details.kimi_session_id_source = source;
+            }
+            else
+                details[source === "recovered_session_dir" ? "session_recovery" : "session_id_persistence"] = "persistence_failed";
+        }
+    }
+    catch {
+        // `session_recovery` describes only the recovery branch; an announced id or
+        // the provenance update failing is a different fact.
+        details[source === "recovered_session_dir" ? "session_recovery" : "session_id_persistence"] = "persistence_failed";
+        // Diagnostics stay in the stream log; the failure transition proceeds.
+    }
+    return {
+        text: reassembleProseFromRecords(result.records),
+        toolCalls: result.records.some((record) => record.role === "tool" ||
+            (record.role === "assistant" && Array.isArray(record.tool_calls) &&
+                record.tool_calls.length > 0)),
+        recordCount: result.records.length,
+        budgetMs: timeout.details.budget_ms,
+    };
+}
+export function warnInheritedBudget(job, stderr) {
+    if (job.budget_source === "inherited" && job.budget_ms !== null) {
+        stderr.write(`[${job.command_type}] budget ${formatBudgetDuration(job.budget_ms)} inherited from job ${job.resumed_from_job_id}; pass --budget to override\n`);
+    }
+}

package/dist/commands/pursue.js

@@ -143,6 +143,8 @@ export async function runPursue(argv, context) {
             model: parsed.model ?? null,
             thinking: parsed.thinking ?? null,
             background: false,
+            budget_ms: parsed.budgetMs ?? KIMI_PURSUE_DEFAULT_BUDGET_MS,
+            budget_source: parsed.budgetMs !== undefined ? "explicit" : "default",
             pid: process.pid,
             kimi_pid: null,
             status: "running",
@@ -168,7 +170,7 @@ export async function runPursue(argv, context) {
             await markJobFailed(store, paths, job, classified, "Pursue failed.", { phase: "failed" });
             throw classified;
         }
-        const completed = await executePursueJob(job.job_id, prompt, objective, parsed.budgetMs ?? KIMI_PURSUE_DEFAULT_BUDGET_MS, context);
+        const completed = await executePursueJob(job.job_id, prompt, objective, job.budget_ms, context);
         if (!completed.final_output_path) {
             throw new RuntimeError("PURSUE_RESULT_MISSING", "Pursue finished without a rendered result.", "pursue.result");
         }
@@ -249,7 +251,7 @@ async function executePursueJob(jobId, prompt, objective, budgetMs, context) {
         if (result.sessionId !== undefined &&
             result.sessionId.length > 0 &&
             result.sessionId !== job.kimi_session_id) {
-            store.updateRunningJob(job.job_id, { kimi_session_id: result.sessionId });
+            store.updateRunningJob(job.job_id, { kimi_session_id_source: "announced", kimi_session_id: result.sessionId });
         }
         await syncKimiSessionTitle({
             promptText: objective,

package/dist/commands/repair-sessions.js

@@ -1,3 +1,4 @@
+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";
@@ -15,7 +16,7 @@ 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 [--apply] [--all]", "repair-sessions.args");
+            throw new RuntimeError("INVALID_ARGS", `Usage: repair-sessions. Supported flags: ${REPAIR_SESSIONS_SUPPORTED_FLAGS}.`, "repair-sessions.args");
         }
         seen.add(arg);
     }

package/dist/commands/replay.js

@@ -1,3 +1,4 @@
+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";
@@ -9,8 +10,8 @@ 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 || rest.length > 0) {
-        throw new RuntimeError("INVALID_ARGS", "replay expects exactly one job id: replay <job-id>.", "replay.parse");
+    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);

package/dist/commands/rescue.js

@@ -1,3 +1,4 @@
+import { companionHelp } from "../help.js";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { createCliCancellationHandlers } from "../cli-cancellation.js";
@@ -16,7 +17,7 @@ import { parseRescueArgs } from "../parsing.js";
 import { readArtifact, renderManagedJobOutput, writeArtifact } from "../render.js";
 import { startBackgroundJob } from "../background-spawn.js";
 import { hookRefusalDetails, hookRefusalRetryProtocol, maybeWarnHookMissing, verifyHookInstalled, } from "../hooks/install.js";
-import { assertCliResultSuccess, reassembleProseFromRecords, warnIfSessionIdMissing } from "./cli-helpers.js";
+import { warnInheritedBudget, captureTimeoutPartialOutput, assertCliResultSuccess, reassembleProseFromRecords, warnIfSessionIdMissing } from "./cli-helpers.js";
 import { buildKimiSessionTitle, syncKimiSessionTitle } from "../session-title.js";
 export { describeMissingResult } from "../background-spawn.js";
 // v1.0 cutover note (PR 3):
@@ -41,6 +42,8 @@ const RESCUE_SUMMARY_MAX = 120;
 const RESCUE_AGENT_PROFILE_PLACEHOLDER = "<cli-client>";
 export async function runRescue(argv, context) {
     const parsed = parseRescueArgs(argv);
+    if (parsed.help)
+        return companionHelp(["task", "rescue", ...argv]);
     const paths = resolvePluginPaths(context.env);
     await ensurePluginPaths(paths);
     const repoIdentity = await resolveRepoIdentity(context.cwd);
@@ -68,10 +71,14 @@ export async function runRescue(argv, context) {
             model: parsed.model ?? null,
             thinking: parsed.thinking ?? null,
             background: parsed.background,
+            budget_ms: parsed.budgetMs ?? (sessionResolution.sourceJob?.operation_kind === "rescue" ? sessionResolution.sourceJob.budget_ms : null) ?? null,
+            budget_source: parsed.budgetMs !== undefined ? "explicit"
+                : sessionResolution.sourceJob?.operation_kind === "rescue" && sessionResolution.sourceJob.budget_ms !== null ? "inherited" : "default",
             pid: parsed.background ? null : process.pid,
             kimi_pid: null,
             status: "running",
             kimi_session_id: sessionResolution.kimiSessionId,
+            kimi_session_id_source: sessionResolution.sourceJob?.kimi_session_id_source ?? null,
             ...persistedExecutionPlanFields(executionPlan),
             agent_profile: RESCUE_AGENT_PROFILE_PLACEHOLDER,
             prompt_digest: digestPrompt(prompt),
@@ -93,6 +100,7 @@ export async function runRescue(argv, context) {
             await markJobFailed(store, paths, job, classified, rescueConfig.cancellation.failedSummary, { phase: "failed" });
             throw classified;
         }
+        warnInheritedBudget(job, context.stderr);
         if (parsed.background) {
             return startBackgroundJob(job, prompt, context, paths, {
                 workerKind: "rescue",
@@ -185,18 +193,17 @@ export async function executeRescueJob(jobId, prompt, context, options) {
             signal: handlers.signal,
             // SIGKILL escalation defaults to 1500ms inside cli-client —
             // matches v0.4's cancellation.ts behavior for the wire client.
-        }, KIMI_RESCUE_PROMPT_TIMEOUT_MS, "rescue.prompt");
+        }, job.budget_ms ?? KIMI_RESCUE_PROMPT_TIMEOUT_MS, "rescue.prompt");
         store.updateRunningJob(job.job_id, observedExecutionFields(result));
         if (handlers.cancelling) {
             throw new RuntimeError(cancel.errorCodes.cancelled, cancel.cancelMessages.afterPrompt, "rescue.runtime");
         }
         assertCliResultSuccess(result, "rescue.runtime");
         if (result.sessionId !== undefined &&
-            result.sessionId.length > 0 &&
-            result.sessionId !== job.kimi_session_id) {
+            result.sessionId.length > 0) {
             // length>0 guard: empty-string capture would poison the row. (Kimi
             // alpha.4 challenge finding #3.)
-            store.updateRunningJob(job.job_id, { kimi_session_id: result.sessionId });
+            store.updateRunningJob(job.job_id, { kimi_session_id_source: "announced", kimi_session_id: result.sessionId });
         }
         await syncKimiSessionTitle({
             promptText: prompt,
@@ -242,14 +249,17 @@ export async function executeRescueJob(jobId, prompt, context, options) {
         }) ?? job);
     }
     catch (error) {
+        const classified = classifyManagedCommandFailure(error, "rescue", job.job_id, {
+            preserveStage: true,
+            background: job.background,
+            budgetMs: job.budget_ms ?? KIMI_RESCUE_PROMPT_TIMEOUT_MS,
+        });
+        const partialOutput = await captureTimeoutPartialOutput(classified, store, job, context.env, handlers.signal);
         if (handlers.cancelling) {
             const cancelledError = new RuntimeError(cancel.errorCodes.cancelled, cancel.cancelMessages.default, "rescue.runtime", error instanceof Error ? { cause: error } : undefined);
             return await markJobCancelled(store, paths, job, cancel.cancelledSummary, cancelledError, { phase: "cancelled" });
         }
-        const classified = classifyManagedCommandFailure(error, "rescue", job.job_id, {
-            preserveStage: true,
-        });
-        return await markJobFailed(store, paths, job, classified, cancel.failedSummary, { phase: "failed" });
+        return await markJobFailed(store, paths, job, classified, cancel.failedSummary, { phase: "failed", partialOutput });
     }
     finally {
         handlers.dispose();

package/dist/commands/result.js

@@ -2,7 +2,7 @@ import { RuntimeError } from "../errors.js";
 import { resolveRepoIdentity } from "../git.js";
 import { sweepStaleJobs } from "../jobs.js";
 import { reconcileHistoricalJobProvenance } from "../kimi-engine.js";
-import { withJobStore } from "../job-store.js";
+import { renderBudgetSource, withJobStore } from "../job-store.js";
 import { ensurePluginPaths, resolvePluginPaths } from "../paths.js";
 import { parseJobLookupArgs } from "../parsing.js";
 import { readArtifact, renderTerminalJobArtifact } from "../render.js";
@@ -42,6 +42,12 @@ function renderResultEnvelope(job, artifactPath, body) {
         job_id: job.job_id,
         kind: job.command_type,
         status: job.status,
+        budget_ms: job.budget_ms,
+        budget_source: renderBudgetSource(job),
+        kimi_session_id_source: job.kimi_session_id_source,
+        kimi_session_id: job.kimi_session_id,
+        // True when a budget timeout preserved assistant prose in the artifact.
+        partial_output: job.status === "failed" && Number(job.error?.details?.partial_output_chars ?? 0) > 0,
         summary: job.summary,
         error: job.error,
         artifact_path: artifactPath,

package/dist/commands/review-gate.js

@@ -153,6 +153,7 @@ async function executeReviewGate(payload, assistantMessage, context) {
             kimi_pid: null,
             status: "running",
             kimi_session_id: null,
+            budget_source: "default",
             ...persistedExecutionPlanFields(executionPlan),
             agent_profile: REVIEW_GATE_AGENT_PROFILE_PLACEHOLDER,
             prompt_digest: digestPrompt(prompt),
@@ -195,7 +196,7 @@ async function executeReviewGate(payload, assistantMessage, context) {
                 // can't synthesize empty strings today, but the guard locks the
                 // SQLite contract independent of upstream behavior).
                 activeStore.updateRunningJob(job.job_id, {
-                    kimi_session_id: result.sessionId,
+                    kimi_session_id_source: "announced", kimi_session_id: result.sessionId,
                 });
             }
             const finalText = reassembleProseFromRecords(result.records);

package/dist/commands/review.js

@@ -17,7 +17,7 @@ import { renderManagedJobOutput, writeArtifact } from "../render.js";
 import { RuntimeError } from "../errors.js";
 import { resolveRepoIdentity } from "../git.js";
 import { hookRefusalDetails, hookRefusalRetryProtocol, maybeWarnHookMissing, verifyHookInstalled, } from "../hooks/install.js";
-import { assertCliResultSuccess, reassembleProseFromRecords, warnIfSessionIdMissing } from "./cli-helpers.js";
+import { captureTimeoutPartialOutput, assertCliResultSuccess, reassembleProseFromRecords, warnIfSessionIdMissing } from "./cli-helpers.js";
 import { buildKimiSessionTitle, syncKimiSessionTitle } from "../session-title.js";
 // v1.0 cutover note (PR 2):
 //
@@ -81,6 +81,8 @@ export async function runReview(argv, context, commandType) {
         model: parsed.model ?? null,
         thinking: parsed.thinking ?? null,
         background: false,
+        budget_ms: parsed.budgetMs ?? null,
+        budget_source: parsed.budgetMs !== undefined ? "explicit" : "default",
         pid: process.pid,
         kimi_pid: null,
         status: "running",
@@ -113,7 +115,7 @@ export async function runReview(argv, context, commandType) {
             model: parsed.model,
             logPath,
             signal: handlers.signal,
-        }, KIMI_REVIEW_PROMPT_TIMEOUT_MS, `${commandType}.prompt`);
+        }, job.budget_ms ?? KIMI_REVIEW_PROMPT_TIMEOUT_MS, `${commandType}.prompt`);
         store.updateRunningJob(job.job_id, observedExecutionFields(result));
         if (handlers.cancelling) {
             throw new RuntimeError(cancel.errorCodes.cancelled, cancel.cancelMessages.afterPrompt, `${commandType}.runtime`);
@@ -127,7 +129,7 @@ export async function runReview(argv, context, commandType) {
             // poison the row — consumers reading SQLite distinguish "missing"
             // (NULL) from "captured" (non-empty UUID) only via NULL-ness.
             // (Kimi alpha.4 challenge finding #3.)
-            store.updateRunningJob(job.job_id, { kimi_session_id: result.sessionId });
+            store.updateRunningJob(job.job_id, { kimi_session_id_source: "announced", kimi_session_id: result.sessionId });
         }
         await syncKimiSessionTitle({
             promptText: previewPrompt,
@@ -158,13 +160,14 @@ export async function runReview(argv, context, commandType) {
         return rendered.output;
     }
     catch (error) {
+        const classified = classifyManagedCommandFailure(error, commandType, job.job_id, { background: job.background, budgetMs: job.budget_ms ?? KIMI_REVIEW_PROMPT_TIMEOUT_MS });
+        const partialOutput = await captureTimeoutPartialOutput(classified, store, job, context.env, handlers.signal);
         if (handlers.cancelling) {
             const cancelledError = new RuntimeError(cancel.errorCodes.cancelled, cancel.cancelMessages.default, `${commandType}.runtime`, error instanceof Error ? { cause: error } : undefined);
             await markJobCancelled(store, paths, job, cancel.cancelledSummary, cancelledError);
             throw cancelledError;
         }
-        const classified = classifyManagedCommandFailure(error, commandType, job.job_id);
-        await markJobFailed(store, paths, job, classified, cancel.failedSummary);
+        await markJobFailed(store, paths, job, classified, cancel.failedSummary, { partialOutput });
         throw classified;
     }
     finally {

package/dist/commands/setup.js

@@ -1,3 +1,4 @@
+import { SETUP_SUPPORTED_FLAGS } from "../parsing.js";
 // Managed-block installer for the kimi-code PreToolUse hook.
 //
 // Replaces the v0.4 Wire-based setup probe. In v1.0 the load-bearing
@@ -127,7 +128,7 @@ function parseArgs(argv) {
                 disableReviewGate = true;
                 break;
             default:
-                throw new RuntimeError("INVALID_ARGS", `Unknown setup flag ${token}. Supported flags: --check, --uninstall, --all (with --uninstall), --enable-review-gate, --disable-review-gate.`, "setup.parse");
+                throw new RuntimeError("INVALID_ARGS", `Unknown setup flag ${token}. Supported flags: ${SETUP_SUPPORTED_FLAGS}.`, "setup.parse");
         }
     }
     if (enableReviewGate && disableReviewGate) {

package/dist/commands/status.js

@@ -2,7 +2,7 @@ import { RuntimeError } from "../errors.js";
 import { resolveRepoIdentity } from "../git.js";
 import { sweepStaleJobs } from "../jobs.js";
 import { reconcileHistoricalJobProvenance } from "../kimi-engine.js";
-import { withJobStore } from "../job-store.js";
+import { renderBudgetSource, withJobStore } from "../job-store.js";
 import { ensurePluginPaths, resolvePluginPaths } from "../paths.js";
 import { parseJobLookupArgs } from "../parsing.js";
 export async function runStatus(argv, context) {
@@ -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, null, 2)}\n`;
+        return `${JSON.stringify({ ...job, budget_source: renderBudgetSource(job) }, null, 2)}\n`;
     });
 }

package/dist/commands/swarm.js

@@ -210,6 +210,8 @@ async function runReadSwarm(parsed, objective, context) {
             model: parsed.model ?? null,
             thinking: parsed.thinking ?? null,
             background: false,
+            budget_ms: parsed.budgetMs ?? KIMI_SWARM_DEFAULT_BUDGET_MS,
+            budget_source: parsed.budgetMs !== undefined ? "explicit" : "default",
             pid: process.pid,
             kimi_pid: null,
             status: "running",
@@ -235,7 +237,7 @@ async function runReadSwarm(parsed, objective, context) {
             await markJobFailed(store, paths, job, classified, "Swarm failed.", { phase: "failed" });
             throw classified;
         }
-        const completed = await executeSwarmJob(job.job_id, prompt, objective, parsed.budgetMs ?? KIMI_SWARM_DEFAULT_BUDGET_MS, resolveSwarmMaxConcurrency(parsed.maxConcurrency), context);
+        const completed = await executeSwarmJob(job.job_id, prompt, objective, job.budget_ms, resolveSwarmMaxConcurrency(parsed.maxConcurrency), context);
         if (!completed.final_output_path) {
             throw new RuntimeError("SWARM_RESULT_MISSING", "Swarm finished without a rendered result.", "swarm.result");
         }
@@ -308,6 +310,8 @@ async function runWriteSwarm(parsed, objective, context) {
                 model: parsed.model ?? null,
                 thinking: parsed.thinking ?? null,
                 background: false,
+                budget_ms: parsed.budgetMs ?? KIMI_SWARM_DEFAULT_BUDGET_MS,
+                budget_source: parsed.budgetMs !== undefined ? "explicit" : "default",
                 pid: process.pid,
                 kimi_pid: null,
                 status: "running",
@@ -335,7 +339,7 @@ async function runWriteSwarm(parsed, objective, context) {
                 });
                 throw classified;
             }
-            const completed = await executeSwarmJob(job.job_id, prompt, objective, parsed.budgetMs ?? KIMI_SWARM_DEFAULT_BUDGET_MS, resolveSwarmWriteMaxConcurrency(parsed.maxConcurrency), context, { spawnCwd: worktreePath, workspaceRoot: worktreePath });
+            const completed = await executeSwarmJob(job.job_id, prompt, objective, job.budget_ms, resolveSwarmWriteMaxConcurrency(parsed.maxConcurrency), context, { spawnCwd: worktreePath, workspaceRoot: worktreePath });
             if (!completed.final_output_path) {
                 throw new RuntimeError("SWARM_RESULT_MISSING", "Swarm (write) finished without a rendered result.", "swarm.result");
             }
@@ -500,7 +504,7 @@ writeMode) {
         if (result.sessionId !== undefined &&
             result.sessionId.length > 0 &&
             result.sessionId !== job.kimi_session_id) {
-            store.updateRunningJob(job.job_id, { kimi_session_id: result.sessionId });
+            store.updateRunningJob(job.job_id, { kimi_session_id_source: "announced", kimi_session_id: result.sessionId });
         }
         await syncKimiSessionTitle({
             promptText: objective,

package/dist/companion.js

@@ -1,3 +1,4 @@
+import { companionHelp } from "./help.js";
 import { runAsk } from "./commands/ask.js";
 import { runModelInventory } from "./commands/models.js";
 import { runCancel } from "./commands/cancel.js";
@@ -15,6 +16,11 @@ import { runWorker } from "./commands/worker.js";
 import { formatError, RuntimeError } from "./errors.js";
 import { resolveKimiHome } from "./kimi-home.js";
 async function main(argv) {
+    const help = companionHelp(argv);
+    if (help !== undefined) {
+        process.stdout.write(`${help}\n`);
+        return;
+    }
     const [command, ...rest] = argv;
     const cwd = process.env.KIMI_PLUGIN_CC_WORKSPACE_CWD || process.cwd();
     const context = {

package/dist/help.js

@@ -0,0 +1,40 @@
+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";
+const TASK_KINDS = "rescue, challenge, pursue, swarm";
+/** Help is a dispatch-only, side-effect-free exception to normal argument parsing. */
+export function companionHelp(argv) {
+    const [command, kind] = argv;
+    // Scan only the argument region: the subcommand (and a task kind) are
+    // positional names, not prose, so they must not end the flag region.
+    const argumentStart = command === "--help" || command === "-h" ? 0
+        : command === "task" && kind !== undefined && !kind.startsWith("-") ? 2
+            : 1;
+    if (!hasHelpFlag(argv.slice(argumentStart)))
+        return undefined;
+    const suffix = " Use --help or -h among the leading flags (before any prompt text or --) to show this usage.";
+    const usage = (name, positionals, flags, description) => `Usage: companion.sh ${name}${positionals ? ` ${positionals}` : ""}. ${description} Supported flags: ${flags}.${suffix}`;
+    switch (command) {
+        case "--help":
+        case "-h":
+            return `Usage: companion.sh <subcommand> [arguments]. Subcommands: ${SUBCOMMANDS}. Use <subcommand> --help for usage.`;
+        case "task":
+            switch (kind) {
+                case "rescue": return usage("task rescue", "[options] [--] <task>", RESCUE_SUPPORTED_FLAGS, "Write-capable task; default budget 45m. Backgrounding does not extend the budget.");
+                case "challenge": return usage("task challenge", "[options] [--] [focus]", REVIEW_SUPPORTED_FLAGS, "Read-only challenge; default budget 30m. Foreground-only (no --background/--wait).");
+                case "pursue": return usage("task pursue", "[options] [--] <objective>", PURSUE_SUPPORTED_FLAGS, "Autonomous goal; default budget 45m. Runtime foreground-only.");
+                case "swarm": return usage("task swarm", "[options] [--] <objective>", SWARM_SUPPORTED_FLAGS, "Parallel task; default budget 30m. Runtime foreground-only; --write produces a patch.");
+                default: return `Usage: companion.sh task <kind> [arguments]. Task kinds: ${TASK_KINDS}. Use task <kind> --help for usage.`;
+            }
+        case "ask": return usage(command, "[options] [--] [prompt]", ASK_SUPPORTED_FLAGS, "Read-only question; default budget 30m. Backgrounding does not extend the budget.");
+        case "review": return usage(command, "[options] [--] [focus]", REVIEW_SUPPORTED_FLAGS, "Read-only review; default budget 30m. Foreground-only (no --background/--wait).");
+        case "setup": return usage(command, "[options]", SETUP_SUPPORTED_FLAGS, "Install, check, or remove this host's managed hook, or list configured models.");
+        case "status":
+        case "result":
+        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 "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.";
+        default: return undefined;
+    }
+}

package/dist/hooks/config-safety.js

@@ -417,15 +417,23 @@ export function normalizeTopLevelInlineHooks(contents, lineEnding) {
         entryCount: hooks.length,
     };
 }
+// Same defaults as smol-toml 1.9.1 parse(); this walker only locates assignments.
+// tests/runtime/toml-walker-context.test.ts asserts these against the vendored parse().
+export function assignmentParseContext(s) {
+    return { s, p: s.charCodeAt(0) === 0xfeff ? 1 : 0, d: 1_000, bi: false, ld: true, uk: 0 };
+}
 function findTopLevelHooksAssignment(contents) {
-    let ptr = skipVoid(contents, 0);
-    while (ptr < contents.length) {
+    const ctx = assignmentParseContext(contents);
+    skipVoid(ctx);
+    while (ctx.p < contents.length) {
         // A root-level direct assignment cannot resume after entering a table.
-        if (contents[ptr] === "[")
+        if (contents[ctx.p] === "[")
             return null;
-        const declarationStart = ptr;
-        const [key, valueStart] = parseKey(contents, ptr);
-        const [, valueEnd] = extractValue(contents, valueStart, undefined, 1_000, undefined);
+        const declarationStart = ctx.p;
+        const key = parseKey(ctx);
+        skipVoid(ctx, true, true);
+        extractValue(ctx, undefined);
+        const valueEnd = ctx.p;
         if (key.length === 1 && key[0] === "hooks") {
             const lineStart = contents.lastIndexOf("\n", declarationStart - 1) + 1;
             const start = /^[\t ]*$/.test(contents.slice(lineStart, declarationStart))
@@ -445,7 +453,7 @@ function findTopLevelHooksAssignment(contents) {
             }
             return { start, end, hadLineEnding };
         }
-        ptr = skipVoid(contents, valueEnd);
+        skipVoid(ctx);
     }
     return null;
 }
@@ -585,14 +593,15 @@ function validateVersionSensitiveEvents(events, version) {
         return invalidHookSet(`version-sensitive event ${JSON.stringify(first.event)} requires a verified kimi-code version`, first.entry, first.line);
     }
     // Exact schemas reviewed at 2.0.0 (1b89e4b0), 2.0.1 (caf7d4e2),
-    // 2.0.2 (9d07f634), 2.1.0 (52437299), and 2.1.1 (f67e6398):
+    // 2.0.2 (9d07f634), 2.1.0 (52437299), 2.1.1 (f67e6398) and 2.2.0 (472192c3):
     // the additive events and HookDefSchema are unchanged. Require the full
     // version string AND matching components; no inferred 2.x compatibility.
     if (version.major === 2 && ((version.minor === 0 && ((version.version === "2.0.0" && version.patch === 0) ||
         (version.version === "2.0.1" && version.patch === 1) ||
         (version.version === "2.0.2" && version.patch === 2))) ||
         (version.minor === 1 && ((version.version === "2.1.0" && version.patch === 0) ||
-            (version.version === "2.1.1" && version.patch === 1))))) {
+            (version.version === "2.1.1" && version.patch === 1))) ||
+        (version.minor === 2 && ((version.version === "2.2.0" && version.patch === 0))))) {
         return { valid: true };
     }
     if (version.major !== 0) {