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

package/README.md

@@ -2,7 +2,7 @@
 
 UI-agnostic agent orchestration framework. The headless core of [`code-shell`](https://github.com/cjhyy/codeshell): turn an LLM + a tool registry + a transcript into a multi-turn agent loop, with permissions, hooks, MCP support, and pluggable approval backends.
 
-Compatible with Anthropic and OpenAI-protocol providers (Claude, DeepSeek, GPT, Gemini, Qwen, …). No terminal UI dependencies — embed it in a CLI, a web service, a Slack bot, a desktop app.
+Compatible with Anthropic and OpenAI-protocol providers (Claude, DeepSeek, GPT, Gemini, Qwen, …). No terminal UI dependencies — embed it in a CLI, a web service, a Slack bot, a desktop app. This is a Node.js runtime package, not a browser SDK.
 
 ## Install
 
@@ -12,7 +12,7 @@ npm install @cjhyy/code-shell-core
 bun add @cjhyy/code-shell-core
 ```
 
-Requires Node ≥ 20.10.
+Requires Node ≥ 20.10 and an ESM-capable runtime.
 
 ## Quickstart
 
@@ -29,8 +29,10 @@ const engine = new Engine({
     apiKey: process.env.ANTHROPIC_API_KEY!,
   },
   cwd: process.cwd(),
-  // Headless approval — "approve-all" trusts the model fully; use
-  // "approve-read-only" or a custom ApprovalBackend in production.
+  // Headless approval — "approve-all" trusts the model fully and is
+  // only appropriate for local/trusted prompts. Use "approve-read-only",
+  // explicit permissionMode/tool allowlists, or a custom ApprovalBackend
+  // in production.
   approvalBackend: new HeadlessApprovalBackend("approve-all"),
   headless: true,
 });
@@ -78,7 +80,7 @@ new Engine({
 
 ## Designing for production
 
-- **Approval backend.** `HeadlessApprovalBackend("approve-all")` is fine for trusted prompts. For untrusted input, implement `ApprovalBackend` to gate destructive tools (Write/Edit/Bash) through your own auth.
+- **Approval backend.** `HeadlessApprovalBackend("approve-all")` is fine only for local/trusted prompts. For untrusted input, explicitly set `permissionMode`, restrict tools with `enabledBuiltinTools` / `disabledBuiltinTools`, or implement `ApprovalBackend` to gate destructive tools (Write/Edit/Bash) through your own auth.
 - **Permission rules.** Pass `permissionRules` to the engine for fine-grained allow/deny per tool + args pattern. Bash commands additionally get a built-in safety classifier (dangerous commands like `rm -rf` always require explicit approval).
 - **Hooks** are the right place for audit logging, prompt rewriting, and policy enforcement.
 - **Memory.** The engine ships with an extract-memories + auto-dream pipeline that persists to `~/.code-shell/memory/`. Disable by passing a no-op `MemoryOrchestrator`, or scope to a project by setting `CODE_SHELL_HOME`.
@@ -144,11 +146,12 @@ These exports are covered by the stability promise:
 
 ### Treat as internal
 
-Anything not in the table above — including direct imports from
-`./engine/...`, `./tool-system/...`, `./session/...`, `./hooks/...`
-subpaths and APIs marked `@internal` in their docstrings — may change
-between minor versions without notice. Plan to migrate via the protocol
-surface instead of deep-importing.
+Anything not in the table above — including root-entry exports for
+product/runtime helpers and direct imports from `./engine/...`,
+`./tool-system/...`, `./session/...`, `./hooks/...` subpaths — is
+experimental/internal unless explicitly documented otherwise, and may
+change between minor versions without notice. Plan to migrate via the
+protocol surface instead of deep-importing.
 
 ## Stability
 

package/dist/agent/agent-definition-registry.d.ts

@@ -2,6 +2,9 @@ import { type AgentDefinition } from "./agent-definition.js";
 export interface AgentSourceDir {
     dir: string;
     source: "project" | "user" | "plugin";
+    /** For source === "plugin": the owning plugin name, carried onto each def
+     *  so the spawn layer can namespace bare skill allowlists. */
+    pluginName?: string;
 }
 /**
  * Loads reusable sub-agent role definitions from one or more directories

package/dist/agent/agent-definition-registry.js

@@ -24,7 +24,7 @@ export class AgentDefinitionRegistry {
     }
     static loadFromDirs(dirs, disabled) {
         const reg = new AgentDefinitionRegistry();
-        for (const { dir, source } of dirs) {
+        for (const { dir, source, pluginName } of dirs) {
             if (!existsSync(dir) || !statSync(dir).isDirectory())
                 continue;
             for (const entry of readdirSync(dir).sort()) {
@@ -36,6 +36,8 @@ export class AgentDefinitionRegistry {
                         continue;
                     const def = parseAgentDefinition(readFileSync(full, "utf8"), entry);
                     def.source = source;
+                    if (pluginName)
+                        def.pluginName = pluginName;
                     def.filePath = full;
                     // A later dir overriding an earlier one. Carry forward the shadowed
                     // sources (the prev def's own source + anything it already shadowed)

package/dist/agent/agent-definition.d.ts

@@ -10,10 +10,25 @@ export interface AgentDefinition {
     maxTurns?: number;
     /** Optional tool allowlist. Undefined → inherit parent's full tool set. */
     tools?: string[];
+    /**
+     * Optional skill allowlist. Undefined → inherit the parent's full skill
+     * pool (every non-disabled skill in the project). When set, the sub-agent
+     * physically only sees these skills: they're the only ones listed in its
+     * system prompt and the only ones it may invoke. Empty array → no skills.
+     */
+    skills?: string[];
     /** Markdown body — becomes the child Engine's appendSystemPrompt. */
     systemPrompt: string;
     /** Where this def was loaded from. Runtime-only; never serialized. */
     source?: "project" | "user" | "plugin";
+    /**
+     * Owning plugin name when source === "plugin" (e.g. "mimi-video"). Runtime-
+     * only; never serialized. Used to namespace this agent's bare skill
+     * allowlist into `<pluginName>:<skill>` at spawn time, since a plugin's
+     * frontmatter references its own skills by bare name (CC convention) but
+     * the scanner registers them namespaced. Undefined for project/user agents.
+     */
+    pluginName?: string;
     /** Absolute path of the file it came from. Runtime-only. */
     filePath?: string;
     /** True when this def shadows a same-named def from a lower-priority dir. */

package/dist/agent/agent-definition.js

@@ -1,4 +1,23 @@
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+/**
+ * Normalize a frontmatter `tools:` / `skills:` value into a string[].
+ * Accepts both a YAML list (`[a, b]`) and a comma/whitespace-separated
+ * string (`a, b`) — CC-lineage agent files use either form. Returns
+ * undefined when the field is absent or not a usable shape, so the caller
+ * keeps the "inherit parent" default.
+ */
+function normalizeNameList(value) {
+    if (Array.isArray(value)) {
+        return value.filter((t) => typeof t === "string");
+    }
+    if (typeof value === "string") {
+        return value
+            .split(/[,\s]+/)
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    return undefined;
+}
 /**
  * Parse a Markdown agent-definition file (YAML frontmatter + body).
  * Pure: no filesystem access. `sourceName` is only used in error messages.
@@ -31,9 +50,12 @@ export function parseAgentDefinition(raw, sourceName) {
         def.model = fm.model.trim();
     if (typeof fm.maxTurns === "number")
         def.maxTurns = fm.maxTurns;
-    if (Array.isArray(fm.tools)) {
-        def.tools = fm.tools.filter((t) => typeof t === "string");
-    }
+    const tools = normalizeNameList(fm.tools);
+    if (tools !== undefined)
+        def.tools = tools;
+    const skills = normalizeNameList(fm.skills);
+    if (skills !== undefined)
+        def.skills = skills;
     return def;
 }
 /**
@@ -54,6 +76,8 @@ export function serializeAgentDefinition(def) {
         fm.maxTurns = def.maxTurns;
     if (def.tools !== undefined)
         fm.tools = def.tools;
+    if (def.skills !== undefined)
+        fm.skills = def.skills;
     const yaml = stringifyYaml(fm).trimEnd();
     return `---\n${yaml}\n---\n${def.systemPrompt}\n`;
 }

package/dist/arena/context/context-tools.js

@@ -6,9 +6,9 @@
  * to prevent command injection. File paths are validated against the
  * repository boundary to prevent path traversal.
  */
-import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { resolve, join } from "node:path";
+import { resolve, join, dirname, basename } from "node:path";
 import { isWithinRoot } from "./within-root.js";
 export const MAX_TOOL_RESULT = 15_000; // chars per tool call
 // 5 was too generous for thinking-mode models — they'd spend the
@@ -113,7 +113,41 @@ export function executeContextTool(tc) {
  */
 function validatePath(filePath) {
     const resolved = resolve(filePath);
-    return isWithinRoot(REPO_ROOT, resolved) ? resolved : null;
+    // Realpath both sides so a symlink planted inside the repo that points OUTSIDE
+    // can't pass a lexical containment check (isWithinRoot assumes resolved input
+    // and won't catch a link escape on its own). Matches fs-service's discipline.
+    // Reads are read-only, but a contained-looking symlink would still leak an
+    // out-of-repo file into arena context. Fall back to the lexical check when the
+    // target doesn't exist yet (a read of a missing file fails downstream anyway).
+    let realRoot;
+    try {
+        realRoot = realpathSync(REPO_ROOT);
+    }
+    catch {
+        realRoot = REPO_ROOT;
+    }
+    let realTarget;
+    try {
+        realTarget = realpathSync(resolved);
+    }
+    catch {
+        // Target doesn't exist yet. Compare REAL-vs-REAL by resolving the existing
+        // parent dir's realpath and rejoining the missing leaf — comparing realRoot
+        // (a real path) against a lexical `resolved` would false-reject valid files
+        // whenever REPO_ROOT (or any ancestor) is reached through a symlink.
+        let realParent;
+        try {
+            realParent = realpathSync(dirname(resolved));
+        }
+        catch {
+            // Parent missing too — no realpath available; fall back to lexical-vs-lexical
+            // so both operands share the same (unresolved) mode.
+            return isWithinRoot(resolve(REPO_ROOT), resolved) ? resolved : null;
+        }
+        const candidate = join(realParent, basename(resolved));
+        return isWithinRoot(realRoot, candidate) ? candidate : null;
+    }
+    return isWithinRoot(realRoot, realTarget) ? realTarget : null;
 }
 function executeReadFile(args) {
     const filePath = args.path;
@@ -124,7 +158,16 @@ function executeReadFile(args) {
     const raw = readFileSync(filePath, "utf-8");
     const lines = raw.split("\n");
     const offset = Math.max(0, (args.offset ?? 1) - 1);
-    const limit = args.limit ?? 200;
+    // Guard `limit` before slicing: a negative limit makes lines.slice count
+    // "from the end" and silently drop the file's tail (reader thinks the file is
+    // shorter). A missing/NaN limit falls back to the default; a non-positive
+    // limit reads nothing.
+    const rawLimit = args.limit;
+    const limit = rawLimit === undefined || !Number.isFinite(rawLimit)
+        ? 200
+        : rawLimit > 0
+            ? Math.floor(rawLimit)
+            : 0;
     const slice = lines.slice(offset, offset + limit);
     const numbered = slice.map((l, i) => `${offset + i + 1}\t${l}`).join("\n");
     return truncateResult(numbered);

package/dist/arena/ledger.js

@@ -68,11 +68,16 @@ export class ArenaLedger {
     }
     appendChallenge(challenge) {
         this.ledger.challenges.push(challenge);
-        // Also add to the claim's challenges array
+        // Also add to the claim's challenges array. If the claimId doesn't resolve
+        // the challenge still lives in ledger.challenges but is invisible to any
+        // code reading claim.challenges directly — surface that inconsistency.
         const claim = this.index.claimsById.get(challenge.claimId);
         if (claim) {
             claim.challenges.push(challenge);
         }
+        else {
+            logger.warn("arena.challenge_for_unknown_claim", { claimId: challenge.claimId });
+        }
         this.checkGrowth();
         // Register any requested checks
         if (challenge.requestedChecks) {
@@ -94,6 +99,9 @@ export class ArenaLedger {
         if (claim) {
             claim.adjudication = adjudication;
         }
+        else {
+            logger.warn("arena.adjudication_for_unknown_claim", { claimId: adjudication.claimId });
+        }
     }
     // ─── Query operations ───────────────────────────────────────
     /**

package/dist/arena/strategies/utils.d.ts

@@ -1,9 +1,6 @@
 /** Shared utilities for arena strategy implementations. */
 import type { ArenaBaseContext, FindingReview, ParticipantReport, ArenaConsensus, ArenaRoadmapPhaseDetail, ClaimRecord, ClaimChallenge, ClaimAdjudication, ClaimStatusSummary, DebateTurn, RoundResearchDigest } from "../types.js";
-/** Extract JSON from text that might have markdown fences or surrounding text */
-export declare function extractJSON(text: string): string;
-/** Extract a JSON array from text */
-export declare function extractJSONArray(text: string): string;
+export { extractJSON, extractJSONArray } from "../../utils/json.js";
 /** Format base context into a readable text block for LLM prompts */
 export declare function formatBaseContext(ctx: ArenaBaseContext): string;
 /** Format participant reports for cross-review or consensus prompts */

package/dist/arena/strategies/utils.js

@@ -22,90 +22,13 @@ function sanitizeForPrompt(text) {
         .replace(/^(?:IGNORE|DISREGARD|FORGET|OVERRIDE|SYSTEM|INSTRUCTION)[:\s].*/gim, "")
         .slice(0, 3000);
 }
-/** Extract JSON from text that might have markdown fences or surrounding text */
-export function extractJSON(text) {
-    // Try fenced code blocks — use GREEDY match to handle nested backticks
-    const fenced = text.match(/```(?:json)?\s*\n([\s\S]*)\n\s*```/);
-    if (fenced)
-        return fenced[1].trim();
-    // Try to find the outermost { ... } pair with balanced braces
-    const start = text.indexOf("{");
-    if (start !== -1) {
-        let depth = 0;
-        let inString = false;
-        let escape = false;
-        for (let i = start; i < text.length; i++) {
-            const ch = text[i];
-            if (escape) {
-                escape = false;
-                continue;
-            }
-            if (ch === "\\") {
-                escape = true;
-                continue;
-            }
-            if (ch === '"') {
-                inString = !inString;
-                continue;
-            }
-            if (inString)
-                continue;
-            if (ch === "{")
-                depth++;
-            else if (ch === "}") {
-                depth--;
-                if (depth === 0)
-                    return text.slice(start, i + 1);
-            }
-        }
-        // Unbalanced — return from start to end as best effort
-        return text.slice(start);
-    }
-    return text;
-}
-/** Extract a JSON array from text */
-export function extractJSONArray(text) {
-    const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
-    if (fenced)
-        return fenced[1].trim();
-    // Return the FIRST balanced top-level array. A greedy /\[[\s\S]*\]/ spanned
-    // to the last ']', merging two arrays (or trailing prose) into one invalid
-    // blob. Scan for bracket balance, ignoring brackets inside strings.
-    const balanced = firstBalancedArray(text);
-    if (balanced)
-        return balanced;
-    return text;
-}
-function firstBalancedArray(text) {
-    const start = text.indexOf("[");
-    if (start === -1)
-        return undefined;
-    let depth = 0;
-    let inString = false;
-    let escaped = false;
-    for (let i = start; i < text.length; i++) {
-        const ch = text[i];
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if (ch === "\\")
-                escaped = true;
-            else if (ch === '"')
-                inString = false;
-            continue;
-        }
-        if (ch === '"')
-            inString = true;
-        else if (ch === "[")
-            depth++;
-        else if (ch === "]") {
-            depth--;
-            if (depth === 0)
-                return text.slice(start, i + 1);
-        }
-    }
-    return undefined; // unbalanced
-}
+// extractJSON / extractJSONArray are generic JSON extractors with no Arena
+// dependency. They moved to utils/json.ts so non-Arena consumers (e.g.
+// services/memory-orchestrator) can use them without importing this Arena
+// module — that import made Arena a dependency of a core service. Re-exported
+// here for back-compat with Arena's own callers and the existing test.
+export { extractJSON, extractJSONArray } from "../../utils/json.js";
+import { extractJSON, extractJSONArray } from "../../utils/json.js";
 /** Format base context into a readable text block for LLM prompts */
 export function formatBaseContext(ctx) {
     const sections = [];

package/dist/automation/cron-expr.d.ts

@@ -18,6 +18,16 @@ export interface ParsedCron {
     daysOfMonth: Set<number>;
     months: Set<number>;
     daysOfWeek: Set<number>;
+    /**
+     * Whether the dayOfMonth / dayOfWeek FIELD was restricted (anything other
+     * than a bare "*"). Vixie-cron semantics: when BOTH day fields are
+     * restricted, a tick matches if EITHER matches (OR); when only one is
+     * restricted, the "*" one is ignored and the restricted one governs. We
+     * can't recover this from the value Set alone ("*" and an explicit full
+     * range both expand to the full set), so we capture it at parse time.
+     */
+    domRestricted: boolean;
+    dowRestricted: boolean;
 }
 /** Cheap check: is this string a 5-field cron expression (vs an interval like "5m")? */
 export declare function isCronExpression(s: string): boolean;

package/dist/automation/cron-expr.js

@@ -76,6 +76,10 @@ export function parseCronExpression(expr) {
         daysOfMonth: parseField(parts[2], SPECS[2]),
         months: parseField(parts[3], SPECS[3]),
         daysOfWeek: parseField(parts[4], SPECS[4]),
+        // A bare "*" is unrestricted; anything else (a number, range, list, or even
+        // "*/n") restricts the field for the OR rule below.
+        domRestricted: parts[2].trim() !== "*",
+        dowRestricted: parts[4].trim() !== "*",
     };
 }
 // Cache one formatter per timezone — constructing Intl.DateTimeFormat is costly.
@@ -123,11 +127,25 @@ function wallClockInZone(ms, timeZone) {
     };
 }
 function matches(cron, wc) {
-    return (cron.minutes.has(wc.minute) &&
-        cron.hours.has(wc.hour) &&
-        cron.daysOfMonth.has(wc.dayOfMonth) &&
-        cron.months.has(wc.month) &&
-        cron.daysOfWeek.has(wc.dayOfWeek));
+    if (!cron.minutes.has(wc.minute))
+        return false;
+    if (!cron.hours.has(wc.hour))
+        return false;
+    if (!cron.months.has(wc.month))
+        return false;
+    // Day-of-month vs day-of-week per Vixie/POSIX cron:
+    //   - both restricted → match if EITHER matches (OR)
+    //   - only one restricted → that one governs (the "*" one is ignored)
+    //   - neither restricted → matches every day
+    const domHit = cron.daysOfMonth.has(wc.dayOfMonth);
+    const dowHit = cron.daysOfWeek.has(wc.dayOfWeek);
+    if (cron.domRestricted && cron.dowRestricted)
+        return domHit || dowHit;
+    if (cron.domRestricted)
+        return domHit;
+    if (cron.dowRestricted)
+        return dowHit;
+    return true;
 }
 const MINUTE_MS = 60_000;
 // ~2 years of minutes — bounds the search for an unsatisfiable expression.

package/dist/automation/runner.d.ts

@@ -18,6 +18,7 @@ import type { CronJob } from "./scheduler.js";
 import type { CronScheduler } from "./scheduler.js";
 import type { PermissionMode } from "../types.js";
 import type { ApprovalBackend } from "../tool-system/permission.js";
+import type { SandboxMode } from "../tool-system/sandbox/index.js";
 /** What the executor hands to the run backend for one fired job. */
 export interface CronRunRequest {
     job: CronJob;
@@ -27,6 +28,11 @@ export interface CronRunRequest {
     permissionMode: PermissionMode;
     /** Approval backend the run must install (resolved from the job's tier). */
     approvalBackend: ApprovalBackend;
+    /** Sandbox mode the run should confine writes/shell to (resolved from the
+     *  job's tier). The host runner must forward this to `Engine({ sandbox })`
+     *  so even a `full` tier can't escape the workspace — defense in depth on
+     *  top of the approval backend. */
+    sandboxMode: SandboxMode;
     /** Abort signal for the run — tripped by `CronScheduler.abort(jobId)` when
      *  the run must be cancelled mid-flight (e.g. the user deletes its session
      *  while it's still executing). Forward to `Engine.run({ signal })`. */
@@ -35,16 +41,27 @@ export interface CronRunRequest {
 export interface CronRunResult {
     text: string;
     reason: string;
+    /**
+     * When present, this fire hit a PERMANENT failure that will recur every tick
+     * (e.g. a `resumeSessionId` whose session was deleted). The scheduler should
+     * auto-disable the job with `stop.reason` rather than silently retrying
+     * forever. Absent = transient/normal outcome; keep scheduling.
+     */
+    stop?: {
+        reason: string;
+    };
 }
 /** The pluggable run backend. Production wires this to a headless Engine run;
  *  tests pass a stub. Phase 5 will swap this for a RunManager.submit() path. */
 export type CronRunner = (req: CronRunRequest) => Promise<CronRunResult>;
 /**
  * Install the cron executor. After this call, a fired job invokes `runner`
- * with a run request whose permission tier comes from the job. Errors from
- * `runner` are swallowed by the
- * scheduler's existing try/catch (scheduler.ts) so one bad run never stops
- * future ticks — we still log here so failures are visible.
+ * with a run request whose permission tier comes from the job. A thrown error
+ * is logged (`logCronFailure`) and re-thrown so the scheduler's catch records
+ * stats and keeps ticking — one transient bad run never stops future ticks. A
+ * PERMANENT failure the runner flags via `result.stop` (e.g. a resume target
+ * whose session was deleted) auto-disables the job with that reason, so it
+ * stops silently retrying forever.
  */
 export declare function bindCronToEngine(scheduler: CronScheduler, runner: CronRunner): void;
 /** Minimal structural view of RunManager.submit the executor needs. */

package/dist/automation/runner.js

@@ -16,12 +16,30 @@
  */
 import { AUTOMATION_RUN_SOURCE } from "../run/EngineRunner.js";
 import { resolveWritePolicy } from "./write-policy.js";
+import { logger } from "../logging/logger.js";
+/**
+ * Log a cron executor failure, then re-throw so the scheduler's own try/catch
+ * still records run stats and keeps ticking. Without this the failure was
+ * silently swallowed (the scheduler catch is empty) — a job could fail every
+ * fire with zero trace, which is the exact opposite of what the executor
+ * docstrings claimed ("we still log here so failures are visible").
+ */
+function logCronFailure(job, err) {
+    logger.warn("cron.executor_failed", {
+        cat: "automation",
+        jobId: job.id,
+        jobName: job.name,
+        error: err instanceof Error ? err.message : String(err),
+    });
+}
 /**
  * Install the cron executor. After this call, a fired job invokes `runner`
- * with a run request whose permission tier comes from the job. Errors from
- * `runner` are swallowed by the
- * scheduler's existing try/catch (scheduler.ts) so one bad run never stops
- * future ticks — we still log here so failures are visible.
+ * with a run request whose permission tier comes from the job. A thrown error
+ * is logged (`logCronFailure`) and re-thrown so the scheduler's catch records
+ * stats and keeps ticking — one transient bad run never stops future ticks. A
+ * PERMANENT failure the runner flags via `result.stop` (e.g. a resume target
+ * whose session was deleted) auto-disables the job with that reason, so it
+ * stops silently retrying forever.
  */
 export function bindCronToEngine(scheduler, runner) {
     scheduler.setExecutor(async (job, signal) => {
@@ -31,9 +49,21 @@ export function bindCronToEngine(scheduler, runner) {
             prompt: job.prompt,
             permissionMode: policy.permissionMode,
             approvalBackend: policy.approvalBackend,
+            sandboxMode: policy.sandboxMode,
             signal,
         };
-        await runner(req);
+        try {
+            const result = await runner(req);
+            // A PERMANENT failure the runner flags (e.g. a resume target whose session
+            // was deleted) auto-disables the job so it stops silently retrying.
+            if (result?.stop) {
+                scheduler.disableWithReason(job.id, result.stop.reason);
+            }
+        }
+        catch (err) {
+            logCronFailure(job, err);
+            throw err; // let the scheduler's catch record stats + keep ticking
+        }
     });
 }
 /**
@@ -45,12 +75,18 @@ export function bindCronToEngine(scheduler, runner) {
  */
 export function bindCronToRunManager(scheduler, runManager) {
     scheduler.setExecutor(async (job, _signal) => {
-        const snapshot = await runManager.submit({
-            objective: job.prompt,
-            cwd: job.cwd,
-            metadata: { source: AUTOMATION_RUN_SOURCE, cronJobId: job.id, cronJobName: job.name },
-        });
-        // Record the run id on the job so the UI can link to run history.
-        job.lastRunId = snapshot.runId;
+        try {
+            const snapshot = await runManager.submit({
+                objective: job.prompt,
+                cwd: job.cwd,
+                metadata: { source: AUTOMATION_RUN_SOURCE, cronJobId: job.id, cronJobName: job.name },
+            });
+            // Record the run id on the job so the UI can link to run history.
+            job.lastRunId = snapshot.runId;
+        }
+        catch (err) {
+            logCronFailure(job, err);
+            throw err; // let the scheduler's catch record stats + keep ticking
+        }
     });
 }

package/dist/automation/scheduler.d.ts

@@ -5,6 +5,12 @@
  * with a predefined prompt on schedule.
  */
 import type { CronStore } from "./store.js";
+/**
+ * True when a cron timer fired too far past its scheduled instant to be a
+ * legitimate on-time run — i.e. the host slept through the scheduled time and
+ * the timer fired on wake. Exported for unit testing the sleep/wake guard.
+ */
+export declare function isCronMisfire(scheduledFor: number, now: number): boolean;
 /** Permission tier a scheduled job runs under (Phase 5 enforces write tiers). */
 export type CronPermissionLevel = "read-only" | "workspace-write" | "full";
 export interface CronJob {
@@ -25,12 +31,27 @@ export interface CronJob {
     permissionLevel?: CronPermissionLevel;
     /** RunStore run id of the most recent execution (Phase 2 RunManager path). */
     lastRunId?: string;
+    /** True = one-shot: delete the job after its first real execution so it never
+     *  fires again (e.g. "in 10 minutes, do X once"). */
+    once?: boolean;
+    /** When set, the fired job RESUMES this codeshell chat session instead of
+     *  starting a fresh one: the prompt is appended as a new user turn to that
+     *  session (restored from disk if not in memory), carrying its transcript /
+     *  goal / context. Unset = the default standalone behaviour (new session per
+     *  fire). The host's executor honours this. */
+    resumeSessionId?: string;
+    /** Why the job was auto-disabled (set by `disableWithReason`), e.g. a resume
+     *  target whose session no longer exists. Surfaced in the UI so a silently
+     *  stopped job is explainable; cleared when the job is re-enabled. */
+    disabledReason?: string;
 }
 /** Optional metadata accepted by create(). */
 export interface CreateJobOptions {
     cwd?: string;
     timezone?: string;
     permissionLevel?: CronPermissionLevel;
+    once?: boolean;
+    resumeSessionId?: string;
 }
 /** Fields editable via update(). Any omitted field is left unchanged. */
 export interface UpdateJobPatch {
@@ -119,6 +140,14 @@ export declare class CronScheduler {
     list(): CronJob[];
     get(id: string): CronJob | undefined;
     pause(id: string): boolean;
+    /**
+     * Auto-disable a job and record WHY (e.g. its resume target session was
+     * deleted). Unlike `delete`, the job is retained (enabled=false) so the user
+     * can see it stopped and its reason in the UI, then delete or re-point it.
+     * Mirrors `pause` but also stamps `disabledReason`. Idempotent-safe: a
+     * subsequent `resume()` clears the reason.
+     */
+    disableWithReason(id: string, reason: string): boolean;
     resume(id: string): boolean;
     /**
      * Edit an existing job's fields (name/prompt/schedule/timezone/cwd/
@@ -153,4 +182,13 @@ export declare class CronScheduler {
      */
     private fire;
 }
+/**
+ * Parse a schedule string into milliseconds.
+ * Supports: "30s", "5m", "1h", "1d", or raw (all-digit) milliseconds.
+ *
+ * Throws on anything else rather than silently falling back to a default —
+ * a typo like "5mn" should surface as an error, not quietly schedule every
+ * 10 minutes (review-2026-05-30).
+ */
+export declare function parseSchedule(schedule: string): number;
 export declare const cronScheduler: CronScheduler;