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

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/review/review-prompt.d.ts

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

package/dist/review/review-prompt.js

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

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

package/dist/run/RunApprovalBackend.js

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

package/dist/run/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.
      */