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

package/dist/protocol/types.d.ts

@@ -40,6 +40,12 @@ export declare const ErrorCodes: {
     readonly Overloaded: -32001;
     readonly SessionNotFound: -32002;
     readonly SessionClosed: -32004;
+    /**
+     * Run was cancelled by the user (ESC / Stop). Clients should treat
+     * this as a clean terminal state, not a real error: no banner, no
+     * red toast — just clear busy and stop streaming.
+     */
+    readonly Cancelled: -32005;
 };
 /** Start an agent run with a user task. */
 export interface RunParams {
@@ -60,6 +66,15 @@ export interface RunParams {
      * this run; when omitted, the engine keeps its configured default.
      */
     planMode?: 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
+     * met and re-prompts if not (bounded). Orthogonal to permissionMode.
+     *
+     * Accepts a bare objective string or a full GoalConfig (objective +
+     * optional token/time budgets). Normalized at the engine run boundary.
+     */
+    goal?: string | import("../engine/goal.js").GoalConfig;
 }
 export interface RunResult {
     text: string;
@@ -104,6 +119,14 @@ export interface ConfigureParams {
      * running engine picks them up without a process restart.
      */
     reloadModels?: boolean;
+    /**
+     * Re-read disk settings and hot-push the disk-default config fields (preset /
+     * customSystemPrompt / appendSystemPrompt / personalization / mcpServers) +
+     * settings hooks onto ALREADY-RUNNING sessions ("config hot-reload layer 2").
+     * No sessionId → applies to every live session; with sessionId → that one.
+     * Applied at the next turn boundary; in-flight turns are not interrupted.
+     */
+    reloadSettings?: boolean;
 }
 /** Query server state. */
 export interface QueryParams {

package/dist/protocol/types.js

@@ -18,6 +18,12 @@ export const ErrorCodes = {
     Overloaded: -32001,
     SessionNotFound: -32002,
     SessionClosed: -32004,
+    /**
+     * Run was cancelled by the user (ESC / Stop). Clients should treat
+     * this as a clean terminal state, not a real error: no banner, no
+     * red toast — just clear busy and stop streaming.
+     */
+    Cancelled: -32005,
 };
 // ─── Method Names ───────────────────────────────────────────────────
 export const Methods = {

package/dist/remote/bridge.d.ts

@@ -4,6 +4,7 @@
  * Architecture:
  *   Local terminal ←→ SSH ←→ Remote code-shell (NDJSON stdio mode)
  */
+import { type ChildProcess } from "node:child_process";
 export interface BridgeConfig {
     host: string;
     user?: string;
@@ -11,11 +12,20 @@ export interface BridgeConfig {
     identityFile?: string;
     remoteCommand?: string;
 }
+/** A spawn function (injectable for tests). Defaults to child_process.spawn. */
+export type SpawnFn = (command: string, args: string[]) => ChildProcess;
+/**
+ * Build the ssh argv. Each value is a discrete element — spawn runs ssh
+ * without a shell, so identityFile/port/host are never shell-interpreted
+ * (there is no local command-injection surface here).
+ */
+export declare function buildSSHArgs(config: BridgeConfig): string[];
 export declare class RemoteBridge {
     private readonly config;
     private ssh;
     private connected;
-    constructor(config: BridgeConfig);
+    private readonly spawnFn;
+    constructor(config: BridgeConfig, spawnFn?: SpawnFn);
     /**
      * Connect to the remote host via SSH and start code-shell in NDJSON mode.
      */
@@ -33,5 +43,4 @@ export declare class RemoteBridge {
      */
     disconnect(): void;
     get isConnected(): boolean;
-    private buildSSHArgs;
 }

package/dist/remote/bridge.js

@@ -6,42 +6,71 @@
  */
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
+/**
+ * Build the ssh argv. Each value is a discrete element — spawn runs ssh
+ * without a shell, so identityFile/port/host are never shell-interpreted
+ * (there is no local command-injection surface here).
+ */
+export function buildSSHArgs(config) {
+    const args = ["-T"]; // No pseudo-terminal
+    if (config.port)
+        args.push("-p", String(config.port));
+    if (config.identityFile)
+        args.push("-i", config.identityFile);
+    args.push(config.user ? `${config.user}@${config.host}` : config.host);
+    return args;
+}
 export class RemoteBridge {
     config;
     ssh;
     connected = false;
-    constructor(config) {
+    spawnFn;
+    constructor(config, spawnFn) {
         this.config = config;
+        this.spawnFn = spawnFn ?? ((cmd, args) => spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] }));
     }
     /**
      * Connect to the remote host via SSH and start code-shell in NDJSON mode.
      */
     async connect() {
-        const sshArgs = this.buildSSHArgs();
+        const sshArgs = buildSSHArgs(this.config);
         const remoteCmd = this.config.remoteCommand ?? "code-shell run --output stream-json";
-        this.ssh = spawn("ssh", [...sshArgs, remoteCmd], {
-            stdio: ["pipe", "pipe", "pipe"],
-        });
+        this.ssh = this.spawnFn("ssh", [...sshArgs, remoteCmd]);
         return new Promise((resolve, reject) => {
+            // Settle exactly once: the first stdout resolves; an error/early-exit
+            // before that rejects. Events after settlement are ignored (the old
+            // code re-rejected an already-settled promise and used a dead
+            // `if (!this.connected)` guard that was always true).
+            let settled = false;
             const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
                 reject(new Error("SSH connection timed out"));
                 this.disconnect();
             }, 30000);
             this.ssh.stdout?.once("data", () => {
+                if (settled)
+                    return;
+                settled = true;
                 clearTimeout(timer);
                 this.connected = true;
                 resolve();
             });
             this.ssh.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
                 clearTimeout(timer);
                 reject(err);
             });
             this.ssh.on("exit", (code) => {
                 this.connected = false;
-                if (!this.connected) {
-                    clearTimeout(timer);
-                    reject(new Error(`SSH exited with code ${code}`));
-                }
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`SSH exited with code ${code}`));
             });
         });
     }
