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

package/dist/run/RunLock.js

@@ -13,18 +13,33 @@ import { logger } from "../logging/logger.js";
 export class RunLock {
     runsDir;
     staleMs;
+    targetWaitMs;
+    targetPollMs;
     releaseFns = new Map();
     constructor(config) {
         this.runsDir = config?.runsDir ?? join(homedir(), ".code-shell", "runs");
         this.staleMs = config?.staleMs ?? 60_000;
+        this.targetWaitMs = config?.targetWaitMs ?? 2_000;
+        this.targetPollMs = config?.targetPollMs ?? 10;
     }
     /**
-     * Acquire a lock for a run. Returns true if acquired, false if already held.
+     * Acquire a lock for a run. Missing target and held-lock failures are
+     * intentionally distinct so callers don't silently abandon a run as "locked"
+     * when the real issue is a bad/mismatched run store path.
+     *
+     * Race note: if the queue reaches acquire() before the file is visible, a
+     * short wait bridges that gap. Only a proper-lockfile conflict is "locked".
      */
     async acquire(runId) {
         const lockTarget = this.lockTarget(runId);
-        if (!existsSync(lockTarget))
-            return false;
+        if (!(await this.waitForTarget(lockTarget))) {
+            logger.warn("run.lock.target_missing", { runId, lockTarget });
+            return {
+                acquired: false,
+                reason: "missing_target",
+                message: `Lock target did not appear: ${lockTarget}`,
+            };
+        }
         try {
             const release = await lock(lockTarget, {
                 stale: this.staleMs,
@@ -32,12 +47,39 @@ export class RunLock {
             });
             this.releaseFns.set(runId, release);
             logger.info("run.lock.acquired", { runId });
-            return true;
+            return { acquired: true };
         }
-        catch {
-            // Lock already held by another process
-            return false;
+        catch (err) {
+            const e = err;
+            logger.warn("run.lock.conflict", {
+                runId,
+                lockTarget,
+                code: e?.code,
+                message: e?.message,
+                alreadyHeldByThisInstance: this.releaseFns.has(runId),
+            });
+            return {
+                acquired: false,
+                reason: "locked",
+                code: e?.code,
+                message: e?.message,
+            };
+        }
+    }
+    /**
+     * Wait (up to ~targetWaitMs) for the lock target file to exist, polling on a
+     * short interval. Returns true once present, false if it never appears
+     * within the window. Bridges the submit→executeRun create race without
+     * blocking meaningfully when the file is already there (first check hits).
+     */
+    async waitForTarget(lockTarget) {
+        const deadline = Date.now() + this.targetWaitMs;
+        while (!existsSync(lockTarget)) {
+            if (Date.now() >= deadline)
+                return false;
+            await new Promise((r) => setTimeout(r, this.targetPollMs));
         }
+        return true;
     }
     /**
      * Release the lock for a run.

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[]>;

package/dist/run/RunManager.js

@@ -33,6 +33,17 @@ export class RunManager {
     abortControllers = new Map();
     /** Active execution handles — used to resolve pending approvals/input while Engine is suspended */
     executionHandles = new Map();
+    /**
+     * 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.
+     */
+    resolvingRuns = new Set();
     constructor(config) {
         this.store = config.store;
         this.queue = new RunQueue({ concurrency: config.concurrency ?? 1 });
@@ -99,6 +110,23 @@ export class RunManager {
     }
     // ─── Resume ────────────────────────────────────────────────────
     async resume(runId, input) {
+        // Serialize resume/cancel decisions per run. Without this, two concurrent
+        // resumes (or resume racing cancel) both pass the status check below —
+        // status stays `waiting_*` until a later `await transition()` — and both
+        // drive transitions / the re-queue path. Reject the late arrival rather
+        // than letting it double-resolve.
+        if (this.resolvingRuns.has(runId)) {
+            throw new Error(`Cannot resume run ${runId}: another resume/cancel is already in progress`);
+        }
+        this.resolvingRuns.add(runId);
+        try {
+            await this.resumeInner(runId, input);
+        }
+        finally {
+            this.resolvingRuns.delete(runId);
+        }
+    }
+    async resumeInner(runId, input) {
         const run = await this.getOrThrow(runId);
         if (run.status !== "waiting_input" &&
             run.status !== "waiting_approval" &&
@@ -137,6 +165,13 @@ export class RunManager {
                 handle.resolveInput(input.userInput);
                 return;
             }
+            // A handle exists (Engine is live and suspended) but the input doesn't
+            // match what it's waiting for — e.g. userInput supplied for a
+            // waiting_approval run. Falling through to Case 2 would re-enqueue a
+            // FRESH execution while the suspended Engine still dangles (duplicate
+            // run + leaked handle). Reject with a clear message instead.
+            throw new Error(`Cannot resume run ${runId}: it is ${run.status} but the provided input does not match ` +
+                `(expected ${run.status === "waiting_approval" ? "approvalDecision" : "userInput"}).`);
         }
         // Case 2: No active handle (process restarted, or blocked state)
         // Re-queue the run for a fresh execution attempt
@@ -293,9 +328,25 @@ export class RunManager {
     async executeRun(runId) {
         const run = await this.getOrThrow(runId);
         // Acquire run lock — prevents concurrent execution by multiple workers
-        const acquired = await this.lock.acquire(runId);
-        if (!acquired) {
-            logger.warn("run.lock.failed", { runId, reason: "already locked by another worker" });
+        const lockResult = await this.lock.acquire(runId);
+        if (!lockResult.acquired) {
+            if (lockResult.reason === "missing_target") {
+                const errorMsg = lockResult.message ?? "Run lock target was missing";
+                run.error = errorMsg;
+                await this.transition(run, "blocked");
+                await this.emitRunEvent(runId, "run_blocked", {
+                    error: errorMsg,
+                    reason: "missing_lock_target",
+                });
+                logger.error("run.lock.target_missing", { runId, error: errorMsg });
+                return;
+            }
+            logger.warn("run.lock.failed", {
+                runId,
+                reason: "already locked by another worker",
+                code: lockResult.code,
+                message: lockResult.message,
+            });
             return;
         }
         // Start heartbeat so crash recovery can detect liveness
@@ -331,6 +382,38 @@ export class RunManager {
                 // Feed events to checkpoint writer and artifact tracker
                 await checkpointWriter.onStreamEvent(event);
                 await artifactTracker.onStreamEvent(event);
+                // Link the run's sessionId the moment the engine resolves it.
+                // session_started fires at run START (engine.ts:1081); without this,
+                // sessionId is only written at completion, so in-flight runs have
+                // sessionId=null on disk and never reach the sidebar import.
+                //
+                // The `!agentId` guard is defensive: the built-in engine already
+                // suppresses sub-agent session_started upstream (engine.ts:830-835),
+                // but a custom RunExecutor could forward sub-agent events — and only
+                // the MAIN run's session should identify the run, never a sub-agent's.
+                if (event.type === "session_started" &&
+                    !event.agentId) {
+                    try {
+                        const run = await this.getOrThrow(runId);
+                        if (run.sessionId !== event.sessionId) {
+                            run.sessionId = event.sessionId;
+                            checkpointWriter.setSessionId(event.sessionId);
+                            await this.store.update(run);
+                            await this.emitRunEvent(runId, "session_linked", {
+                                sessionId: event.sessionId,
+                            });
+                        }
+                    }
+                    catch (linkErr) {
+                        // Don't let a snapshot-write failure abort the run as a swallowed
+                        // unhandled rejection — log and continue; the completion-time link
+                        // is the backstop.
+                        logger.warn("run.session_link_error", {
+                            runId,
+                            error: linkErr instanceof Error ? linkErr.message : String(linkErr),
+                        });
+                    }
+                }
                 // Forward to run subscribers
                 this.notifySubscribers(runId, { type: "engine_stream", event });
             },

package/dist/run/RunQueue.d.ts

@@ -11,6 +11,7 @@ export type RunQueueExecutor = (runId: string) => Promise<void>;
 export declare class RunQueue {
     private readonly concurrency;
     private readonly pending;
+    private readonly pendingSet;
     private readonly active;
     private executor;
     private draining;

package/dist/run/RunQueue.js

@@ -6,7 +6,10 @@
  */
 export class RunQueue {
     concurrency;
+    // `pending` keeps FIFO order; `pendingSet` mirrors its membership for O(1)
+    // dedup/lookup (the array's includes() was O(n)).
     pending = [];
+    pendingSet = new Set();
     active = new Set();
     executor = null;
     draining = false;
@@ -17,15 +20,17 @@ export class RunQueue {
         this.executor = fn;
     }
     enqueue(runId) {
-        if (this.pending.includes(runId) || this.active.has(runId))
+        if (this.pendingSet.has(runId) || this.active.has(runId))
             return;
         this.pending.push(runId);
+        this.pendingSet.add(runId);
         this.drain();
     }
     cancel(runId) {
         const idx = this.pending.indexOf(runId);
         if (idx !== -1) {
             this.pending.splice(idx, 1);
+            this.pendingSet.delete(runId);
             return true;
         }
         return false;
@@ -34,7 +39,7 @@ export class RunQueue {
         return this.active.has(runId);
     }
     isPending(runId) {
-        return this.pending.includes(runId);
+        return this.pendingSet.has(runId);
     }
     get activeCount() {
         return this.active.size;
@@ -57,6 +62,7 @@ export class RunQueue {
             return;
         while (this.active.size < this.concurrency && this.pending.length > 0) {
             const runId = this.pending.shift();
+            this.pendingSet.delete(runId);
             this.active.add(runId);
             this.executor(runId)
                 .catch((err) => {

package/dist/run/factory.d.ts

@@ -18,7 +18,7 @@
  * ```
  */
 import type { LLMConfig, PermissionMode } from "../types.js";
-import type { EngineConfig, EngineHookConfig } from "../engine/engine.js";
+import type { EngineConfig, EngineHookConfig } from "../engine/types.js";
 import type { Evaluator } from "./Evaluator.js";
 import { RunManager } from "./RunManager.js";
 export interface CreateRunManagerOptions {
@@ -56,6 +56,13 @@ export interface CreateRunManagerOptions {
     defaultTags?: string[];
     /** Metadata merged into every submitted run. Submit input wins on conflicts. */
     defaultMetadata?: Record<string, unknown>;
+    /**
+     * Override the approval backend for every run. Used by unattended hosts
+     * (automation/cron) that must auto-decide without a UI — e.g.
+     * `new HeadlessApprovalBackend("approve-read-only")`. When unset, runs use
+     * the interactive run-aware backend.
+     */
+    approvalBackend?: import("../tool-system/permission.js").ApprovalBackend;
 }
 /**
  * Create a fully configured RunManager with one call.

package/dist/run/factory.js

@@ -41,6 +41,7 @@ export function createRunManager(options) {
             customSystemPrompt: options.customSystemPrompt,
             appendSystemPrompt: options.appendSystemPrompt,
             hooks: options.hooks,
+            ...(options.approvalBackend ? { approvalBackend: options.approvalBackend } : {}),
         },
         concurrency: options.concurrency ?? 1,
         runsDir,

package/dist/run/index.d.ts

@@ -9,9 +9,9 @@ export { RunQueue } from "./RunQueue.js";
 export { RunApprovalBackend, createRunAskUserFn, type RunLifecycleHooks, type PendingApproval, type PendingInput, } from "./RunApprovalBackend.js";
 export { CheckpointWriter, type CheckpointWriterConfig } from "./CheckpointWriter.js";
 export { ArtifactTracker, type ArtifactTrackerConfig } from "./ArtifactTracker.js";
-export { RunLock, type RunLockConfig } from "./RunLock.js";
+export { RunLock, type RunLockConfig, type RunLockAcquireResult } from "./RunLock.js";
 export { Heartbeat, type HeartbeatConfig, type HeartbeatData } from "./Heartbeat.js";
 export { NoopEvaluator, CompositeEvaluator, type Evaluator, type EvaluatorResult, type EvaluatorVerdict, type EvaluatorContext, } from "./Evaluator.js";
-export { EngineRunner, type EngineRunnerConfig, type RunExecutionHandle, type RunExecutor, type CustomToolEntry, } from "./EngineRunner.js";
+export { EngineRunner, AUTOMATION_PROMPT_NOTE, AUTOMATION_RUN_SOURCE, type EngineRunnerConfig, type RunExecutionHandle, type RunExecutor, type CustomToolEntry, } from "./EngineRunner.js";
 export { RunManager, type RunManagerConfig } from "./RunManager.js";
 export { createRunManager, type CreateRunManagerOptions } from "./factory.js";

package/dist/run/index.js

@@ -16,7 +16,7 @@ export { Heartbeat } from "./Heartbeat.js";
 // Evaluator
 export { NoopEvaluator, CompositeEvaluator, } from "./Evaluator.js";
 // Runner
-export { EngineRunner, } from "./EngineRunner.js";
+export { EngineRunner, AUTOMATION_PROMPT_NOTE, AUTOMATION_RUN_SOURCE, } from "./EngineRunner.js";
 // Manager
 export { RunManager } from "./RunManager.js";
 // Factory

package/dist/run/redirect-target.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract the file target of a trailing shell redirect (`> file` / `>> file`).
+ * Handles quoted paths with spaces — the old /> \s*(\S+)\s*$/ matched only the
+ * first non-whitespace run, so `> "my file.txt"` yielded `"my`
+ * (review-2026-05-30). Returns undefined when there's no trailing redirect.
+ */
+export declare function parseRedirectTarget(command: string): string | undefined;

package/dist/run/redirect-target.js

@@ -0,0 +1,13 @@
+/**
+ * Extract the file target of a trailing shell redirect (`> file` / `>> file`).
+ * Handles quoted paths with spaces — the old /> \s*(\S+)\s*$/ matched only the
+ * first non-whitespace run, so `> "my file.txt"` yielded `"my`
+ * (review-2026-05-30). Returns undefined when there's no trailing redirect.
+ */
+export function parseRedirectTarget(command) {
+    // Optional quote captured in group 1; body in group 2 (or unquoted in 3).
+    const m = command.match(/>>?\s*(?:(['"])(.*?)\1|(\S+))\s*$/);
+    if (!m)
+        return undefined;
+    return m[2] !== undefined ? m[2] : m[3];
+}

package/dist/run/types.js

@@ -10,7 +10,7 @@
  * Key = current status, Value = allowed next statuses.
  */
 export const VALID_TRANSITIONS = {
-    queued: ["running", "cancelled"],
+    queued: ["running", "blocked", "cancelled"],
     running: [
         "waiting_input",
         "waiting_approval",

package/dist/runtime/background-shell.d.ts

@@ -0,0 +1,139 @@
+/**
+ * BackgroundShellManager — session-scoped registry + lifecycle for
+ * fire-and-forget background shells (design §4).
+ *
+ * A background shell is a long-lived process (typically `npm run dev`)
+ * started via `Bash(run_in_background=true)`. Unlike the foreground Bash
+ * path (which awaits the command to completion), this:
+ *
+ *   - spawns the command **detached** so it owns its own process group
+ *     (so KillShell can reap the whole `sh → npm → node vite` tree, §难点2);
+ *   - returns a `shell_id` immediately, never blocking the turn;
+ *   - streams output to an in-memory ring buffer + a wrap-around disk file,
+ *     stripping ANSI/progress noise only when handed to the agent (§难点4);
+ *   - detects a served port best-effort from the output (§难点3);
+ *   - is **completely separate** from `asyncAgentRegistry` so Engine.run's
+ *     wait-for-background loop never waits on a dev server (§难点5);
+ *   - on exit, enqueues a one-line completion notification (no output body,
+ *     §难点6 / D6) keyed by sessionId.
+ *
+ * Lifetime is process-local and session-scoped: `killSession(sid)` on
+ * explicit session deletion, `killAll()` on app/worker exit. Crashing the
+ * worker leaks the detached children as orphans — pidfiles let a restarted
+ * worker discover and reap them (§难点1, `reapOrphansFromPidfiles`).
+ */
+import type { SandboxBackend } from "../tool-system/sandbox/index.js";
+export type BgShellStatus = "starting" | "running" | "exited" | "killed" | "orphaned";
+/** Per-session soft cap on background shells (design §7 — fork-bomb guard). */
+export declare const MAX_SHELLS_PER_SESSION = 16;
+interface PidfileRecord {
+    shellId: string;
+    pgid: number;
+    command: string;
+    port?: number;
+    startedAt: number;
+    sessionId: string;
+}
+export interface BgShell {
+    shellId: string;
+    sessionId: string;
+    command: string;
+    cwd: string;
+    pgid: number;
+    status: BgShellStatus;
+    startedAt: number;
+    exitedAt?: number;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    detectedPort?: number;
+    /** Absolute stream position (RingFile.totalWritten) already returned to the
+     *  agent. Absolute — not window-relative — so it survives ring wraparound. */
+    agentReadOffset: number;
+    /** Total bytes the shell has written so far (monotonic, survives ring
+     *  wraparound). Lets the UI show live progress for long jobs like downloads
+     *  ("↑ 1.1 GB") even though the panel doesn't parse the output itself. */
+    totalBytes: number;
+    didWrap: boolean;
+    diskAvailable: boolean;
+}
+export interface SpawnBackgroundOptions {
+    command: string;
+    cwd: string;
+    sessionId: string;
+    shell?: string;
+    sandbox?: SandboxBackend;
+    /**
+     * Project `localEnvironment.env` to layer on top of the base shell env
+     * (see mergeShellEnv). Same source as the foreground Bash tool's
+     * `ctx.shellEnv` — passed through so a background dev server sees the same
+     * project env as a one-shot command.
+     */
+    shellEnv?: Record<string, string>;
+}
+export type SpawnResult = {
+    ok: true;
+    shellId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type ReadResult = {
+    ok: true;
+    text: string;
+    header: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type KillResult = {
+    ok: true;
+    alreadyExited?: boolean;
+    status: BgShellStatus;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class BackgroundShellManager {
+    private shells;
+    spawnBackground(opts: SpawnBackgroundOptions): SpawnResult;
+    private finalize;
+    private enqueueExitNotification;
+    private updatePidfilePort;
+    get(shellId: string): BgShell | undefined;
+    /** Raw retained output (no cleaning) — test/UI helper. */
+    readOutputRaw(shellId: string): string | undefined;
+    listForSession(sessionId: string): BgShell[];
+    /**
+     * Read a shell's output. `mode=incremental` (default) returns text since the
+     * agent's last read; `mode=all` returns the full retained buffer. Output is
+     * ANSI-stripped and progress-folded, capped at the last READ_RETURN_CAP
+     * chars. `expectSessionId`, when given, enforces session ownership.
+     */
+    readOutput(shellId: string, mode?: "incremental" | "all", expectSessionId?: string): ReadResult;
+    /**
+     * Build the status header line for a readOutput result. `mode` shapes the cap
+     * note: `all` keeps the trailing 16KB (older output omitted from THIS view),
+     * while incremental paginates (more output available on the next read).
+     */
+    private buildHeader;
+    /** Terminate a shell (its whole process group). Idempotent. */
+    kill(shellId: string, expectSessionId?: string): Promise<KillResult>;
+    /** Kill every background shell belonging to `sessionId`. */
+    killSession(sessionId: string): Promise<void>;
+    /** Kill every background shell (app/worker exit). */
+    killAll(): Promise<void>;
+    /**
+     * Scan pidfiles left by a previous (crashed) worker. For each: if the pgid
+     * is still alive it's an orphan (the dev server outlived its worker) — list
+     * it as `orphaned` so KillShell can clean it up; if dead, delete the stale
+     * pidfile. Returns the orphaned records found.
+     */
+    reapOrphansFromPidfiles(): PidfileRecord[];
+    private registerOrphan;
+    /** Test/reset helper — clears the registry without killing (used in tests). */
+    _clear(): void;
+    private toPublic;
+}
+/** Process-local singleton, mirroring asyncAgentRegistry's lifetime contract. */
+export declare const backgroundShellManager: BackgroundShellManager;
+export {};