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

package/dist/automation/scheduler.js

@@ -5,6 +5,23 @@
  * with a predefined prompt on schedule.
  */
 import { isCronExpression, parseCronExpression, nextCronTime } from "./cron-expr.js";
+/**
+ * How late a cron-expression timer may fire and still be considered "on time".
+ * A setTimeout that fires within this window of its scheduled instant runs
+ * normally; one that fires later (the host slept through the scheduled time
+ * and the timer fired on wake) is treated as a misfire — skipped and re-armed
+ * to the next occurrence. 90s comfortably clears cron's 60s granularity plus
+ * normal timer jitter, while still catching a multi-minute/hour sleep drift.
+ */
+const CRON_MISFIRE_GRACE_MS = 90_000;
+/**
+ * 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 function isCronMisfire(scheduledFor, now) {
+    return now - scheduledFor > CRON_MISFIRE_GRACE_MS;
+}
 export class CronScheduler {
     jobs = new Map();
     timers = new Map();
@@ -168,10 +185,9 @@ export class CronScheduler {
         }
     }
     persistRunStats(job) {
-        if (!this.store) {
-            this.persist();
+        // No store → nothing to persist. (persist() would also no-op here.)
+        if (!this.store)
             return;
-        }
         try {
             this.store.mutate((jobs) => {
                 const idx = jobs.findIndex((j) => j.id === job.id);
@@ -210,6 +226,8 @@ export class CronScheduler {
                     ...(opts?.cwd !== undefined ? { cwd: opts.cwd } : {}),
                     ...(opts?.timezone !== undefined ? { timezone: opts.timezone } : {}),
                     ...(opts?.permissionLevel !== undefined ? { permissionLevel: opts.permissionLevel } : {}),
+                    ...(opts?.once === true ? { once: true } : {}),
+                    ...(opts?.resumeSessionId !== undefined ? { resumeSessionId: opts.resumeSessionId } : {}),
                 };
                 this.refreshNextRunForDisplay(job);
                 return { jobs: [...jobs, job], result: job };
@@ -229,6 +247,8 @@ export class CronScheduler {
             ...(opts?.cwd !== undefined ? { cwd: opts.cwd } : {}),
             ...(opts?.timezone !== undefined ? { timezone: opts.timezone } : {}),
             ...(opts?.permissionLevel !== undefined ? { permissionLevel: opts.permissionLevel } : {}),
+            ...(opts?.once === true ? { once: true } : {}),
+            ...(opts?.resumeSessionId !== undefined ? { resumeSessionId: opts.resumeSessionId } : {}),
         };
         this.jobs.set(id, job);
         this.arm(job);
@@ -279,6 +299,37 @@ export class CronScheduler {
         this.persist();
         return true;
     }
+    /**
+     * 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, reason) {
+        if (this.store) {
+            const tx = this.store.mutate((jobs) => {
+                let changed = false;
+                const next = jobs.map((j) => {
+                    if (j.id !== id)
+                        return j;
+                    changed = true;
+                    return { ...j, enabled: false, disabledReason: reason };
+                });
+                return { jobs: next, result: changed };
+            });
+            this.reconcileJobs(tx.jobs);
+            return tx.result;
+        }
+        const job = this.jobs.get(id);
+        if (!job)
+            return false;
+        job.enabled = false;
+        job.disabledReason = reason;
+        this.clearTimer(id);
+        this.persist();
+        return true;
+    }
     resume(id) {
         if (this.store) {
             const tx = this.store.mutate((jobs) => {
@@ -287,7 +338,7 @@ export class CronScheduler {
                     if (j.id !== id)
                         return j;
                     changed = true;
-                    const job = { ...j, enabled: true };
+                    const job = { ...j, enabled: true, disabledReason: undefined };
                     this.refreshNextRunForDisplay(job);
                     return job;
                 });
@@ -300,6 +351,7 @@ export class CronScheduler {
         if (!job)
             return false;
         job.enabled = true;
+        job.disabledReason = undefined;
         this.arm(job);
         this.persist();
         return true;
@@ -440,12 +492,27 @@ export class CronScheduler {
             return;
         }
         job.nextRun = next;
+        const scheduledFor = next;
         const delay = Math.max(0, next - Date.now());
         const timer = setTimeout(() => {
-            void this.fire(job, () => {
-                // Re-arm for the following occurrence.
+            // Misfire guard for sleep/wake drift. A setTimeout pauses while the host
+            // sleeps, then fires the instant the machine wakes — which can be hours
+            // off the scheduled wall-clock (observed: a `0 9 * * *` job running at
+            // 06:56 because the Mac did a maintenance wake and the timer fired on
+            // resume). If we wake too far PAST the scheduled instant, this is a
+            // misfire: skip running and re-arm to the next correct occurrence rather
+            // than running at the wrong time.
+            if (isCronMisfire(scheduledFor, Date.now())) {
                 if (job.enabled)
                     this.armCron(job);
+                return;
+            }
+            void this.fire(job, () => {
+                // Re-arm for the following occurrence — but only if the job still
+                // exists. A one-shot (once) job deletes itself in fire()'s finally,
+                // so this closure must not resurrect it via a stale reference.
+                if (job.enabled && this.jobs.has(job.id))
+                    this.armCron(job);
             });
         }, delay);
         this.timers.set(job.id, timer);
@@ -498,6 +565,11 @@ export class CronScheduler {
             this.persistRunStats(job);
             this.running.delete(job.id);
             this.runningControllers.delete(job.id);
+            // One-shot: delete after its first execution so it never fires again.
+            // Done after persistRunStats so the final stats write can't race the
+            // removal; delete() clears the timer + removes from store/in-memory.
+            if (job.once)
+                this.delete(job.id);
             // Unblock any abort() awaiting this run's teardown.
             resolveDone();
         }
@@ -523,15 +595,20 @@ function validateSchedule(schedule, timezone) {
  * a typo like "5mn" should surface as an error, not quietly schedule every
  * 10 minutes (review-2026-05-30).
  */
