kimi-plugin-cc 2.0.7 → 2.2.0

package/plugins/kimi-codex/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/plugins/kimi-codex/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) {

package/plugins/kimi-codex/dist/job-store.js

@@ -11,8 +11,11 @@ export class JobStore {
         let db;
         try {
             db = createSqliteAdapter(paths.stateDbPath);
-            db.pragma("journal_mode = WAL");
+            // busy_timeout FIRST: switching the journal mode takes a brief write lock,
+            // and a second opener (status/result racing a worker) otherwise fails
+            // immediately with SQLITE_BUSY instead of waiting (seen 2026-10-14).
             db.pragma("busy_timeout = 5000");
+            db.pragma("journal_mode = WAL");
         }
         catch (error) {
             try {
@@ -58,6 +61,7 @@ export class JobStore {
         prompt_digest TEXT NOT NULL,
         summary TEXT NOT NULL,
         phase TEXT,
+        budget_ms INTEGER,
         final_output_path TEXT,
         stream_log_path TEXT NOT NULL,
         error TEXT
@@ -66,6 +70,14 @@ export class JobStore {
             if (!tableHasColumn(this.db, "phase")) {
                 this.db.exec(`ALTER TABLE jobs ADD COLUMN phase TEXT;`);
             }
+            if (!tableHasColumn(this.db, "budget_ms")) {
+                this.db.exec(`ALTER TABLE jobs ADD COLUMN budget_ms INTEGER;`);
+            }
+            for (const column of ["kimi_session_id_source", "budget_source"]) {
+                if (!tableHasColumn(this.db, column)) {
+                    this.db.exec("ALTER TABLE jobs ADD COLUMN " + column + " TEXT;");
+                }
+            }
             // Additive provenance migration. Existing rows deliberately remain NULL:
             // v1.9.5 plus kimi-code 0.33/0.34 could have routed to native v2 before the
             // legacy pin landed, so a blanket historical v1 backfill would invent fact.
@@ -94,6 +106,8 @@ export class JobStore {
       CREATE INDEX IF NOT EXISTS jobs_repo_type_updated_idx
         ON jobs (repo_id, command_type, updated_at DESC);
 
+      CREATE INDEX IF NOT EXISTS jobs_session_id_idx ON jobs (kimi_session_id);
+
       CREATE INDEX IF NOT EXISTS jobs_session_idx
         ON jobs (repo_id, kimi_session_id, updated_at DESC);
 
@@ -159,17 +173,17 @@ export class JobStore {
             this.db.run(`
           INSERT INTO jobs (
             job_id, repo_id, command_type, created_at, updated_at, cwd, model, thinking,
-            background, pid, kimi_pid, status, kimi_session_id,
+            background, pid, kimi_pid, status, kimi_session_id, kimi_session_id_source, budget_source,
             operation_kind, intended_engine, observed_engine, kimi_version, system_version,
             kimi_command, kimi_prefix_args, plan_certification, resumed_from_job_id, safety_profile,
-            agent_profile, prompt_digest, summary, phase, final_output_path, stream_log_path, error
+            agent_profile, prompt_digest, summary, phase, budget_ms, final_output_path, stream_log_path, error
           )
           VALUES (
             @job_id, @repo_id, @command_type, @created_at, @updated_at, @cwd, @model, @thinking,
-            @background, @pid, @kimi_pid, @status, @kimi_session_id,
+            @background, @pid, @kimi_pid, @status, @kimi_session_id, @kimi_session_id_source, @budget_source,
             @operation_kind, @intended_engine, @observed_engine, @kimi_version, @system_version,
             @kimi_command, @kimi_prefix_args, @plan_certification, @resumed_from_job_id, @safety_profile,
-            @agent_profile, @prompt_digest, @summary, @phase, @final_output_path, @stream_log_path, @error
+            @agent_profile, @prompt_digest, @summary, @phase, @budget_ms, @final_output_path, @stream_log_path, @error
           )
         `, {
                 ...serializeRecord(input),
@@ -194,6 +208,10 @@ export class JobStore {
         const row = this.db.get("SELECT * FROM jobs WHERE job_id = ?", jobId);
         return row ? hydrateRow(row) : null;
     }
+    /** Global across repos and terminal states; optionally exclude the current row. */
+    hasSessionId(sessionId, exceptJobId = "") {
+        return Boolean(this.db.get("SELECT 1 FROM jobs WHERE kimi_session_id = ? AND job_id != ? LIMIT 1", sessionId, exceptJobId));
+    }
     findLatestJob(options) {
         const conditions = ["repo_id = @repo_id"];
         const params = {
@@ -243,6 +261,18 @@ export class JobStore {
     updateRunningJob(jobId, patch) {
         return this.updateWhere(jobId, patch, "status = 'running'");
     }
+    /** Recheck uniqueness atomically: another worker can claim an ID during the
+     * asynchronous directory scan. Ordinary announced/resumed IDs may be shared. */
+    claimRecoveredSessionId(jobId, sessionId) {
+        this.db.run(`UPDATE jobs
+      SET kimi_session_id = @session_id, kimi_session_id_source = 'recovered_session_dir',
+          updated_at = @updated_at
+      WHERE job_id = @job_id AND status = 'running' AND kimi_session_id IS NULL
+        AND NOT EXISTS (SELECT 1 FROM jobs WHERE kimi_session_id = @session_id AND job_id != @job_id)`, { job_id: jobId, session_id: sessionId, updated_at: new Date().toISOString() });
+        const job = this.getJob(jobId);
+        return job?.status === "running" && job.kimi_session_id === sessionId &&
+            job.kimi_session_id_source === "recovered_session_dir" ? job : null;
+    }
     /**
      * Evidence-only backfill for pre-provenance rows. COALESCE prevents forensic
      * inspection from overwriting a field already recorded at execution time.
@@ -276,7 +306,7 @@ export class JobStore {
         return this.updateWhere(jobId, { ...patch, status: "cancelled", pid: null, kimi_pid: null }, "status = 'running'");
     }
     static JOBS_COLUMNS = new Set([
-        "status", "summary", "phase", "pid", "kimi_pid",
+        "status", "summary", "phase", "budget_ms", "budget_source", "kimi_session_id_source", "pid", "kimi_pid",
         "final_output_path", "stream_log_path", "kimi_session_id",
         "error", "command_type", "prompt_digest", "repo_id",
         "cwd", "model", "thinking", "background", "agent_profile",
@@ -320,6 +350,9 @@ function serializeRecord(record) {
     return {
         ...record,
         phase: record.phase ?? null,
+        budget_ms: record.budget_ms ?? null,
+        budget_source: record.budget_source ?? null,
+        kimi_session_id_source: record.kimi_session_id_source ?? null,
         operation_kind: record.operation_kind ?? null,
         intended_engine: record.intended_engine ?? null,
         observed_engine: record.observed_engine ?? null,
@@ -557,3 +590,7 @@ export function withJobStoreSync(paths, fn) {
         store?.close();
     }
 }
+/** Old non-null budgets have unknown provenance; never invent explicit intent. */
+export function renderBudgetSource(job) {
+    return job.budget_source ?? (job.budget_ms === null ? "default" : "unknown");
+}

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

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { RuntimeError } from "./errors.js";
-import { renderTerminalJobArtifact, writeArtifact } from "./render.js";
+import { formatBudgetDuration, renderTerminalJobArtifact, writeArtifact } from "./render.js";
 export function digestPrompt(prompt) {
     return createHash("sha256").update(prompt).digest("hex");
 }
@@ -30,10 +30,14 @@ export function normalizeJobError(error) {
     };
 }
 export async function markJobFailed(store, paths, job, error, summary = "Job failed.", options) {
+    if (options?.partialOutput) {
+        const label = job.command_type[0].toUpperCase() + job.command_type.slice(1);
+        summary = `${label} timed out after ${formatBudgetDuration(options.partialOutput.budgetMs)}; partial output captured (${options.partialOutput.text.trim().length} chars).`;
+    }
     const normalized = normalizeJobError(error);
     const phase = options?.phase;
     const artifactJob = {
-        ...job,
+        ...(store.getJob(job.job_id) ?? job),
         status: "failed",
         summary,
         error: normalized,
@@ -42,7 +46,7 @@ export async function markJobFailed(store, paths, job, error, summary = "Job fai
         kimi_pid: null,
         ...(phase !== undefined ? { phase } : {}),
     };
-    const artifactPath = await writeArtifact(paths, artifactJob, renderTerminalJobArtifact(artifactJob));
+    const artifactPath = await writeArtifact(paths, artifactJob, renderTerminalJobArtifact(artifactJob, options?.partialOutput));
     return (store.markFailed(job.job_id, {
         summary,
         error: normalized,

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

@@ -38,6 +38,7 @@ export const NATIVE_V2_CERTIFIED_VERSIONS = Object.freeze([
     "2.0.2",
     "2.1.0",
     "2.1.1",
+    "2.2.0",
 ]);
 /** Per-operation native-v2 certification. One green operation never certifies another. */
 export const NATIVE_V2_CERTIFIED = new Map([

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

@@ -1,9 +1,35 @@
 import { RuntimeError, formatError } from "./errors.js";
+const BUDGET_CEILING_MS = 24 * 60 * 60 * 1_000;
+function formatBudgetMs(ms) {
+    if (ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    return `${Math.ceil(ms / 1_000)}s`;
+}
+/**
+ * Suggest a concrete next budget from the one that just expired: double it,
+ * capped at the 24h ceiling. At the ceiling there is nothing left to raise,
+ * so the only honest advice is to narrow the prompt.
+ */
+function budgetAdvice(budgetMs) {
+    if (budgetMs === undefined || !Number.isFinite(budgetMs) || budgetMs <= 0)
+        return "raise the budget (`--budget <dur>`, at most 24h)";
+    if (budgetMs >= BUDGET_CEILING_MS)
+        return "note the budget is already at the 24h ceiling, so narrowing the prompt is the only remaining lever";
+    return `raise the budget (e.g. \`--budget ${formatBudgetMs(Math.min(budgetMs * 2, BUDGET_CEILING_MS))}\`)`;
+}
 export function classifyManagedCommandFailure(error, commandType, jobId, options) {
     const classification = classifyKimiAvailability(error);
     if (!classification) {
         return error instanceof Error ? error : new Error(String(error));
     }
+    if (classification.kind === "response_timeout" && commandType !== "review_gate" && options?.background !== undefined) {
+        const foregroundAdvice = !options?.background && (commandType === "ask" || commandType === "rescue")
+            ? " Or run with --background so the caller's shell timeout is not the limit."
+            : "";
+        classification.nextStep = `Narrow the prompt or ${budgetAdvice(options.budgetMs)}. Partial output, if any, is in the artifact (\`result ${jobId}\`).${foregroundAdvice}`;
+    }
     const label = formatCommandLabel(commandType);
     const stage = options?.preserveStage && error instanceof RuntimeError
         ? error.stage
@@ -18,6 +44,14 @@ export function classifyManagedCommandFailure(error, commandType, jobId, options
     const details = { availability: classification.kind };
     if (error instanceof RuntimeError) {
         details.cause_code = error.code;
+        if (error.code === "RESPONSE_TIMEOUT") {
+            for (const key of ["budget_ms", "record_count", "partial_output_chars", "aborted", "settled_post_abort"]) {
+                if (error.details[key] !== undefined)
+                    details[key] = error.details[key];
+            }
+            if (details.budget_ms === undefined && options?.budgetMs !== undefined)
+                details.budget_ms = options.budgetMs;
+        }
     }
     if (error instanceof Error && error.message.length > 0) {
         details.cause_message = truncateCauseMessageForDetails(error.message);
@@ -170,7 +204,7 @@ function classifyKimiAvailability(error) {
             return {
                 kind: "response_timeout",
                 summary: "Kimi started and accepted the prompt but never returned a final response.",
-                nextStep: "Reduce the prompt scope (or for /kimi:ask and /kimi:rescue, retry with --background to detach). If the response still hangs after a fresh run, check local Kimi version and report upstream.",
+                nextStep: "Narrow the prompt or raise the budget (`--budget <dur>`, at most 24h). Check the job artifact (`result <jobId>`) for any captured partial output. Backgrounding does not extend the runtime budget.",
                 runtimeProbe: "ok",
                 authProbe: "ok",
             };

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

@@ -12,23 +12,23 @@
 // kimi-code spends real wallclock on extended reasoning before emitting
 // the first assistant record; pre-alpha.4 budgets (300s/600s) were sized
 // against the non-thinking path and timed out in production smoke
-// testing under default flags. Raised to 900/1800/1800 so a real
-// thinking-on review/rescue session has headroom; review-gate stays at
+// testing under default flags. Defaults are now 1800/1800/2700 seconds
+// for ask/review/rescue to allow repo-wide work; review-gate stays at
 // 8s because it fires inside Claude Code's Stop hook and is forced to
 // thinking-off in its own caller.
 /** Ask budget. Conversational; thinking-on free-form reasoning. */
-export const KIMI_ASK_PROMPT_TIMEOUT_MS = 900_000;
+export const KIMI_ASK_PROMPT_TIMEOUT_MS = 1_800_000; // 30 minutes
 /** Review/challenge budget. Thinking-on single-turn analysis over the workspace. */
 export const KIMI_REVIEW_PROMPT_TIMEOUT_MS = 1_800_000;
 /** Rescue budget. Thinking-on multi-step apply/test/verify loops. */
-export const KIMI_RESCUE_PROMPT_TIMEOUT_MS = 1_800_000;
+export const KIMI_RESCUE_PROMPT_TIMEOUT_MS = 2_700_000; // 45 minutes
 /**
  * Pursue (autonomous goal mode) DEFAULT wall-clock ceiling when the user
  * passes no `--budget`. This is the ONLY hard bound on an autonomous goal —
  * headless goal create sets no token/turn budget (only the model, via
- * SetGoalBudget, or this AbortController stops the loop). Larger than the
- * single-turn rescue budget (a goal spans multiple continuation turns) but
- * deliberately finite. Overridable per-job via `--budget` (parsed to ms in
+ * SetGoalBudget, or this AbortController stops the loop). The same duration as
+ * the single-turn rescue default, but a safety ceiling rather than a patience
+ * knob. Deliberately finite. Overridable per-job via `--budget` (parsed to ms in
  * parsePursueArgs). See runtime/commands/pursue.ts and docs/safety.md.
  */
 export const KIMI_PURSUE_DEFAULT_BUDGET_MS = 2_700_000; // 45 minutes

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

@@ -21,8 +21,13 @@ function looksLikeFlag(token) {
     // Short flag: a single dash followed by exactly one letter (`-r`, `-m`).
     return /^-[a-zA-Z]$/.test(token);
 }
-const ASK_SUPPORTED_FLAGS = "-m/--model <name>, --background, --wait, --fresh, -r, --resume <job-id|session-id>";
-const RESCUE_SUPPORTED_FLAGS = "-m/--model <name>, --background, --wait, --fresh, -r, --resume <job-id|session-id>";
+export const ASK_SUPPORTED_FLAGS = "-m/--model <name>, --budget <30m|1h|90s>, --background, --wait, --fresh, -r, --resume <job-id|session-id>";
+export const RESCUE_SUPPORTED_FLAGS = "-m/--model <name>, --budget <30m|1h|90s>, --background, --wait, --fresh, -r, --resume <job-id|session-id>";
+export const REVIEW_SUPPORTED_FLAGS = "--base <ref>, -m/--model <name>, --budget <30m|1h|90s>";
+export const JOB_LOOKUP_SUPPORTED_FLAGS = "--type <review|challenge|rescue|review_gate|ask>, --json";
+export const SETUP_SUPPORTED_FLAGS = "--check, --uninstall, --all (with --uninstall), --enable-review-gate, --disable-review-gate, --models [--json] (without other setup flags)";
+export const REPAIR_SESSIONS_SUPPORTED_FLAGS = "--apply, --all";
+export const REPLAY_SUPPORTED_FLAGS = "none (one job-id required)";
 // Thinking-on is always-on for user-facing commands in v1.0. review-gate
 // pins thinking=false via the cli-client options bag instead of an argv
 // flag (see runtime/cli-client.ts::CliClientOptions). The parser rejects
@@ -39,8 +44,8 @@ function isRemovedThinkingFlag(token) {
         token.startsWith("--thinking=") ||
         token.startsWith("--no-thinking="));
 }
-const PURSUE_SUPPORTED_FLAGS = "-m/--model <name>, --budget <30m|1h|90s>, --turns <N>";
-const SWARM_SUPPORTED_FLAGS = "-m/--model <name>, --budget <30m|1h|90s>, --cap <N>, --max-concurrency <N>, --write";
+export const PURSUE_SUPPORTED_FLAGS = "-m/--model <name>, --budget <30m|1h|90s>, --turns <N>";
+export const SWARM_SUPPORTED_FLAGS = "-m/--model <name>, --budget <30m|1h|90s>, --cap <N>, --max-concurrency <N>, --write";
 /**
  * Parser for /kimi:swarm (read-only parallel fan-out). Foreground-only:
  * no --background/--fresh/--resume. Trailing tokens are the objective.
@@ -85,7 +90,7 @@ export function parseSwarmArgs(argv) {
                 if (!value || value.startsWith("-")) {
                     throw new RuntimeError("INVALID_ARGS", "--budget requires a duration (e.g. 30m, 1h, 90s).", "swarm.parse");
                 }
-                budgetMs = parseDurationMs(value, "--budget");
+                budgetMs = parseDurationMs(value, "--budget", "swarm.parse", "safety");
                 index += 1;
                 break;
             }
@@ -154,20 +159,23 @@ export const MAX_DURATION_MS = 24 * 60 * 60 * 1_000;
  * into milliseconds. Throws INVALID_ARGS on a malformed, non-positive, or
  * absurdly large value (> {@link MAX_DURATION_MS}).
  */
-export function parseDurationMs(token, flag) {
+export function parseDurationMs(token, flag, stage, budgetKind) {
+    const limitReason = budgetKind === "safety"
+        ? "the budget is a safety ceiling, not a scheduler"
+        : "the budget is a response-time limit; a timed-out job is still a safe failure";
     const match = /^(\d+)(s|m|h)?$/.exec(token.trim());
     if (!match) {
-        throw new RuntimeError("INVALID_ARGS", `${flag} expects a duration like 30m, 1h, or 90s (bare number = minutes); got "${token}".`, "pursue.parse");
+        throw new RuntimeError("INVALID_ARGS", `${flag} expects a duration like 30m, 1h, or 90s (bare number = minutes); got "${token}".`, stage);
     }
     const value = Number(match[1]);
     const unit = match[2] ?? "m";
     if (!Number.isFinite(value) || value <= 0) {
-        throw new RuntimeError("INVALID_ARGS", `${flag} must be a positive duration.`, "pursue.parse");
+        throw new RuntimeError("INVALID_ARGS", `${flag} must be a positive duration.`, stage);
     }
     const unitMs = unit === "s" ? 1_000 : unit === "h" ? 3_600_000 : 60_000;
     const ms = value * unitMs;
     if (ms > MAX_DURATION_MS) {
-        throw new RuntimeError("INVALID_ARGS", `${flag} must be at most 24h (got "${token}"); the budget is a safety ceiling, not a scheduler.`, "pursue.parse");
+        throw new RuntimeError("INVALID_ARGS", `${flag} must be at most 24h (got "${token}"); ${limitReason}.`, stage);
     }
     return ms;
 }
@@ -211,7 +219,7 @@ export function parsePursueArgs(argv) {
                 if (!value || value.startsWith("-")) {
                     throw new RuntimeError("INVALID_ARGS", "--budget requires a duration (e.g. 30m, 1h, 90s).", "pursue.parse");
                 }
-                budgetMs = parseDurationMs(value, "--budget");
+                budgetMs = parseDurationMs(value, "--budget", "pursue.parse", "safety");
                 index += 1;
                 break;
             }
@@ -248,7 +256,38 @@ export function parsePursueArgs(argv) {
         objective: trailingTokens?.join(" "),
     };
 }
+/** Help before -- wins even over malformed flags or prose trailing-token mode. */
+const VALUE_TAKING_FLAGS = new Set(["-m", "--model", "--budget", "--resume", "--base", "--cap", "--max-concurrency", "--turns", "--type"]);
+/**
+ * `--help` / `-h` counts only inside the leading flag region: before `--`
+ * and before the first prose token. The value of a value-taking flag is
+ * skipped, so `-m kimi -h` is still a help request (`kimi` is a value, not
+ * prose) and `--budget --help` asks for help rather than failing on a bad
+ * duration. Once prose starts (`ask what does du -h print`), nothing after it
+ * is a flag — the whole remainder is the prompt.
+ */
+export function hasHelpFlag(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--")
+            return false;
+        if (token === "--help" || token === "-h")
+            return true;
+        if (!token.startsWith("-"))
+            return false;
+        if (VALUE_TAKING_FLAGS.has(token)) {
+            const value = argv[index + 1];
+            if (value === "--help" || value === "-h")
+                return true;
+            index += 1;
+        }
+    }
+    return false;
+}
 export function parseAskArgs(argv) {
+    if (hasHelpFlag(argv))
+        return { help: true, background: false, wait: false, fresh: false, resume: false };
+    let budgetMs;
     let model;
     // Thinking is on by default across ask/review/challenge/rescue. The
     // parser rejects --thinking / --no-thinking; review-gate's runtime
@@ -272,6 +311,15 @@ export function parseAskArgs(argv) {
             break;
         }
         switch (token) {
+            case "--budget": {
+                const value = argv[index + 1];
+                if (!value || value.startsWith("-")) {
+                    throw new RuntimeError("INVALID_ARGS", "--budget requires a duration (e.g. 30m, 1h, 90s).", "ask.parse");
+                }
+                budgetMs = parseDurationMs(value, "--budget", "ask.parse", "response");
+                index += 1;
+                break;
+            }
             case "-m":
             case "--model": {
                 const value = argv[index + 1];
@@ -327,6 +375,7 @@ export function parseAskArgs(argv) {
         throw new RuntimeError("INVALID_ARGS", "--resume only accepts a job-id or session-id. Use -r to resume the latest ask session with a prompt.", "ask.parse");
     }
     return {
+        budgetMs,
         background,
         wait,
         fresh,
@@ -338,8 +387,9 @@ export function parseAskArgs(argv) {
     };
 }
 export function parseReviewArgs(argv, commandName = "review") {
-    const parsed = parseKnownFlags(argv, new Set(["--base", "--background", "--wait", "-m", "--model"]), commandName);
+    const parsed = parseKnownFlags(argv, new Set(["--budget", "--base", "--background", "--wait", "-m", "--model"]), commandName);
     return {
+        budgetMs: parsed.budgetMs,
         base: parsed.base,
         background: parsed.background,
         wait: parsed.wait,
@@ -349,6 +399,9 @@ export function parseReviewArgs(argv, commandName = "review") {
     };
 }
 export function parseRescueArgs(argv) {
+    if (hasHelpFlag(argv))
+        return { help: true, background: false, wait: false, fresh: false, resume: false };
+    let budgetMs;
     let model;
     let thinking = true;
     let background = false;
@@ -369,6 +422,15 @@ export function parseRescueArgs(argv) {
             break;
         }
         switch (token) {
+            case "--budget": {
+                const value = argv[index + 1];
+                if (!value || value.startsWith("-")) {
+                    throw new RuntimeError("INVALID_ARGS", "--budget requires a duration (e.g. 30m, 1h, 90s).", "rescue.parse");
+                }
+                budgetMs = parseDurationMs(value, "--budget", "rescue.parse", "response");
+                index += 1;
+                break;
+            }
             case "-m":
             case "--model": {
                 const value = argv[index + 1];
@@ -424,6 +486,7 @@ export function parseRescueArgs(argv) {
         throw new RuntimeError("INVALID_ARGS", "--resume only accepts a job-id or session-id. Use -r to resume the latest rescue session with a prompt.", "rescue.parse");
     }
     return {
+        budgetMs,
         background,
         wait,
         fresh,
@@ -454,7 +517,7 @@ export function parseJobLookupArgs(argv) {
             continue;
         }
         if (token.startsWith("-")) {
-            throw new RuntimeError("INVALID_ARGS", `Unknown flag ${token}. Supported flags: --type <review|challenge|rescue|review_gate|ask>, --json.`, "args.parse");
+            throw new RuntimeError("INVALID_ARGS", `Unknown flag ${token}. Supported flags: ${JOB_LOOKUP_SUPPORTED_FLAGS}.`, "args.parse");
         }
         if (jobId) {
             throw new RuntimeError("INVALID_ARGS", "Only one optional job id may be supplied.", "args.parse");
@@ -475,6 +538,7 @@ function isManagedCommandType(value) {
         value === "ask");
 }
 function parseKnownFlags(argv, knownFlags, commandName) {
+    let budgetMs;
     let model;
     let thinking = true;
     let base;
@@ -497,12 +561,21 @@ function parseKnownFlags(argv, knownFlags, commandName) {
                 // slurping them into focus text produced a bloated prompt that
                 // looked like a hang. Hard-fail with the supported list inline so
                 // the error message itself is the correction.
-                throw new RuntimeError("INVALID_ARGS", `Unknown flag ${token} for ${commandName}. Supported flags: --base <ref>, -m/--model <name>. Use \`--\` before flag-shaped focus text to pass it through.`, "args.parse");
+                throw new RuntimeError("INVALID_ARGS", `Unknown flag ${token} for ${commandName}. Supported flags: ${REVIEW_SUPPORTED_FLAGS}. Use \`--\` before flag-shaped focus text to pass it through.`, "args.parse");
             }
             trailingTokens = argv.slice(index);
             break;
         }
         switch (token) {
+            case "--budget": {
+                const value = argv[index + 1];
+                if (!value || value.startsWith("-")) {
+                    throw new RuntimeError("INVALID_ARGS", "--budget requires a duration (e.g. 30m, 1h, 90s).", `${commandName}.parse`);
+                }
+                budgetMs = parseDurationMs(value, "--budget", `${commandName}.parse`, "response");
+                index += 1;
+                break;
+            }
             case "-m":
             case "--model": {
                 const value = argv[index + 1];
@@ -543,6 +616,7 @@ function parseKnownFlags(argv, knownFlags, commandName) {
         }
     }
     return {
+        budgetMs,
         base,
         background,
         wait,

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

@@ -126,7 +126,16 @@ export function renderReviewGateArtifact(job, output) {
     }
     return `${lines.join("\n")}\n`;
 }
-export function renderTerminalJobArtifact(job) {
+export function formatBudgetDuration(ms) {
+    if (ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    if (ms % 1_000 === 0)
+        return `${ms / 1_000}s`;
+    return `${ms}ms`;
+}
+export function renderTerminalJobArtifact(job, partialOutput) {
     const lines = [
         `# ${capitalize(job.status)} Job`,
         "",
@@ -149,6 +158,15 @@ export function renderTerminalJobArtifact(job) {
             }
         }
     }
+    if (partialOutput) {
+        lines.push("", `## Partial output (budget exhausted after ${formatBudgetDuration(partialOutput.budgetMs)} — NOT a final answer)`, "", partialOutput.text.trim()
+            ? partialOutput.text
+            : partialOutput.recordCount === 0
+                ? "No stream records arrived before the budget expired (the model had not produced any output yet)."
+                : partialOutput.toolCalls
+                    ? "No assistant prose was emitted before the budget (tool calls only)."
+                    : "No assistant prose was emitted before the budget.");
+    }
     return lines.join("\n");
 }
 function capitalize(value) {