@@ -52,7 +81,13 @@ export class RemoteBridge {
         if (!this.connected || !this.ssh?.stdin) {
             throw new Error("Not connected");
         }
-        this.ssh.stdin.write(JSON.stringify(message) + "\n");
+        this.ssh.stdin.write(JSON.stringify(message) + "\n", (err) => {
+            if (err) {
+                // A broken pipe means the remote is gone — surface it as a
+                // disconnect rather than swallowing the failed write.
+                this.connected = false;
+            }
+        });
     }
     /**
      * Async iterator for messages from the remote code-shell.
@@ -61,17 +96,24 @@ export class RemoteBridge {
         if (!this.ssh?.stdout)
             return;
         const rl = createInterface({ input: this.ssh.stdout, crlfDelay: Infinity });
-        for await (const line of rl) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            try {
-                yield JSON.parse(trimmed);
-            }
-            catch {
-                // Skip malformed
+        try {
+            for await (const line of rl) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    yield JSON.parse(trimmed);
+                }
+                catch {
+                    // Skip malformed
+                }
             }
         }
+        finally {
+            // Close the interface if the consumer breaks/returns early — otherwise
+            // it (and its stdout listener) leaks.
+            rl.close();
+        }
     }
     /**
      * Disconnect from the remote host.
@@ -86,18 +128,4 @@ export class RemoteBridge {
     get isConnected() {
         return this.connected;
     }
-    buildSSHArgs() {
-        const args = ["-T"]; // No pseudo-terminal
-        if (this.config.port)
-            args.push("-p", String(this.config.port));
-        if (this.config.identityFile)
-            args.push("-i", this.config.identityFile);
-        if (this.config.user) {
-            args.push(`${this.config.user}@${this.config.host}`);
-        }
-        else {
-            args.push(this.config.host);
-        }
-        return args;
-    }
 }

package/dist/run/ArtifactTracker.js

@@ -12,6 +12,7 @@
  *   - Judgment: file writes are artifacts, reads are not
  */
 import { nanoid } from "nanoid";