-function parseSchedule(schedule) {
+export function parseSchedule(schedule) {
     const match = schedule.match(/^(\d+)(s|m|h|d)$/);
     if (match) {
         const value = parseInt(match[1], 10);
-        switch (match[2]) {
-            case "s": return value * 1000;
-            case "m": return value * 60 * 1000;
-            case "h": return value * 60 * 60 * 1000;
-            case "d": return value * 24 * 60 * 60 * 1000;
+        // A zero interval ("0s"/"0m"/…) → 0ms → setInterval(fn, 0) spins
+        // continuously. Reject it (fall through to throw), matching the raw-ms
+        // path's `> 0` guard and the "throw on bad input" contract.
+        if (value > 0) {
+            switch (match[2]) {
+                case "s": return value * 1000;
+                case "m": return value * 60 * 1000;
+                case "h": return value * 60 * 60 * 1000;
+                case "d": return value * 24 * 60 * 60 * 1000;
+            }
         }
     }
     // Raw milliseconds — must be all digits and > 0 (parseInt would otherwise

package/dist/automation/store.js

@@ -113,7 +113,10 @@ export class CronStore {
         throw lastError;
     }
 }
+// Reused across calls — Atomics.wait only reads slot 0, which always stays 0,
+// so a single shared buffer is safe and avoids per-call allocation in the
+// lock-retry loop.
+const SLEEP_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
 function sleepSync(ms) {
-    const signal = new Int32Array(new SharedArrayBuffer(4));
-    Atomics.wait(signal, 0, 0, ms);
+    Atomics.wait(SLEEP_SIGNAL, 0, 0, ms);
 }

package/dist/capability-control/disabled-lists.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Effective disabled-skills/plugins computation — the ONE place that folds a
+ * project's capabilityOverrides (tri-state on/off/inherit) over the global
+ * baseline, plus the no-repo whitelist inversion.
+ *
+ * Extracted from Engine.readDisabledLists because the MCP merge consumers
+ * (engineFactory in the stdio/tcp servers, diskDefaultsFrom hot-reload) were
+ * passing the RAW global `settings.disabledPlugins` to mergePluginMcpServers:
+ * a plugin force-enabled at project level (能力总览 "on") stayed excluded from
+ * the MCP merge because the global list still named it. Every consumer must
+ * fold through here so "project on overrides global off" holds everywhere.
+ */
+import { SettingsManager } from "../settings/manager.js";
+export interface EffectiveDisabledLists {
+    disabledSkills: string[];
+    disabledPlugins: string[];
+    /** Folded from capabilityOverrides.pluginHooks "off" keys (see
+     *  pluginHookKey) — per-hook suppression for plugin-provided hooks. */
+    disabledPluginHooks: string[];
+}
+/**
+ * Compute the effective disabled lists for `cwd`. Never throws — any read
+ * error falls back to empty lists (same contract as Engine.readDisabledLists).
+ */
+export declare function computeEffectiveDisabledLists(sm: SettingsManager, cwd: string | undefined): EffectiveDisabledLists;

package/dist/capability-control/disabled-lists.js

@@ -0,0 +1,57 @@
+/**
+ * Effective disabled-skills/plugins computation — the ONE place that folds a
+ * project's capabilityOverrides (tri-state on/off/inherit) over the global
+ * baseline, plus the no-repo whitelist inversion.
+ *
+ * Extracted from Engine.readDisabledLists because the MCP merge consumers
+ * (engineFactory in the stdio/tcp servers, diskDefaultsFrom hot-reload) were
+ * passing the RAW global `settings.disabledPlugins` to mergePluginMcpServers:
+ * a plugin force-enabled at project level (能力总览 "on") stayed excluded from
+ * the MCP merge because the global list still named it. Every consumer must
+ * fold through here so "project on overrides global off" holds everywhere.
+ */
+import { noRepoDir } from "../settings/manager.js";
+import { scanSkills } from "../skills/scanner.js";
+import { readInstalledPlugins } from "../plugins/installedPlugins.js";
+import { effectiveDisabledList, whitelistDisabledList } from "./overlay.js";
+/**
+ * Compute the effective disabled lists for `cwd`. Never throws — any read
+ * error falls back to empty lists (same contract as Engine.readDisabledLists).
+ */
+export function computeEffectiveDisabledLists(sm, cwd) {
+    try {
+        const settings = sm.get();
+        // Read the project overlay UNMERGED (getForScope), not the merged get(),
+        // so tri-state inheritance survives. No cwd / no overlay → the baseline
+        // is returned unchanged (zero regression).
+        const overrides = cwd
+            ? sm.getForScope("project", cwd).capabilityOverrides
+            : undefined;
+        // no-repo "conversation" scope: INVERT skill/plugin filtering to a
+        // whitelist (default-all-off, only explicit "on" survives). Only this
+        // fixed cwd flips; every real project keeps the denylist below. agent/
+        // mcp/builtin are NOT inverted. See conversation-settings spec §3.
+        if (cwd && cwd === noRepoDir()) {
+            const allSkillNames = scanSkills(cwd).map((s) => s.name);
+            const allPluginNames = Object.keys(readInstalledPlugins().plugins).map((key) => {
+                const at = key.lastIndexOf("@");
+                return at > 0 ? key.slice(0, at) : key;
+            });
+            return {
+                disabledSkills: whitelistDisabledList(allSkillNames, overrides?.skills),
+                disabledPlugins: whitelistDisabledList(allPluginNames, overrides?.plugins),
+                // pluginHooks is NOT inverted (like agents/mcp/builtin): there is no
+                // global per-hook baseline, only project-level "off" keys.
+                disabledPluginHooks: effectiveDisabledList([], overrides?.pluginHooks),
+            };
+        }
+        return {
+            disabledSkills: effectiveDisabledList(settings.disabledSkills ?? [], overrides?.skills),
+            disabledPlugins: effectiveDisabledList(settings.disabledPlugins ?? [], overrides?.plugins),
+            disabledPluginHooks: effectiveDisabledList([], overrides?.pluginHooks),
+        };
+    }
+    catch {
+        return { disabledSkills: [], disabledPlugins: [], disabledPluginHooks: [] };
+    }
+}

package/dist/capability-control/overlay.d.ts

@@ -30,6 +30,21 @@ export declare function overrideFor(overrides: CapabilityOverrides | undefined,
  * leaves the baseline.
  */
 export declare function effectiveDisabledList(globalDisabled: string[], bucket: Record<string, CapabilityOverride> | undefined): string[];
+/**
+ * Whitelist (opt-in) variant of {@link effectiveDisabledList}, used only for
+ * the no-repo "conversation" scope where skill/plugin default-state is INVERTED:
+ * everything is disabled UNLESS the project override bucket explicitly marks it
+ * `"on"`. This is the opposite of the normal denylist (default-enabled) model.
+ *
+ * Given the full set of installed names and an override bucket:
+ *   - a name explicitly `"on"`  → kept enabled (NOT in the returned list)
+ *   - everything else (`"off"`, inherit/absent, garbage) → disabled (in the list)
+ *
+ * The returned list is the effective disabled list to feed run-time
+ * skill/plugin filtering. Order follows `allInstalledNames`; duplicates are
+ * collapsed.
+ */
+export declare function whitelistDisabledList(allInstalledNames: string[], bucket: Record<string, CapabilityOverride> | undefined): string[];
 /**
  * Fold a project builtin override bucket into the global enabled/disabled
  * builtin-tool lists, producing the lists to feed resolveBuiltinToolNames

package/dist/capability-control/overlay.js

@@ -54,6 +54,33 @@ export function effectiveDisabledList(globalDisabled, bucket) {
     }
     return [...disabled];
 }
+/**
+ * Whitelist (opt-in) variant of {@link effectiveDisabledList}, used only for
+ * the no-repo "conversation" scope where skill/plugin default-state is INVERTED:
+ * everything is disabled UNLESS the project override bucket explicitly marks it
+ * `"on"`. This is the opposite of the normal denylist (default-enabled) model.
+ *
+ * Given the full set of installed names and an override bucket:
+ *   - a name explicitly `"on"`  → kept enabled (NOT in the returned list)
+ *   - everything else (`"off"`, inherit/absent, garbage) → disabled (in the list)
+ *
+ * The returned list is the effective disabled list to feed run-time
+ * skill/plugin filtering. Order follows `allInstalledNames`; duplicates are
+ * collapsed.
+ */
+export function whitelistDisabledList(allInstalledNames, bucket) {
+    const disabled = [];
+    const seen = new Set();
+    for (const name of allInstalledNames) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        if (bucket?.[name] === "on")
+            continue; // explicit allow → stays enabled
+        disabled.push(name);
+    }
+    return disabled;
+}
 /**
  * Fold a project builtin override bucket into the global enabled/disabled
  * builtin-tool lists, producing the lists to feed resolveBuiltinToolNames

package/dist/cc-orchestrator/agent-adapter.d.ts

@@ -0,0 +1,50 @@
+export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions";
+export interface BuildArgsOpts {
+    prompt: string;
+    resumeSessionId?: string;
+    permissionMode: PermissionMode;
+    cwd: string;
+}
+export interface ParsedResult {
+    sessionId: string;
+    finalText: string;
+    isError: boolean;
+}
+export interface AgentAdapter {
+    /** Display name, e.g. "claude" / "codex". */
+    kind: string;
+    /** Build the CLI argv (command itself excluded). */
+    buildArgs(opts: BuildArgsOpts): string[];
+    /** Reduce collected stream-json output lines to {sessionId, finalText, isError}. */
+    parseResult(lines: string[]): ParsedResult;
+    /**
+     * When true, the prompt is fed over stdin instead of being passed in argv.
+     * claude takes the prompt as `-p <prompt>` (argv) so leaves this unset; codex
+     * `exec` reads the prompt from stdin (its argv ends with a bare `-`).
+     */
+    promptViaStdin?: boolean;
+}
+/**
+ * Soft cost-guard appended to a driven CC's system prompt. Workflow fans out a
+ * fleet of agents and is the main token sink; we ask CC to surface intent and
+ * get a go-ahead before running one, so a human can intervene (rooms) and the
+ * model stays cost-aware even where Workflow isn't hard-disabled. Shared so the
+ * room's resident process can reuse the exact same wording.
+ */
+export declare const CC_COST_GUARD_PROMPT: string;
+export declare const claudeAdapter: AgentAdapter;
+/**
+ * Drives the OpenAI Codex CLI via `codex exec`. Mirrors claudeAdapter but for
+ * codex's different surface:
+ *  - prompt is fed over STDIN (argv ends with a bare `-`), not argv → promptViaStdin
+ *  - permission is a spawn-time SANDBOX choice, not a per-tool approval loop:
+ *      default        → --sandbox read-only      (codex can read, not write)
+ *      acceptEdits    → --sandbox workspace-write (codex can write the workspace)
+ *      bypassPermissions → --dangerously-bypass-approvals-and-sandbox (full auto)
+ *    (Matches the only model codex supports — same choice the `wand` tool makes;
+ *    codex has no `--permission-prompt-tool stdio` equivalent.)
+ *  - JSONL event shape differs: session id is `thread.started`.thread_id, the
+ *    final answer is the last `item.completed` of item.type "agent_message", and
+ *    failure is `turn.failed` / `error` events (no `is_error` flag).
+ */
+export declare const codexAdapter: AgentAdapter;

package/dist/cc-orchestrator/agent-adapter.js

@@ -0,0 +1,133 @@
+/**
+ * Soft cost-guard appended to a driven CC's system prompt. Workflow fans out a
+ * fleet of agents and is the main token sink; we ask CC to surface intent and
+ * get a go-ahead before running one, so a human can intervene (rooms) and the
+ * model stays cost-aware even where Workflow isn't hard-disabled. Shared so the
+ * room's resident process can reuse the exact same wording.
+ */
+export const CC_COST_GUARD_PROMPT = "Cost guard: before invoking the Workflow tool (which fans out many agents and " +
+    "burns a lot of tokens), first state in one short message what workflow you intend " +
+    "to run and why, and ask for a go-ahead — do NOT launch a Workflow unprompted. A " +
+    "single Task sub-agent is fine without asking.";
+export const claudeAdapter = {
+    kind: "claude",
+    buildArgs(opts) {
+        // -p (print/headless) + stream-json REQUIRES --verbose (verified).
+        const args = ["-p", opts.prompt, "--output-format", "stream-json", "--verbose"];
+        if (opts.resumeSessionId)
+            args.push("--resume", opts.resumeSessionId);
+        // Hard-disallow Workflow: driving CC unattended (esp. bypassPermissions),
+        // CC's Workflow tool fans out a FLEET of agents — the real token-burn culprit
+        // (user: "自动了 2 个 workflow token 就烧没了"). A single Task (one sub-agent)
+        // is cheap, so it stays ALLOWED. (We earlier disallowed Task by mistake;
+        // Workflow is the one that fans out.) Disabling outright is cleaner than an
+        // approval round-trip this path doesn't have.
+        args.push("--disallowedTools", "Workflow");
+        // Soft constraint (belt-and-suspenders + carries to rooms where Workflow is
+        // allowed): ask CC to check in before expensive multi-agent work.
+        args.push("--append-system-prompt", CC_COST_GUARD_PROMPT);
+        args.push("--permission-mode", opts.permissionMode);
+        return args;
+    },
+    parseResult(lines) {
+        let sessionId = "";
+        let finalText = "";
+        let isError = false;
+        for (const line of lines) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            let d;
+            try {
+                d = JSON.parse(t);
+            }
+            catch {
+                continue;
+            }
+            if (typeof d.session_id === "string" && !sessionId)
+                sessionId = d.session_id;
+            if (d.type === "result") {
+                if (typeof d.session_id === "string")
+                    sessionId = d.session_id;
+                if (typeof d.result === "string")
+                    finalText = d.result;
+                isError = Boolean(d.is_error);
+            }
+        }
+        return { sessionId, finalText, isError };
+    },
+};
+/**
+ * Drives the OpenAI Codex CLI via `codex exec`. Mirrors claudeAdapter but for
+ * codex's different surface:
+ *  - prompt is fed over STDIN (argv ends with a bare `-`), not argv → promptViaStdin
+ *  - permission is a spawn-time SANDBOX choice, not a per-tool approval loop:
+ *      default        → --sandbox read-only      (codex can read, not write)
+ *      acceptEdits    → --sandbox workspace-write (codex can write the workspace)
+ *      bypassPermissions → --dangerously-bypass-approvals-and-sandbox (full auto)
+ *    (Matches the only model codex supports — same choice the `wand` tool makes;
+ *    codex has no `--permission-prompt-tool stdio` equivalent.)
+ *  - JSONL event shape differs: session id is `thread.started`.thread_id, the
+ *    final answer is the last `item.completed` of item.type "agent_message", and
+ *    failure is `turn.failed` / `error` events (no `is_error` flag).
+ */
+export const codexAdapter = {
+    kind: "codex",
+    promptViaStdin: true,
+    buildArgs(opts) {
+        const args = ["exec", "--json", "--color", "never", "--skip-git-repo-check"];
+        if (opts.permissionMode === "bypassPermissions") {
+            args.push("--dangerously-bypass-approvals-and-sandbox");
+        }
+        else {
+            args.push("--sandbox", opts.permissionMode === "acceptEdits" ? "workspace-write" : "read-only");
+        }
+        // `resume <thread_id>` continues a prior codex session; the trailing `-`
+        // tells codex exec to read the prompt from stdin (we feed it there).
+        if (opts.resumeSessionId)
+            args.push("resume", opts.resumeSessionId, "-");
+        else
+            args.push("-");
+        return args;
+    },
+    parseResult(lines) {
+        let sessionId = "";
+        let finalText = "";
+        let isError = false;
+        const errorBits = [];
+        for (const line of lines) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            let d;
+            try {
+                d = JSON.parse(t);
+            }
+            catch {
+                continue;
+            }
+            if (d.type === "thread.started" && typeof d.thread_id === "string")
+                sessionId = d.thread_id;
+            else if (d.type === "item.completed" && d.item?.type === "agent_message" && typeof d.item.text === "string") {
+                finalText = d.item.text; // keep the LAST agent_message
+            }
+            else if (d.type === "turn.failed") {
+                isError = true;
+                const msg = d.error?.message ?? d.error ?? "turn failed";
+                if (typeof msg === "string")
+                    errorBits.push(msg);
+            }
+            else if (d.type === "error") {
+                isError = true;
+                const msg = d.message ?? d.error?.message ?? d.error ?? "error";
+                if (typeof msg === "string")
+                    errorBits.push(msg);
+            }
+        }
+        // On failure, surface the error text as finalText (so the caller/notification
+        // shows *why*), preferring it over any partial agent_message.
+        if (isError && errorBits.length)
+            finalText = errorBits.join("\n");
+        return { sessionId, finalText, isError };
+    },
+};

