llm-relay 0.85.0 → 0.86.0

package/dist/mcp/lane-runner.d.ts

@@ -1,5 +1,8 @@
-import { type JobJournal } from "./job-journal.js";
+import { type WindowsNpmShimDeps, type WindowsNpmShimResolution } from "./windows-npm-shim.js";
+import { type JobJournal, type JournalRow, type JournalStartingTree } from "./job-journal.js";
+import type { LaneExecutionSnapshot } from "../lane-execution-broker.js";
 import { type JobArchive } from "./job-archive.js";
+import type { TreeSnapshot } from "./tree-delta.js";
 import type { DispatchLaneStatus } from "../dispatch-lane-stats.js";
 /** Depth marker written into every child's environment, read back to bound recursion. */
 export declare const DEPTH_ENV = "LLM_RELAY_DISPATCH_DEPTH";
@@ -126,6 +129,33 @@ export declare function classifyLaneAttempt(run: LaneRunResult, opts?: {
     abandoned?: boolean | undefined;
     semanticFailure?: string | undefined;
 }): DispatchLaneStatus;
+export type LaneActivityState = "starting" | "active" | "quiet" | "advancing" | "unmonitored";
+export type LaneWalkVerdict = "keep-running" | "no-idle-stop";
+/**
+ * The walk's OWN liveness decision for the attempt running now.
+ *
+ * This is a published snapshot, not a second activity probe. `mcp/server.ts` computes it while
+ * making the same keep/stop decision the walk already has to make, then `dispatch_status` merely
+ * renders it. A status read must never call the relay-traffic, process-CPU or working-tree readers:
+ * those readers carry baselines/state and consuming them from a poll could change routing.
+ */
+export interface LaneLiveness {
+    activity: LaneActivityState;
+    verdict: LaneWalkVerdict;
+    /** When the walk last evaluated/published this snapshot. */
+    checkedAt: number;
+    /**
+     * Timestamp the idle timer is anchored to. Starts at attempt launch so a new lane gets a full
+     * idle window even before it emits observable activity; moves forward when real activity arrives.
+     */
+    idleBaselineAt: number;
+    /** Newest REAL activity timestamp the walk accepted for this attempt, or null before any. */
+    lastActivityAt: number | null;
+    /** What established the current idle baseline: attempt-start or a first-party activity signal. */
+    source: string;
+    /** Idle cutoff applied to this attempt; null means the walk will not idle-stop it. */
+    idleMs: number | null;
+}
 export interface LaneJob {
     id: string;
     status: JobStatus;
@@ -172,9 +202,10 @@ export interface LaneJob {
     forcedLane?: boolean;
     /**
      * How long the lane now running usually takes to ANSWER in this dispatch's mode, from that
-     * lane's own completed runs — rendered on every poll so a caller can tell a slow lane from a
-     * stuck one. 23 of the 182 unanswered dispatches in the 2026-09-10 transcript sweep ended with
-     * the caller simply no longer polling. Absent when the lane has no completed run on record.
+     * lane's own completed runs. Diagnostic only: it gives duration context, but the caller follows
+     * `liveness.verdict` rather than deciding "stuck" from history. 23 of the 182 unanswered
+     * dispatches in the 2026-09-10 transcript sweep ended with the caller simply no longer polling.
+     * Absent when the lane has no completed run on record.
      */
     expected?: {
         medianMs: number | null;
@@ -194,6 +225,11 @@ export interface LaneJob {
     relay?: RelayAnnouncements;
     /** Set when the job's dispatch view came from a fallback rather than the live daemon. */
     dispatchSource?: "daemon" | "fallback";
+    /**
+     * Who owns the currently-running agent process tree. Absent preserves the pre-D1/local shape for
+     * embeds and answer-mode jobs. `local-fallback` is explicit because it does NOT survive MCP exit.
+     */
+    executionOwner?: "relay-daemon" | "local-fallback";
     /**
      * What this dispatcher started for this job, and what became of it — written once, when the job
      * reaches a terminal state. See `LaneProcessReport`.
@@ -234,14 +270,10 @@ export interface LaneJob {
      */
     treeDelta?: string;
     /**
-     * The newest activity the walk saw for the lane now running (relay traffic, output, a file
-     * change), with its source. Replaced per lane; the walk stops a lane when this is older than
-     * `routing.dispatchWalk.idleMs`.
+     * The walk's authoritative liveness snapshot for the lane now running. Replaced per lane and
+     * removed when the job becomes terminal; terminal attempt records already say how the lane ended.
      */
-    lastActive?: {
-        at: number;
-        source: string;
-    };
+    liveness?: LaneLiveness;
 }
 /**
  * Output progress of the attempt now running. Byte counts and timestamps only — never the bytes.
@@ -250,8 +282,8 @@ export interface LaneJob {
  * `relay` rung takes in agent mode, i.e. the free pool itself — buffers its whole answer until
  * exit (module header), so "zero bytes after N seconds" is the ordinary shape of a healthy run on
  * the most-used lane. A threshold that killed on it would manufacture the false failure the backlog
- * item names as worse than a slow honest status. The figure lets the CALLER decide, which is the
- * property's second branch.
+ * item names as worse than a slow honest status. This figure is diagnostic only; the caller follows
+ * the walk's published liveness verdict instead of interpreting silence.
  */
 export interface LaneActivity {
     /** When the running attempt was spawned. */
@@ -411,7 +443,11 @@ type LaneExecError = Error & {
     killed?: boolean | undefined;
     code?: unknown;
 };
-/** Terminate a full process tree (on Windows via taskkill /T /F, on POSIX via process group / signal). */
+/**
+ * Terminate a full process tree (Windows: taskkill /T /F; POSIX: the process group created by
+ * `createLaneSpawner`). The positive-pid fallback is defence for an injected/legacy child that was
+ * not started as a group leader; the real POSIX spawner always owns group `pid`.
+ */
 export declare function terminateProcessTree(pid: number, platform?: NodeJS.Platform): void;
 /** A readable the spawner can watch for progress; the `data` event is all it subscribes to. */
 export interface LaneOutputStream {
@@ -432,6 +468,18 @@ export interface LaneChildProcess {
     stderr?: LaneOutputStream | null | undefined;
     kill: () => boolean;
 }
+/** Spawn options for the POSIX process-group path. */
+export interface LaneSpawnProcessOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    windowsHide: true;
+    detached: true;
+}
+/** Child events the POSIX buffered spawn path consumes. */
+export interface LaneSpawnedProcess extends LaneChildProcess {
+    on(event: "error", listener: (err: Error) => void): unknown;
+    on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
 /** Spawn options common to the direct and Windows shell-fallback paths. */
 export interface LaneExecOptions {
     encoding: "utf8";
@@ -447,7 +495,11 @@ export interface LaneProcessApi {
     platform: NodeJS.Platform;
     execFile: (command: string, args: string[], opts: LaneExecOptions, callback: LaneExecCallback) => LaneChildProcess;
     exec: (command: string, opts: LaneExecOptions, callback: LaneExecCallback) => LaneChildProcess;
+    /** POSIX-only real spawn seam: `detached` is supported by spawn, not execFile. */
+    spawn?: (command: string, args: string[], opts: LaneSpawnProcessOptions) => LaneSpawnedProcess;
 }
+/** Injectable npm-shim resolver so unit tests never inspect the host filesystem. */
+export type WindowsNpmShimResolver = (command: string, args: readonly string[], deps: WindowsNpmShimDeps) => WindowsNpmShimResolution;
 /**
  * The real spawner.
  *
@@ -459,7 +511,7 @@ export interface LaneProcessApi {
  * `winenv.ts`, `os-keyring.ts` and `lane-quota-probe.ts`: a test run must never spend real quota
  * or touch the operator's live agent sessions.
  */
-export declare function createLaneSpawner(processApi: LaneProcessApi, hostEnv?: NodeJS.ProcessEnv): LaneSpawner;
+export declare function createLaneSpawner(processApi: LaneProcessApi, hostEnv?: NodeJS.ProcessEnv, resolveNpmShim?: WindowsNpmShimResolver): LaneSpawner;
 export declare const defaultLaneSpawner: LaneSpawner;
 /**
  * The answer-mode HTTP seam — a direct POST to the running relay's own `/v1/messages`,
@@ -499,8 +551,19 @@ export interface RecentJob {
     elsewhere: boolean;
     label?: string;
 }
-/** Raise the counter to at least `seq`; never lowers it. */
-export declare function seedJobCounter(seq: number): void;
+/**
+ * Build one process-local job-id allocator.
+ *
+ * The old allocator read a shared max sequence and then incremented a process-local counter. Two
+ * MCP processes could both read N before either wrote N+1, so both handed out the same handle.
+ *
+ * New ids keep the established `job-<digits>` wire shape but replace the shared sequence with a
+ * 128-bit random PROCESS instance plus a local monotonic suffix. Independent processes need no
+ * coordination. The leading 9 plus fixed-width 39-digit instance guarantees every new id is
+ * outside JavaScript's safe-integer range, so `jobSeqOf` can continue recognizing only legacy
+ * sequential ids in old archive files.
+ */
+export declare function createJobIdFactory(entropy?: Uint8Array): () => string;
 /**
  * The job store.
  *
@@ -526,7 +589,14 @@ export declare class LaneJobStore {
     isAlive: (pid: number) => boolean;
     private readonly journal;
     private readonly archive;
-    constructor(journal?: JobJournal, archive?: JobArchive);
+    /** Starting trees carried off ordinary killed rows before the journal drops them on its next write. */
+    private readonly adoptedStartingTrees;
+    /** Dead-MCP rows whose actual process owner is the daemon, atomically claimed for reconciliation. */
+    private readonly brokerOrphans;
+    /** Running/recovered jobs whose process tree is owned by the daemon rather than this MCP process. */
+    private readonly brokerExecutions;
+    private readonly nextJobId;
+    constructor(journal?: JobJournal, archive?: JobArchive, nextJobId?: () => string);
     /**
      * The finished jobs a previous process archived, read back so `dispatch_status`/`dispatch_result`
      * answer for them after a restart instead of `unknown jobId`. Marked `restored` so the rendering
@@ -552,6 +622,8 @@ export declare class LaneJobStore {
      * reaches a terminal state and so what it owned is reportable afterwards.
      */
     registerProcess(id: string, handle: OwnedProcess): void;
+    /** Root pids currently owned by a still-running job, through the same handle the reaper uses. */
+    runningPids(id: string): number[];
     /**
      * Register a bare kill callback — the pre-existing seam, kept because a caller that owns no OS
      * process (an answer-mode job's direct HTTP call, or a test double) still has something to stop.
@@ -597,6 +669,49 @@ export declare class LaneJobStore {
     beginAttemptActivity(id: string, now: number): void;
     /** The running attempt wrote `bytes` to `stream` at `now`. Ignored once the attempt is over. */
     noteOutput(id: string, stream: "stdout" | "stderr", bytes: number, now: number): void;
+    /** Persist the job-wide starting tree while the job is still running. */
+    noteStartingTree(id: string, tree: TreeSnapshot, scope: readonly string[] | undefined): void;
+    /**
+     * Return, once, daemon-backed orphan rows this process atomically claimed. The server owns the
+     * broker client, so reconciliation is asynchronous and deliberately outside this synchronous store.
+     */
+    takeBrokerOrphans(): JournalRow[];
+    /** Broker execution id for a job this process is collecting, if any. */
+    brokerExecution(id: string): string | undefined;
+    /** Record which execution boundary owns the current attempt. */
+    noteExecutionOwner(id: string, owner: LaneJob["executionOwner"]): void;
+    /**
+     * Clear an attempt-scoped daemon execution after it is definitively terminal and the walk will
+     * continue. The job itself stays running; the journal row is rewritten without broker metadata.
+     */
+    clearBrokerExecution(id: string): void;
+    /**
+     * Bind a live job to the daemon execution that now owns its process tree, and persist the opaque
+     * reference before the broker start request is sent. Used by the later ownership switchover.
+     */
+    noteBrokerExecution(id: string, executionId: string): void;
+    /**
+     * Materialize a claimed broker row as a running job while the daemon is queried/retried.
+     * The daemon, not this process, owns its process tree; no local kill handle is registered.
+     */
+    adoptBrokerRunning(row: JournalRow, snapshot?: LaneExecutionSnapshot): LaneJob | undefined;
+    /**
+     * Apply one identity-checked daemon snapshot to an adopted broker job.
+     * Returns false on mismatch/inconsistent terminal data; callers then retain the row and retry
+     * rather than turn malformed transport data into a death claim.
+     */
+    applyBrokerSnapshot(id: string, snapshot: LaneExecutionSnapshot): boolean;
+    /** Definitive reachable-daemon 404: the broker no longer knows the execution. */
+    markBrokerKilled(id: string, message: string): boolean;
+    /**
+     * Return, once, the starting trees carried by jobs adopted as killed after a restart. The server
+     * owns the git reader, so the store cannot render their deltas synchronously during construction.
+     */
+    takeAdoptedStartingTrees(): Array<{
+        jobId: string;
+        cwd: string;
+        startingTree: JournalStartingTree;
+    }>;
     /** Record the read-only tool binding the lane now running was given, so the reply can state it. */
     noteReadOnly(id: string, laneId: string, binding: string): void;
     /** Record what the launcher changed for the lane now running, so the reply can state it. */
@@ -605,8 +720,8 @@ export declare class LaneJobStore {
      * the second `git status` returns — and the archive row is then written again so it carries it.
      */
     noteTreeDelta(id: string, text: string): void;
-    /** Record the newest activity the walk saw for the running lane. */
-    noteLastActivity(id: string, at: number, source: string): void;
+    /** Publish the walk's liveness decision for the attempt now running. Pure status data only. */
+    noteLiveness(id: string, liveness: LaneLiveness): void;
     noteLaunch(id: string, notes: readonly string[]): void;
     /**
      * Append one tried lane to the walk's record. Appended for EVERY attempt, the winner included,
@@ -651,11 +766,11 @@ export declare class LaneJobStore {
      * Passing the asking job's own id excludes it, so this answers "how many OTHER jobs are running
      * this lane right now" — the question a skip check actually needs.
      *
-     * ⚠ Per-process by construction, and that is the whole design, not a limitation to work around:
-     * the daemon never spawns a lane, so the only process that ever knows a `cli` rung's process is
-     * running is the one that spawned it. Two host sessions each running their own `llm-relay mcp`
-     * can together exceed a rung's `maxConcurrent` — this bounds one host's own concurrency, and
-     * `docs/reference.md` says so rather than implying a machine-wide guarantee this cannot make.
+     * ⚠ Per MCP SERVER PROCESS by design. D1 moves the physical child into the daemon, but this
+     * admission policy still counts the jobs THIS MCP store owns or recovered. Another simultaneously
+     * live MCP process is not folded into the number, so two host sessions can together exceed a
+     * rung's `maxConcurrent`. This preserves the documented per-host cap rather than silently turning
+     * it into a machine-wide semaphore.
      */
     inFlight(laneId: string, excludeJobId?: string): number;
     /** A job THIS store holds. The walk reads this; it never needs another process's job. */