+import { parseRedirectTarget } from "./redirect-target.js";
 export class ArtifactTracker {
     config;
     pendingCalls = new Map();
@@ -111,10 +112,10 @@ export class ArtifactTracker {
             await this.config.store.appendArtifactRef(ref);
             return;
         }
-        // Redirect output: command > file or command >> file
-        const redirectMatch = trimmed.match(/>\s*(\S+)\s*$/);
-        if (redirectMatch) {
-            await this.recordFileArtifact(redirectMatch[1], "output", "file");
+        // Redirect output: command > file or command >> file (quoted-path aware)
+        const redirectTarget = parseRedirectTarget(trimmed);
+        if (redirectTarget) {
+            await this.recordFileArtifact(redirectTarget, "output", "file");
             return;
         }
         // cp / mv — destination is an artifact

package/dist/run/EngineRunner.d.ts

@@ -9,9 +9,25 @@
  *   - Return execution result (does NOT manage run state transitions)
  */
 import { type EngineConfig, type EngineHookConfig } from "../engine/engine.js";
-import type { LLMConfig, RegisteredTool } from "../types.js";
+import type { ClientDefaults, LLMConfig, RegisteredTool } from "../types.js";
 import type { RunSnapshot, RunExecutionContext, RunExecutionResult } from "./types.js";
 import { type RunLifecycleHooks } from "./RunApprovalBackend.js";
+import type { ApprovalBackend } from "../tool-system/permission.js";
+/** Unattended runs (those with an injected approval backend) run headless so
+ *  the in-process AgentServer does not wire an interactive askUser. Exported
+ *  for unit testing the decision rule. */
+export declare function buildHeadlessFlag(override: ApprovalBackend | undefined): boolean;
+/** Run-metadata `source` value tagging a run as unattended automation
+ *  (set by the automation host; read here to decide prompt/headless behavior). */
+export declare const AUTOMATION_RUN_SOURCE = "automation";
+/** Appended to the system prompt for unattended automation runs so the model
+ *  knows it IS the automation and must not ask the user or offer to schedule
+ *  automation. English by repo convention; the model answers in the user's
+ *  language regardless. */
+export declare const AUTOMATION_PROMPT_NOTE: string;
+/** Compose the run's appendSystemPrompt: prepend the automation note when the
+ *  run is tagged source "automation", preserving any host-provided append. */
+export declare function buildAppendSystemPrompt(hostAppend: string | undefined, metadata: Record<string, unknown> | undefined): string | undefined;
 /**
  * Handles returned from execute() to allow RunManager to resolve
  * pending approvals and user input while Engine is suspended.
@@ -48,6 +64,8 @@ export interface CustomToolEntry {
 }
 export interface EngineRunnerConfig {
     llm: LLMConfig;
+    /** Cross-model runtime knobs (temperature/timeout/imageDetail). */
+    clientDefaults?: ClientDefaults;
     maxTurns?: number;
     maxContextTokens?: number;
     sessionStorageDir?: string;
@@ -61,6 +79,14 @@ export interface EngineRunnerConfig {
     customTools?: CustomToolEntry[];
     /** Hooks registered into each Engine instance before run execution. */
     hooks?: EngineHookConfig[];
+    /**
+     * Override the approval backend. When set, the run uses THIS backend instead
+     * of the interactive run-aware RunApprovalBackend — used by unattended hosts
+     * (e.g. automation/cron) that must auto-decide without a UI, e.g. a
+     * HeadlessApprovalBackend("approve-read-only"). When unset, the interactive
+     * run-aware backend is used (default REPL/desktop behavior).
+     */
+    approvalBackend?: ApprovalBackend;
 }
 export declare class EngineRunner implements RunExecutor {
     private readonly config;

package/dist/run/EngineRunner.js

@@ -11,6 +11,33 @@
 import { Engine } from "../engine/engine.js";
 import { RunApprovalBackend, createRunAskUserFn, } from "./RunApprovalBackend.js";
 import { createInProcessClient } from "../protocol/helpers.js";
+/** Unattended runs (those with an injected approval backend) run headless so
+ *  the in-process AgentServer does not wire an interactive askUser. Exported
+ *  for unit testing the decision rule. */
+export function buildHeadlessFlag(override) {
+    return override !== undefined;
+}
+/** Run-metadata `source` value tagging a run as unattended automation
+ *  (set by the automation host; read here to decide prompt/headless behavior). */
+export const AUTOMATION_RUN_SOURCE = "automation";
+/** Appended to the system prompt for unattended automation runs so the model
+ *  knows it IS the automation and must not ask the user or offer to schedule
+ *  automation. English by repo convention; the model answers in the user's
+ *  language regardless. */
+export const AUTOMATION_PROMPT_NOTE = "This is an unattended, scheduled automation run. No human is watching, and " +
+    "AskUserQuestion will not reach anyone. You ARE the automation — do not ask " +
+    "the user questions and do not offer to set up or schedule automation. " +
+    "Produce the requested output directly; when uncertain, state your assumption " +
+    "and proceed." +
+    " When finished, call UpdateAutomationMemory exactly once with a concise " +
+    "summary of this run's key findings/state for the next run.";
+/** Compose the run's appendSystemPrompt: prepend the automation note when the
+ *  run is tagged source "automation", preserving any host-provided append. */
+export function buildAppendSystemPrompt(hostAppend, metadata) {
+    if (metadata?.source !== AUTOMATION_RUN_SOURCE)
+        return hostAppend;
+    return hostAppend ? `${AUTOMATION_PROMPT_NOTE}\n\n${hostAppend}` : AUTOMATION_PROMPT_NOTE;
+}
 // ─── EngineRunner (built-in RunExecutor) ────────────────────────
 export class EngineRunner {
     config;
@@ -18,23 +45,30 @@ export class EngineRunner {
         this.config = config;
     }
     async execute(run, context, lifecycleHooks, onHandleReady) {
-        // Create run-aware approval backend
-        const approvalBackend = new RunApprovalBackend();
+        // Run-aware approval backend (interactive: suspends the run and waits for
+        // RunManager to resolve via the handle). Always constructed so the handle
+        // stays well-formed, but only wired into the engine when no override is set.
+        const runApprovalBackend = new RunApprovalBackend();
+        // Unattended override: a host (automation/cron) can inject a backend that
+        // auto-decides (e.g. approve-read-only). When set, the engine uses it and
+        // the interactive resolve path is inert (no UI to resolve approvals).
+        const override = this.config.approvalBackend;
+        const engineApprovalBackend = override ?? runApprovalBackend;
         // Create run-aware askUser adapter
         let resolveInputFn = () => false;
         let hasPendingInputFn = () => false;
         let askUserFn;
-        if (lifecycleHooks) {
-            approvalBackend.setHooks(lifecycleHooks);
+        if (lifecycleHooks && !override) {
+            runApprovalBackend.setHooks(lifecycleHooks);
             const askAdapter = createRunAskUserFn(lifecycleHooks);
             askUserFn = askAdapter.askUserFn;
             resolveInputFn = askAdapter.resolveInput;
             hasPendingInputFn = askAdapter.hasPendingInput;
         }
         const handle = {
-            resolveApproval: (approved, reason) => approvalBackend.resolveApproval(approved ? { approved: true } : { approved: false, reason }),
+            resolveApproval: (approved, reason) => runApprovalBackend.resolveApproval(approved ? { approved: true } : { approved: false, reason }),
             resolveInput: resolveInputFn,
-            hasPendingApproval: () => approvalBackend.hasPendingApproval(),
+            hasPendingApproval: () => runApprovalBackend.hasPendingApproval(),
             hasPendingInput: hasPendingInputFn,
         };
         // Expose handle immediately so RunManager can resolve approvals/input
@@ -42,19 +76,23 @@ export class EngineRunner {
         onHandleReady?.(handle);
         const engineConfig = {
             llm: this.config.llm,
+            clientDefaults: this.config.clientDefaults,
             cwd: run.cwd,
             maxTurns: this.config.maxTurns ?? 30,
             maxContextTokens: this.config.maxContextTokens ?? 200_000,
             permissionMode: this.config.permissionMode ?? "acceptEdits",
+            headless: buildHeadlessFlag(override),
             preset: run.preset,
             enabledBuiltinTools: this.config.enabledBuiltinTools,
             disabledBuiltinTools: this.config.disabledBuiltinTools,
             customSystemPrompt: this.config.customSystemPrompt,
-            appendSystemPrompt: this.config.appendSystemPrompt,
+            // NOTE: callers must not pass appendSystemPrompt in engineConfigOverrides
+            // below, or it will clobber this composed (automation note + host) value.
+            appendSystemPrompt: buildAppendSystemPrompt(this.config.appendSystemPrompt, run.metadata),
             sessionStorageDir: this.config.sessionStorageDir,
             mcpServers: this.config.mcpServers,
             hooks: this.config.hooks,
-            approvalBackend,
+            approvalBackend: engineApprovalBackend,
             askUser: askUserFn,
             ...context.engineConfigOverrides,
         };

package/dist/run/FileRunStore.js

@@ -32,9 +32,16 @@ export class FileRunStore {
     }
     writeJson(filePath, data) {
         const tmp = filePath + ".tmp";
-        writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
-        // Atomic rename — prevents partial writes on crash
-        renameSync(tmp, filePath);
+        try {
+            writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+            // Atomic rename — prevents partial writes on crash
+            renameSync(tmp, filePath);
+        }
+        catch (err) {
+            // Don't leave a dangling .tmp behind on a failed write/rename.
+            rmSync(tmp, { force: true });
+            throw err;
+        }
     }
     readJson(filePath) {
         if (!existsSync(filePath))
@@ -44,13 +51,30 @@ export class FileRunStore {
     /** Serializes concurrent JSONL appends per file path. */
     appendLocks = new Map();
     async appendJsonl(filePath, data) {
-        // Serialize writes to the same file to prevent interleaved output
+        // Serialize writes to the same file to prevent interleaved output. The
+        // chain we STORE as the lock must never reject — otherwise a single failed
+        // write poisons the lock and every later write chains off the rejected
+        // promise, skips its callback, and fails forever. So sequence off the
+        // previous lock's settlement (.catch(()=>{})), do the write, and surface
+        // this write's own error to *this* caller via a separate promise.
         const prev = this.appendLocks.get(filePath) ?? Promise.resolve();
-        const current = prev.then(() => {
-            appendFileSync(filePath, JSON.stringify(data) + "\n", "utf-8");
+        let settle;
+        const lock = new Promise((resolve) => {
+            settle = resolve;
         });
-        this.appendLocks.set(filePath, current);
-        await current;
+        this.appendLocks.set(filePath, lock);
+        try {
+            await prev.catch(() => { });
+            appendFileSync(filePath, JSON.stringify(data) + "\n", "utf-8");
+        }
+        finally {
+            // Release the lock for the next writer regardless of success/failure,
+            // and drop the map entry if no newer writer has queued behind us.
+            settle();
+            if (this.appendLocks.get(filePath) === lock) {
+                this.appendLocks.delete(filePath);
+            }
+        }
     }
     readJsonl(filePath) {
         if (!existsSync(filePath))

package/dist/run/RunLock.d.ts

@@ -10,16 +10,42 @@ export interface RunLockConfig {
     runsDir?: string;
     /** Stale lock timeout in ms. Default: 60_000 (1 minute) */
     staleMs?: number;
+    /** How long to wait for runs/<id>/run.json to appear before failing. */
+    targetWaitMs?: number;
+    /** Poll interval while waiting for the lock target file. */
+    targetPollMs?: number;
 }
+export type RunLockAcquireResult = {
+    acquired: true;
+} | {
+    acquired: false;
+    reason: "missing_target" | "locked";
+    message?: string;
+    code?: string;
+};
 export declare class RunLock {
     private readonly runsDir;
     private readonly staleMs;
+    private readonly targetWaitMs;
+    private readonly targetPollMs;
     private readonly releaseFns;
     constructor(config?: RunLockConfig);
     /**
-     * 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".
      */
-    acquire(runId: string): Promise<boolean>;
+    acquire(runId: string): Promise<RunLockAcquireResult>;
+    /**
+     * 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).
+     */
+    private waitForTarget;
     /**
      * Release the lock for a run.
      */

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.js

@@ -293,9 +293,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 +347,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 });
             },