package/dist/cc-orchestrator/cc-capability.d.ts

@@ -0,0 +1,19 @@
+export interface CCAvailability {
+    available: boolean;
+    command: string;
+    version?: string;
+    reason?: "not-found" | "not-executable";
+}
+/** macOS GUI-launched Electron has a minimal PATH (no Homebrew). Prepend common
+ *  CLI dirs so `claude` resolves. Mirrors resident-agent.ts's fix. */
+export declare function pathWithCommonBins(env?: NodeJS.ProcessEnv): string;
+export type ProbeRunner = (command: string) => Promise<{
+    ok: boolean;
+    stdout: string;
+}>;
+/** Probe a CLI's availability. Injectable runner for tests. */
+export declare function probeCli(command: string, runner?: ProbeRunner): Promise<CCAvailability>;
+/** Cached probe; pass force=true to re-detect (user installed CLI mid-session). */
+export declare function probeClaudeCli(force?: boolean): Promise<CCAvailability>;
+/** Cached probe for the OpenAI Codex CLI; force=true re-detects. */
+export declare function probeCodexCli(force?: boolean): Promise<CCAvailability>;

package/dist/cc-orchestrator/cc-capability.js

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+import { delimiter } from "node:path";
+/** macOS GUI-launched Electron has a minimal PATH (no Homebrew). Prepend common
+ *  CLI dirs so `claude` resolves. Mirrors resident-agent.ts's fix. */
+export function pathWithCommonBins(env = process.env) {
+    const extra = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+    const current = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const merged = [];
+    for (const dir of [...extra, ...current])
+        if (!merged.includes(dir))
+            merged.push(dir);
+    return merged.join(delimiter);
+}
+/** Default runner: `<command> --version` with PATH fix. */
+const defaultRunner = (command) => new Promise((resolve, reject) => {
+    const child = spawn(command, ["--version"], {
+        env: { ...process.env, PATH: pathWithCommonBins() },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    child.stdout?.on("data", (c) => (stdout += String(c)));
+    child.on("error", reject);
+    child.on("exit", (code) => resolve({ ok: code === 0, stdout }));
+});
+/** Probe a CLI's availability. Injectable runner for tests. */
+export async function probeCli(command, runner = defaultRunner) {
+    try {
+        const { ok, stdout } = await runner(command);
+        if (!ok)
+            return { available: false, command, reason: "not-executable" };
+        return { available: true, command, version: stdout.trim() || undefined };
+    }
+    catch (err) {
+        const code = err.code;
+        return { available: false, command, reason: code === "ENOENT" ? "not-found" : "not-executable" };
+    }
+}
+let cached;
+/** Cached probe; pass force=true to re-detect (user installed CLI mid-session). */
+export async function probeClaudeCli(force = false) {
+    if (cached && !force)
+        return cached;
+    cached = await probeCli("claude");
+    return cached;
+}
+let cachedCodex;
+/** Cached probe for the OpenAI Codex CLI; force=true re-detects. */
+export async function probeCodexCli(force = false) {
+    if (cachedCodex && !force)
+        return cachedCodex;
+    cachedCodex = await probeCli("codex");
+    return cachedCodex;
+}

package/dist/cc-orchestrator/codex-session-discovery.d.ts

@@ -0,0 +1,24 @@
+import type { DiscoveredSession, DiscoverOptions } from "./session-discovery.js";
+/**
+ * Discover codex CLI sessions for a given `cwd`, mirroring the claude-side
+ * `discoverSessions` but for codex's storage layout, which is fundamentally
+ * different:
+ *
+ *   ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl
+ *
+ * Unlike claude (one dir per project), codex stores rollouts by DATE, not by
+ * cwd. The cwd lives INSIDE the file: the first line is a `session_meta` event
+ * whose `payload` carries `{ id, cwd, timestamp }` (`id` is the thread id we
+ * resume by). So discovery means: walk every rollout file, read just its first
+ * line to learn its cwd, and keep the ones matching the requested project.
+ *
+ * Codex rollout files can be large, so we deliberately AVOID `readFileSync` on
+ * the whole file (the claude version reads the whole file because claude
+ * sessions are small). We read the first line for the meta, and — only for a
+ * matching file — read a bounded prefix to find the first real user message for
+ * the title. Returns the same `DiscoveredSession` shape so the UI is CLI-blind.
+ */
+export declare function discoverCodexSessions(cwd: string, codexHome?: string, opts?: DiscoverOptions): DiscoveredSession[];
+/** Count codex sessions for `cwd` (reads first-line meta of every rollout; no
+ *  window). Used so the UI knows whether a bounded list left older ones hidden. */
+export declare function countCodexSessions(cwd: string, codexHome?: string): number;