@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.2

package/dist/protocol/transport.js

@@ -25,8 +25,9 @@ export function createInProcessTransport() {
             emitterA.on("message", handler);
         },
         close() {
+            // Only tear down our own incoming channel; the other side listens on
+            // emitterB and must keep working if it hasn't closed yet.
             emitterA.removeAllListeners();
-            emitterB.removeAllListeners();
         },
     };
     const sideB = {
@@ -38,7 +39,7 @@ export function createInProcessTransport() {
             emitterB.on("message", handler);
         },
         close() {
-            emitterA.removeAllListeners();
+            // Only tear down our own incoming channel; sideA listens on emitterA.
             emitterB.removeAllListeners();
         },
     };

package/dist/protocol/types.d.ts

@@ -61,11 +61,28 @@ export interface RunParams {
      * When omitted, the engine keeps its configured default.
      */
     permissionMode?: PermissionMode;
+    /**
+     * Workspace trust for this run's project (`cwd`), asserted by the host
+     * (desktop main from its trust-store) — never by the renderer. When false,
+     * the engine strips dangerous fields from the project's own .code-shell
+     * settings (permissions/env/hooks/mcpServers/localEnvironment). Omitted →
+     * trusted (preserves behavior for hosts that don't wire trust).
+     */
+    projectTrusted?: boolean;
     /**
      * Per-run plan-mode flag. When true, the Engine enters plan mode for
      * this run; when omitted, the engine keeps its configured default.
      */
     planMode?: boolean;
+    /**
+     * Require the target session to already exist on disk. When true and the
+     * session is absent, the run is rejected with `SessionNotFound` instead of
+     * silently creating a fresh empty session. Used by cron "continue this
+     * conversation" jobs: if the user deleted the target session, the job must
+     * fail loudly (so it can be auto-disabled) rather than run its prompt against
+     * a blank context. Omitted/false → the normal resume-or-create behavior.
+     */
+    requireExisting?: boolean;
     /**
      * Goal mode for this run. When set, the engine runs loop-until-done:
      * on each natural completion a GoalStopHook judges whether this goal is
@@ -103,6 +120,19 @@ export interface InjectParams {
     sessionId: string;
     content: string;
 }
+/** Steer an in-flight run: queue a user message for the next turn-loop step. */
+export interface SteerParams {
+    sessionId: string;
+    text: string;
+    /** Stable host-side id for this queued draft. Rides through to the
+     *  steer_injected event and is the handle Unsteer uses to revoke it. */
+    id?: string;
+}
+/** Revoke a still-pending steer entry by id (before the loop consumes it). */
+export interface UnsteerParams {
+    sessionId: string;
+    id: string;
+}
 /** Update runtime configuration. */
 export interface ConfigureParams {
     /** When present, configure that specific chat session. Otherwise worker-global. */
@@ -229,8 +259,24 @@ export declare const Methods: {
     readonly Query: "agent/query";
     /** Inject context into transcript without triggering LLM. */
     readonly Inject: "agent/inject";
+    /** Steer an in-flight run: queue a user message spliced at the next step (不打断). */
+    readonly Steer: "agent/steer";
+    /** Revoke a still-pending steer entry by id (撤回, before the loop consumes it). */
+    readonly Unsteer: "agent/unsteer";
     /** Close (destroy) a session. */
     readonly CloseSession: "agent/closeSession";
+    /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
+    readonly GoalExtend: "agent/goalExtend";
+    /** Clear a session's persisted active goal (CC /goal clear). */
+    readonly GoalClear: "agent/goalClear";
+    /** Read a session's persisted active goal, to re-surface it on session load. */
+    readonly GoalGet: "agent/goalGet";
+    /** Query/control a session's background shells for the UI panel (TODO 3.2). */
+    readonly BackgroundShells: "agent/backgroundShells";
+    /** Unified listing of a session's background work (shells + sub-agents + jobs)
+     *  for the desktop background panel. Output/kill of a shell still goes through
+     *  BackgroundShells by shellId; this is list-only across all three kinds. */
+    readonly BackgroundWork: "agent/backgroundWork";
     readonly StreamEvent: "agent/streamEvent";
     readonly ApprovalRequest: "agent/approvalRequest";
     readonly Status: "agent/status";

package/dist/protocol/types.js

@@ -35,8 +35,24 @@ export const Methods = {
     Query: "agent/query",
     /** Inject context into transcript without triggering LLM. */
     Inject: "agent/inject",
+    /** Steer an in-flight run: queue a user message spliced at the next step (不打断). */
+    Steer: "agent/steer",
+    /** Revoke a still-pending steer entry by id (撤回, before the loop consumes it). */
+    Unsteer: "agent/unsteer",
     /** Close (destroy) a session. */
     CloseSession: "agent/closeSession",
+    /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
+    GoalExtend: "agent/goalExtend",
+    /** Clear a session's persisted active goal (CC /goal clear). */
+    GoalClear: "agent/goalClear",
+    /** Read a session's persisted active goal, to re-surface it on session load. */
+    GoalGet: "agent/goalGet",
+    /** Query/control a session's background shells for the UI panel (TODO 3.2). */
+    BackgroundShells: "agent/backgroundShells",
+    /** Unified listing of a session's background work (shells + sub-agents + jobs)
+     *  for the desktop background panel. Output/kill of a shell still goes through
+     *  BackgroundShells by shellId; this is list-only across all three kinds. */
+    BackgroundWork: "agent/backgroundWork",
     // Server → Client (notifications, no id)
     StreamEvent: "agent/streamEvent",
     ApprovalRequest: "agent/approvalRequest",

package/dist/quota/credentials.d.ts

@@ -0,0 +1,3 @@
+import type { QuotaCredentials } from "./types.js";
+/** Resolve all tokens from their standard local locations. Never throws. */
+export declare function resolveQuotaCredentials(): Promise<QuotaCredentials>;

package/dist/quota/credentials.js

@@ -0,0 +1,80 @@
+/**
+ * Default resolver for the tokens `quota/` needs.
+ *
+ * This is the ONE platform-specific file in the module — it reads a vendor's
+ * Keychain entry / auth.json. A host that stores secrets differently (or a
+ * future plugin) can bypass this and build QuotaCredentials itself; core logic
+ * in index.ts only depends on the QuotaCredentials shape.
+ *
+ * All reads are best-effort: a missing token yields `undefined`, never a throw,
+ * so a machine without Codex or without Keychain access degrades to "quota
+ * unavailable for that provider" instead of failing the whole call.
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function userHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+/** Read the Codex OAuth token + account id from ~/.codex/auth.json. */
+async function readCodexCreds() {
+    try {
+        const raw = await readFile(join(userHome(), ".codex", "auth.json"), "utf8");
+        const j = JSON.parse(raw);
+        const tokens = (j.tokens ?? {});
+        const token = typeof tokens.access_token === "string" ? tokens.access_token : undefined;
+        const acct = typeof tokens.account_id === "string" ? tokens.account_id : undefined;
+        return { codexAccessToken: token, codexAccountId: acct };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Read the Claude Code OAuth access token.
+ * macOS: Keychain generic-password "Claude Code-credentials".
+ * Other platforms: fall back to a plaintext ~/.claude/.credentials.json if present.
+ */
+async function readClaudeCreds() {
+    // macOS Keychain first.
+    if (process.platform === "darwin") {
+        const raw = await runSecurity();
+        const token = parseClaudeToken(raw);
+        if (token)
+            return { claudeAccessToken: token };
+    }
+    // Cross-platform fallback: some installs keep a plaintext credentials file.
+    try {
+        const raw = await readFile(join(userHome(), ".claude", ".credentials.json"), "utf8");
+        const token = parseClaudeToken(raw);
+        if (token)
+            return { claudeAccessToken: token };
+    }
+    catch {
+        /* not present */
+    }
+    return {};
+}
+function parseClaudeToken(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const j = JSON.parse(raw);
+        const oauth = (j.claudeAiOauth ?? {});
+        return typeof oauth.accessToken === "string" ? oauth.accessToken : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runSecurity() {
+    return new Promise((resolve) => {
+        execFile("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], { timeout: 4000 }, (err, stdout) => resolve(err ? null : stdout.toString().trim()));
+    });
+}
+/** Resolve all tokens from their standard local locations. Never throws. */
+export async function resolveQuotaCredentials() {
+    const [codex, claude] = await Promise.all([readCodexCreds(), readClaudeCreds()]);
+    return { ...codex, ...claude };
+}

package/dist/quota/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Query remaining quota for the external coding-agent CLIs.
+ *
+ * Both lookups are verified against the real backends (2026-07-01):
+ *   - Codex: GET https://chatgpt.com/backend-api/wham/usage → JSON
+ *            rate_limit.{primary_window,secondary_window}.{used_percent,reset_at}.
+ *            Zero cost (no message sent).
+ *   - Claude: POST /v1/messages (max_tokens:1) → response headers
+ *            anthropic-ratelimit-unified-{5h,7d}-{utilization,reset}.
+ *            Costs ~1 output token (Claude exposes quota only via response
+ *            headers — there is no standalone usage endpoint).
+ *
+ * The `fetch` and credentials are injected so this is unit-testable offline and
+ * so the host owns secret resolution (see types.ts boundary note).
+ */
+import type { ProviderQuota, QuotaCredentials, QuotaResult } from "./types.js";
+type FetchLike = typeof fetch;
+export interface CheckQuotaOptions {
+    creds: QuotaCredentials;
+    /** Restrict to specific providers; defaults to both. */
+    providers?: ("claude" | "codex")[];
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: FetchLike;
+    /** Caller's abort signal (user Stop); composed with an internal timeout. */
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Codex: GET the usage endpoint and map its JSON to ProviderQuota. */
+export declare function queryCodexQuota(creds: QuotaCredentials, fetchImpl: FetchLike, signal: AbortSignal): Promise<ProviderQuota>;
+/** Claude: POST a 1-token probe and read the unified rate-limit headers. */
+export declare function queryClaudeQuota(creds: QuotaCredentials, fetchImpl: FetchLike, signal: AbortSignal): Promise<ProviderQuota>;
+/** Query both providers (or the subset requested), concurrently. */
+export declare function checkQuota(opts: CheckQuotaOptions): Promise<QuotaResult>;
+/** Render a QuotaResult as a compact human/agent-readable summary. */
+export declare function formatQuota(result: QuotaResult, nowSec: number): string;
+export {};

package/dist/quota/index.js

@@ -0,0 +1,155 @@
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const CLAUDE_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+/** Cheapest always-available model for the 1-token probe. */
+const CLAUDE_PROBE_MODEL = "claude-haiku-4-5-20251001";
+const DEFAULT_TIMEOUT_MS = 8000;
+/** Compose the caller signal with a timeout so a hung backend can't block. */
+function withTimeout(signal, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function num(v) {
+    const n = typeof v === "string" ? parseFloat(v) : typeof v === "number" ? v : NaN;
+    return Number.isFinite(n) ? n : null;
+}
+/** Codex: GET the usage endpoint and map its JSON to ProviderQuota. */
+export async function queryCodexQuota(creds, fetchImpl, signal) {
+    if (!creds.codexAccessToken) {
+        return { provider: "codex", error: "no Codex token (是否已 codex login?)" };
+    }
+    let resp;
+    try {
+        resp = await fetchImpl(CODEX_USAGE_URL, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${creds.codexAccessToken}`,
+                ...(creds.codexAccountId ? { "chatgpt-account-id": creds.codexAccountId } : {}),
+                originator: "codex_cli_rs",
+                "user-agent": "codex_cli_rs",
+            },
+            signal,
+        });
+    }
+    catch (err) {
+        return { provider: "codex", error: `请求失败: ${err.message}` };
+    }
+    if (!resp.ok) {
+        return { provider: "codex", error: `HTTP ${resp.status}${resp.status === 401 ? " (token 可能已过期)" : ""}` };
+    }
+    let body;
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        return { provider: "codex", error: "响应非 JSON" };
+    }
+    const rl = (body.rate_limit ?? {});
+    const windows = [];
+    const map = [
+        ["primary_window", "5h"],
+        ["secondary_window", "7d"],
+    ];
+    for (const [key, kind] of map) {
+        const w = rl[key];
+        if (!w)
+            continue;
+        const usedPercent = num(w.used_percent);
+        if (usedPercent == null)
+            continue;
+        windows.push({ kind, usedPercent, resetsAt: num(w.reset_at) });
+    }
+    if (windows.length === 0)
+        return { provider: "codex", error: "响应无 rate_limit 窗口" };
+    return {
+        provider: "codex",
+        windows,
+        planType: typeof body.plan_type === "string" ? body.plan_type : null,
+    };
+}
+/** Claude: POST a 1-token probe and read the unified rate-limit headers. */
+export async function queryClaudeQuota(creds, fetchImpl, signal) {
+    if (!creds.claudeAccessToken) {
+        return { provider: "claude", error: "no Claude Code token (是否已登录 Claude Code?)" };
+    }
+    let resp;
+    try {
+        resp = await fetchImpl(CLAUDE_MESSAGES_URL, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${creds.claudeAccessToken}`,
+                "anthropic-version": "2023-06-01",
+                "anthropic-beta": "oauth-2025-04-20",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: CLAUDE_PROBE_MODEL,
+                max_tokens: 1,
+                messages: [{ role: "user", content: "hi" }],
+            }),
+            signal,
+        });
+    }
+    catch (err) {
+        return { provider: "claude", error: `请求失败: ${err.message}` };
+    }
+    if (!resp.ok) {
+        return { provider: "claude", error: `HTTP ${resp.status}${resp.status === 401 ? " (token 可能已过期)" : ""}` };
+    }
+    const h = resp.headers;
+    const windows = [];
+    const map = [
+        ["anthropic-ratelimit-unified-5h-utilization", "anthropic-ratelimit-unified-5h-reset", "5h"],
+        ["anthropic-ratelimit-unified-7d-utilization", "anthropic-ratelimit-unified-7d-reset", "7d"],
+    ];
+    for (const [utilKey, resetKey, kind] of map) {
+        const util = num(h.get(utilKey)); // 0–1
+        if (util == null)
+            continue;
+        windows.push({ kind, usedPercent: util * 100, resetsAt: num(h.get(resetKey)) });
+    }
+    if (windows.length === 0)
+        return { provider: "claude", error: "响应头无 rate-limit 字段" };
+    return { provider: "claude", windows };
+}
+/** Query both providers (or the subset requested), concurrently. */
+export async function checkQuota(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const providers = opts.providers ?? ["claude", "codex"];
+    const signal = withTimeout(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const result = {};
+    await Promise.all(providers.map(async (p) => {
+        if (p === "codex")
+            result.codex = await queryCodexQuota(opts.creds, fetchImpl, signal);
+        else
+            result.claude = await queryClaudeQuota(opts.creds, fetchImpl, signal);
+    }));
+    return result;
+}
+/** Render a QuotaResult as a compact human/agent-readable summary. */
+export function formatQuota(result, nowSec) {
+    const lines = [];
+    for (const pq of [result.claude, result.codex]) {
+        if (!pq)
+            continue;
+        const name = pq.provider === "claude" ? "Claude Code" : "Codex";
+        if (pq.error || !pq.windows) {
+            lines.push(`${name}: 查询失败 — ${pq.error ?? "unknown"}`);
+            continue;
+        }
+        const plan = pq.planType ? ` [${pq.planType}]` : "";
+        const parts = pq.windows.map((w) => {
+            const reset = w.resetsAt != null ? ` (重置 ${formatReset(w.resetsAt - nowSec)})` : "";
+            return `${w.kind} 用了 ${w.usedPercent.toFixed(0)}%${reset}`;
+        });
+        lines.push(`${name}${plan}: ${parts.join("，")}`);
+    }
+    return lines.length ? lines.join("\n") : "(无可用额度信息)";
+}
+/** "2h13m" / "45m" / "已重置" from a seconds delta. */
+function formatReset(deltaSec) {
+    if (deltaSec <= 0)
+        return "已重置";
+    const h = Math.floor(deltaSec / 3600);
+    const m = Math.floor((deltaSec % 3600) / 60);
+    return h > 0 ? `${h}h${m}m 后` : `${m}m 后`;
+}

package/dist/quota/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Quota (rate-limit / usage) types for external coding-agent CLIs.
+ *
+ * DESIGN / BOUNDARY NOTE (see project_core_minimal_harness_business_layer):
+ * "how to read Claude Code / Codex remaining quota" is provider-specific
+ * BUSINESS policy, not core harness mechanism — it pokes a vendor's Keychain
+ * entry, an undocumented usage endpoint, and private response headers. It lives
+ * in this self-contained `quota/` module (one interface out: `checkQuota`) on
+ * purpose, so it can be lifted wholesale into a plugin later without untangling
+ * it from the rest of core. Nothing outside this module should know about
+ * Keychain / wham endpoints / `anthropic-ratelimit-*` header names.
+ */
+/** A single rolling limit window (e.g. the 5-hour or 7-day window). */
+export interface QuotaWindow {
+    /** Which window this is. */
+    kind: "5h" | "7d";
+    /** Percent of the window's limit already used, 0–100. */
+    usedPercent: number;
+    /** Unix epoch seconds when this window resets, or null if unknown. */
+    resetsAt: number | null;
+}
+/** Quota for one provider (claude | codex). */
+export interface ProviderQuota {
+    provider: "claude" | "codex";
+    /** Present when the lookup succeeded. */
+    windows?: QuotaWindow[];
+    /** Subscription tier, when the source exposes it (e.g. "team", "pro"). */
+    planType?: string | null;
+    /** Human-readable failure reason when the lookup did not succeed. */
+    error?: string;
+}
+export interface QuotaResult {
+    claude?: ProviderQuota;
+    codex?: ProviderQuota;
+}
+/**
+ * A credential the host supplies so this module can talk to a vendor backend.
+ * Core never reads the Keychain / auth.json itself — the host (desktop main /
+ * server) resolves the secret and hands it in. This is the seam that makes the
+ * whole module portable to a plugin.
+ */
+export interface QuotaCredentials {
+    /** Claude Code OAuth access token (from Keychain "Claude Code-credentials"). */
+    claudeAccessToken?: string;
+    /** Codex OAuth access token + account id (from ~/.codex/auth.json). */
+    codexAccessToken?: string;
+    codexAccountId?: string;
+}

package/dist/quota/types.js

@@ -0,0 +1,13 @@
+/**
+ * Quota (rate-limit / usage) types for external coding-agent CLIs.
+ *
+ * DESIGN / BOUNDARY NOTE (see project_core_minimal_harness_business_layer):
+ * "how to read Claude Code / Codex remaining quota" is provider-specific
+ * BUSINESS policy, not core harness mechanism — it pokes a vendor's Keychain
+ * entry, an undocumented usage endpoint, and private response headers. It lives
+ * in this self-contained `quota/` module (one interface out: `checkQuota`) on
+ * purpose, so it can be lifted wholesale into a plugin later without untangling
+ * it from the rest of core. Nothing outside this module should know about
+ * Keychain / wham endpoints / `anthropic-ratelimit-*` header names.
+ */
+export {};

package/dist/review/review-prompt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Code-review prompt builder (TODO 7.3). Produces the instruction sent to the
+ * model for `/review`. Pure + testable — the TUI/desktop command gathers the
+ * diff or file contents and calls this; the model does the actual reasoning.
+ *
+ * Findings are structured: priority P0–P3, a confidence score, and a precise
+ * location, so the output is consistent and (optionally) machine-readable for
+ * CI/CD via `--json`.
+ */
+export type ReviewDimension = "security" | "performance" | "readability" | "correctness";
+export declare const ALL_DIMENSIONS: ReviewDimension[];
+export interface ReviewPromptOptions {
+    /** The unified diff (incremental) or full file contents to review. */
+    content: string;
+    /** Which dimensions to weigh. Defaults to all four. */
+    dimensions?: ReviewDimension[];
+    /** True when reviewing a diff (incremental); false when reviewing whole files. */
+    incremental?: boolean;
+    /** Emit a machine-readable JSON findings array (for CI/CD) instead of prose. */
+    json?: boolean;
+    /** Optional label for what's under review (e.g. a file path). */
+    label?: string;
+    /** Truncate content to this many chars (default 12000). */
+    maxChars?: number;
+}
+/** Normalize a comma/space list of dimension names; invalid names dropped. */
+export declare function parseDimensions(input: string | undefined): ReviewDimension[];
+export declare function buildReviewPrompt(opts: ReviewPromptOptions): string;

package/dist/review/review-prompt.js

@@ -0,0 +1,81 @@
+/**
+ * Code-review prompt builder (TODO 7.3). Produces the instruction sent to the
+ * model for `/review`. Pure + testable — the TUI/desktop command gathers the
+ * diff or file contents and calls this; the model does the actual reasoning.
+ *
+ * Findings are structured: priority P0–P3, a confidence score, and a precise
+ * location, so the output is consistent and (optionally) machine-readable for
+ * CI/CD via `--json`.
+ */
+export const ALL_DIMENSIONS = [
+    "correctness",
+    "security",
+    "performance",
+    "readability",
+];
+const DIMENSION_LABEL = {
+    security: "安全 (injection, authz, secret leakage, unsafe deserialization)",
+    performance: "性能 (N+1, needless allocation, blocking I/O, complexity)",
+    readability: "可读性 (naming, structure, dead code, comment accuracy)",
+    correctness: "正确性 (logic bugs, edge cases, error handling, races)",
+};
+/** Normalize a comma/space list of dimension names; invalid names dropped. */
+export function parseDimensions(input) {
+    if (!input)
+        return ALL_DIMENSIONS;
+    const wanted = input
+        .split(/[\s,]+/)
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const picked = ALL_DIMENSIONS.filter((d) => wanted.includes(d));
+    return picked.length > 0 ? picked : ALL_DIMENSIONS;
+}
+const PRIORITY_GUIDE = "Priority: P0 = must fix before merge (data loss, security hole, crash); " +
+    "P1 = should fix (likely bug, real risk); " +
+    "P2 = nice to fix (smell, minor inefficiency); " +
+    "P3 = optional (style, nit).";
+export function buildReviewPrompt(opts) {
+    const dims = opts.dimensions?.length ? opts.dimensions : ALL_DIMENSIONS;
+    const maxChars = opts.maxChars ?? 12_000;
+    const body = opts.content.length > maxChars
+        ? opts.content.slice(0, maxChars) + "\n…(truncated)…"
+        : opts.content;
+    const fence = opts.incremental === false ? "" : "diff";
+    const what = opts.incremental === false ? "code" : "code changes (diff)";
+    const subject = opts.label ? ` for \`${opts.label}\`` : "";
+    const dimLines = dims.map((d) => `  - ${DIMENSION_LABEL[d]}`).join("\n");
+    if (opts.json) {
+        return [
+            `Review the following ${what}${subject} across these dimensions:`,
+            dimLines,
+            ``,
+            PRIORITY_GUIDE,
+            ``,
+            `Respond with ONLY a JSON object (no prose, no markdown fence) of the form:`,
+            `{"summary": string, "findings": [{"priority": "P0"|"P1"|"P2"|"P3", ` +
+                `"dimension": ${dims.map((d) => `"${d}"`).join("|")}, ` +
+                `"confidence": number /*0..1*/, "location": string /*file:line*/, ` +
+                `"title": string, "detail": string, "suggestion": string}]}`,
+            `Order findings by priority then confidence. Omit a finding rather than guess.`,
+            ``,
+            "```" + fence,
+            body,
+            "```",
+        ].join("\n");
+    }
+    return [
+        `Review the following ${what}${subject} across these dimensions:`,
+        dimLines,
+        ``,
+        PRIORITY_GUIDE,
+        ``,
+        `For each finding, give: **[P0-P3]** a short title, the location (file:line), ` +
+            `your confidence (low/med/high), what's wrong, and a concrete fix.`,
+        `Start with a one-line summary, then list findings ordered by priority. ` +
+            `If nothing warrants a finding, say so plainly. Don't pad with nits to look thorough.`,
+        ``,
+        "```" + fence,
+        body,
+        "```",
+    ].join("\n");
+}

package/dist/run/FileRunStore.js

@@ -126,9 +126,14 @@ export class FileRunStore {
         }
         // Sort by createdAt descending (newest first)
         snapshots.sort((a, b) => b.createdAt - a.createdAt);
-        // Pagination
-        const offset = query?.offset ?? 0;
-        const limit = query?.limit ?? 50;
+        // Pagination. Clamp to sane bounds before slicing: a negative offset would
+        // make Array.slice count "from the end" and silently return a surprise tail
+        // window; a negative limit would drop elements off the end. Both nonsensical
+        // for pagination — clamp offset≥0, treat a non-positive limit as an empty page.
+        const rawOffset = query?.offset ?? 0;
+        const rawLimit = query?.limit ?? 50;
+        const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? Math.floor(rawOffset) : 0;
+        const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.floor(rawLimit) : 0;
         return snapshots.slice(offset, offset + limit);
     }
     async delete(runId) {

package/dist/run/RunApprovalBackend.js

@@ -24,8 +24,15 @@ export class RunApprovalBackend {
     }
     async requestApproval(request) {
         if (!this.hooks) {
-            // No hooks wired — fall back to auto-approve (shouldn't happen in practice)
-            return { approved: true };
+            // No hooks wired — fail CLOSED. This backend is the engine's approval
+            // path for an interactive run; if a host forgot to setHooks() there is
+            // no UI to ask, so auto-approving every tool (the old behavior) silently
+            // bypassed all approval. Denying is the safe default — a misconfigured
+            // run refuses tools instead of running `rm -rf /` unattended. (§5.6 #15)
+            return {
+                approved: false,
+                reason: "run approval backend has no lifecycle hooks wired (denied fail-closed)",
+            };
         }
         // Notify RunManager that approval is needed
         const { approvalId } = await this.hooks.onApprovalNeeded(request);
@@ -64,12 +71,25 @@ export class RunApprovalBackend {
  */
 export function createRunAskUserFn(hooks) {
     let pending = null;
+    const supersedePending = () => {
+        // A run suspends on a single input at a time (RunManager resolves via one
+        // handle). If a second ask arrives while one is still pending, the old
+        // code overwrote the slot and the first promise hung forever. Reject the
+        // prior one so its awaiter unblocks instead of leaking. (§5.6 #15)
+        if (pending) {
+            pending.reject(new Error("superseded: a newer AskUser request replaced this one before it was answered"));
+            pending = null;
+        }
+    };
     const askUserFn = async (question) => {
         // Notify RunManager
         await hooks.onInputNeeded(question);
-        // Suspend execution until user provides input
-        return new Promise((resolve) => {
-            pending = { resolve, question };
+        // Suspend execution until user provides input. The supersede check runs
+        // here — AFTER the await — so it sees a `pending` set by an earlier ask
+        // whose own await already resolved, rather than racing the assignment.
+        return new Promise((resolve, reject) => {
+            supersedePending();
+            pending = { resolve, reject, question };
         });
     };
     const resolveInput = (answer) => {

package/dist/run/RunManager.d.ts

@@ -49,10 +49,22 @@ export declare class RunManager {
     private readonly abortControllers;
     /** Active execution handles — used to resolve pending approvals/input while Engine is suspended */
     private readonly executionHandles;
+    /**
+     * Runs with a resume()/cancel() decision currently being applied. Guards the
+     * approval/input resume race: resume() and cancel() each have multiple await
+     * points, and the status check at the top of resume() reads a value that
+     * stays `waiting_*` until a later `await transition()` lands. Two concurrent
+     * resumes (double-click approve), or resume racing cancel, would both pass
+     * that check and both drive transitions / resolve the handle. The handle's
+     * resolve is idempotent, but the duplicate transitions and (worse) the
+     * mismatched-input re-queue path are not. We serialize per-run here.
+     */
+    private readonly resolvingRuns;
     constructor(config: RunManagerConfig);
     submit(input: SubmitRunInput): Promise<RunSnapshot>;
     start(runId: string): Promise<void>;
     resume(runId: string, input?: ResumeRunInput): Promise<void>;
+    private resumeInner;
     cancel(runId: string, reason?: string): Promise<void>;
     get(runId: string): Promise<RunSnapshot | null>;
     list(query?: ListRunsQuery): Promise<RunSnapshot[]>;