llm-relay 0.85.0 → 0.86.0

package/dist/mcp/server.js

@@ -1,5 +1,6 @@
-import { randomUUID } from "node:crypto";
-import { LANE_ACTIVITY_HEADER } from "../lane-activity.js";
+import { buildLaneEnv } from "../lane-launch-env.js";
+export { buildLaneEnv, laneCredentialEnvNames } from "../lane-launch-env.js";
+import { createLaneActivityTag, LANE_ACTIVITY_HEADER, withLaneActivityHeader, } from "../lane-activity.js";
 import { DEFAULT_MCP_BLOCKING_WAIT_MS, DEFAULT_MCP_MAX_WAIT_MS, EFFORT_LEVELS } from "../config-types.js";
 import { isToolUseBlock } from "../anthropic.js";
 import { formatLaneStats, isPassThroughSpec, LANE_UNRELIABLE_STREAK, mcpPassThroughReason } from "../dispatch.js";
@@ -11,6 +12,8 @@ import { readOnlyInvoke, readOnlyVerdict } from "./readonly-boundary.js";
 import { agyQuotaStatement } from "./agy-quota-log.js";
 import { nullJobJournal } from "./job-journal.js";
 import { nullJobArchive } from "./job-archive.js";
+import { UNKNOWN_LANE_EXECUTION_MESSAGE } from "../lane-execution-broker.js";
+import { createLaneExecutionId, } from "./lane-execution-client.js";
 import { RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, encodeMessage, errorResponse, isJsonRpcNotification, isJsonRpcRequest, logStderr, negotiateProtocolVersion, resultResponse, splitMessages, } from "./protocol.js";
 export const MCP_SERVER_NAME = "llm-relay";
 export const DEFAULT_ANSWER_MAX_TOKENS = 4096;
@@ -32,7 +35,11 @@ export const MCP_INSTRUCTIONS = "Use dispatch from every MCP host — Claude, Co
     "Call dispatch instead. If this MCP server is unavailable, run `llm-relay dispatch " +
     "--next-command -t <task>` and follow its returned command or target; do not guess from the host.\n\n" +
     "Let dispatch choose the lane. If a lane stops showing activity, dispatch moves to the next one " +
-    "itself and prefers the lane that answered on your next call. Follow the advice at the end of a " +
+    "itself and prefers the lane that answered on your next call. For a running job, follow " +
+    "`walk-verdict`: `keep-running` means continue polling, `no-idle-stop` means the walk will " +
+    "not stop this attempt for idleness, and `unavailable` means another MCP process owns the live " +
+    "job so you should keep polling rather than infer. Do not infer liveness from elapsed time, output silence, " +
+    "historical duration, or activity diagnostics. Follow the advice at the end of a " +
     "reply: when it says a lane was stopped while it was still working, dispatch again with that " +
     "lane named so it can finish; when it says every lane ran and failed, do the work here — " +
     "re-dispatching the same task picks the same lanes. To run one specific model instead of the " +
@@ -153,8 +160,12 @@ const TOOLS = [
     {
         name: "dispatch_status",
         title: "Check a dispatched job",
-        description: "Report a dispatched job. While it runs: its lane, elapsed time and output so far. Once it " +
-            "has ended: its full answer, exactly as dispatch_result returns it. Wait at least a few " +
+        description: "Report a dispatched job. While it runs, `walk-verdict` is the authoritative liveness " +
+            "decision: keep-running means continue polling; no-idle-stop means this attempt is exempt " +
+            "from idle stopping; unavailable means another MCP process owns the live job, so keep polling. " +
+            "Activity may read advancing while the walk changes lanes; keep-running still means poll. " +
+            "Elapsed time, output silence, historical duration and activity diagnostics are diagnostics only. " +
+            "Once it has ended: its full answer, exactly as dispatch_result returns it. Wait at least a few " +
             "seconds between polls. Without jobId: list the recent jobs of every llm-relay MCP server " +
             "on this machine, so a lost jobId can be found again.",
         inputSchema: {
@@ -314,6 +325,31 @@ function relayProvenanceLines(job) {
         lines.push(`degraded: ${relay.degraded}`);
     return lines;
 }
+function describeLiveness(job, now) {
+    if (job.status !== "running")
+        return [];
+    const liveness = job.liveness;
+    if (liveness === undefined) {
+        return ["activity: starting", "walk-verdict: keep-running", "activity-checked: pending"];
+    }
+    const checkedAgo = Math.max(0, Math.round((now - liveness.checkedAt) / 1000));
+    const lines = [
+        `activity: ${liveness.activity}`,
+        `walk-verdict: ${liveness.verdict}`,
+        `activity-checked: ${checkedAgo}s ago`,
+    ];
+    lines.push(`activity-basis: ${liveness.source}`);
+    if (liveness.lastActivityAt !== null) {
+        const activityAgeAtCheck = Math.max(0, liveness.checkedAt - liveness.lastActivityAt);
+        lines.push(`last-activity-at-check: ${Math.round(activityAgeAtCheck / 1000)}s ago`);
+    }
+    if (liveness.verdict === "keep-running" && liveness.idleMs !== null && liveness.activity !== "advancing") {
+        const baselineAgeAtCheck = Math.max(0, liveness.checkedAt - liveness.idleBaselineAt);
+        const remainingAtCheck = Math.max(0, liveness.idleMs - baselineAgeAtCheck);
+        lines.push(`idle-stop-in-at-check: ${Math.ceil(remainingAtCheck / 1000)}s`);
+    }
+    return lines;
+}
 function describeJob(job, now) {
     const elapsed = Math.round(((job.endedAt ?? now) - job.startedAt) / 1000);
     const head = [
@@ -331,17 +367,20 @@ function describeJob(job, now) {
     head.push(...relayProvenanceLines(job));
     if (job.dispatchSource === "fallback")
         head.push("dispatch-source: local-fallback (daemon unreachable)");
+    if (job.executionOwner === "relay-daemon")
+        head.push("execution-owner: relay-daemon (survives MCP host restart)");
+    if (job.executionOwner === "local-fallback")
+        head.push("execution-owner: local-fallback (does NOT survive MCP host restart)");
     if (job.restored === true) {
-        head.push("record: restored from disk — this job ended in an earlier llm-relay MCP server process or in another host's one");
+        head.push(job.status === "running"
+            ? "record: recovered after MCP restart — this job's process tree is owned by the relay daemon"
+            : "record: restored from disk — this job ended in an earlier llm-relay MCP server process or in another host's one");
     }
     if (job.readOnly)
         head.push(`read-only: ${job.readOnly.binding}`);
     if (job.launch?.length)
         head.push(`launch: ${job.launch.join("; ")}`);
-    if (job.status === "running" && job.lastActive) {
-        const ago = Math.max(0, Math.round((now - job.lastActive.at) / 1000));
-        head.push(`last activity: ${ago}s ago (${job.lastActive.source})`);
-    }
+    head.push(...describeLiveness(job, now));
     const usually = runningTimeToAnswer(job);
     if (usually !== null)
         head.push(usually);
@@ -409,7 +448,9 @@ function jobAnswerBody(job, now) {
         return `${header}\n\nStill running. Poll dispatch_status, then call dispatch_result.`;
     }
     if (job.status === "killed") {
-        return `${header}\n\nThe lane was KILLED when the llm-relay MCP server restarted — it did not fail and it did not time out. Its process is gone. Re-dispatch from scratch, and check the working directory first: only files the lane wrote before the restart survive.`;
+        return job.restored === true
+            ? `${header}\n\nThe daemon-owned lane execution could no longer be recovered. No terminal result was collectable, so re-dispatch from scratch and check the working directory for partial files first.`
+            : `${header}\n\nThe lane was KILLED when the llm-relay MCP server restarted — it did not fail and it did not time out. Its process is gone. Re-dispatch from scratch, and check the working directory first: only files the lane wrote before the restart survive.`;
     }
     if (job.status === "timed_out") {
         const partial = isContentEmpty(body) ? "" : `\n\nPartial output before the timeout:\n\n${body}`;
@@ -422,6 +463,7 @@ function jobAnswerBody(job, now) {
     }
     return `${header}\n\n${body}${exhausted}`;
 }
+export const BROKER_STATUS_POLL_MS = 1_000;
 function emptyRun() {
     return { code: null, stdout: "", stderr: "", timedOut: false };
 }
@@ -437,7 +479,7 @@ function attemptReason(status, outcome, idleMs) {
         return undefined;
     if (status === "abandoned") {
         const quiet = idleMs === null ? "a long time" : `${Math.round(idleMs / 1000)}s`;
-        return `no activity for ${quiet} (no relay traffic, output or file change), so the next lane was started`;
+        return `no activity for ${quiet} (no relay traffic, output, process CPU or file change), so the next lane was started`;
     }
     if (outcome.semanticFailure !== undefined)
         return outcome.semanticFailure;
@@ -456,10 +498,7 @@ function flagValue(args, flag) {
     return joined === undefined ? null : joined.slice(flag.length + 1);
 }
 export const IDLE_POLL_MS = 15_000;
-function withActivityHeader(existing, tag) {
-    const line = `${LANE_ACTIVITY_HEADER}: ${tag}`;
-    return existing === undefined || existing.trim() === "" ? line : `${existing}\n${line}`;
-}
+const PROCESS_CPU_ACTIVITY_MS = 1_000;
 function newestActivity(seen) {
     let best = null;
     for (const s of seen) {
@@ -469,9 +508,6 @@ function newestActivity(seen) {
     }
     return best;
 }
-function newActivityTag() {
-    return randomUUID().replaceAll("-", "");
-}
 function pollTimer(ms) {
     return new Promise((resolve) => {
         const t = setTimeout(() => resolve({ kind: "poll" }), ms);
@@ -482,16 +518,6 @@ function pollTimer(ms) {
 function laneAnswered(r) {
     return r.code === 0 && !r.timedOut && !isContentEmpty(r.stdout);
 }
-function applyLaneEnv(base, deltas) {
-    const env = { ...base };
-    for (const [name, value] of Object.entries(deltas ?? {})) {
-        if (value === null)
-            delete env[name];
-        else
-            env[name] = value;
-    }
-    return env;
-}
 function laneSummary(lane, inFlight) {
     const bits = [`${lane.position}. ${lane.id}`, `[${lane.state}]`];
     if (lane.spec)
@@ -504,6 +530,11 @@ function laneSummary(lane, inFlight) {
         bits.push(`unreachable: ${lane.unreachable}`);
     if (lane.note)
         bits.push(lane.note);
+    if (lane.capabilityBasis !== undefined) {
+        bits.push(lane.capability === undefined
+            ? "capability: unknown (no evidence-qualified limit)"
+            : `capability: ${lane.capability} (${lane.capabilityBasis})`);
+    }
     bits.push(...laneEvidenceBits(lane));
     if (lane.maxConcurrent !== null && lane.maxConcurrent !== undefined) {
         bits.push(`in flight: ${inFlight} of ${lane.maxConcurrent}`);
@@ -535,6 +566,11 @@ export class McpDispatchServer {
     cancellable = new Map();
     trees = new Map();
     activityTags = new Map();
+    processCpu = new Map();
+    brokerCpu = new Map();
+    liveBrokerSnapshots = new Map();
+    startup;
+    brokerStartup;
     constructor(deps) {
         this.deps = deps;
         this.jobs = new LaneJobStore(deps.journal ?? nullJobJournal, deps.archive ?? nullJobArchive);
@@ -543,6 +579,9 @@ export class McpDispatchServer {
         this.now = deps.now ?? Date.now;
         this.cwd = deps.cwd ?? (() => process.cwd());
         this.maxDepth = deps.maxDepth ?? DEFAULT_MAX_DEPTH;
+        const killedTreeStartup = this.restoreKilledTreeDeltas();
+        this.brokerStartup = this.restoreBrokerOrphans();
+        this.startup = Promise.all([killedTreeStartup, this.brokerStartup]).then(() => undefined);
     }
     ingest(chunk) {
         this.buffer += chunk;
@@ -661,10 +700,13 @@ export class McpDispatchServer {
             case "dispatch":
                 return this.toolDispatch(args, ctx);
             case "dispatch_status":
+                await this.startup;
                 return this.toolStatus(args);
             case "dispatch_result":
+                await this.startup;
                 return this.toolResult(args);
             case "dispatch_cancel":
+                await this.brokerStartup;
                 return this.toolCancel(args);
             case "dispatch_lanes":
                 return this.toolLanes(args);
@@ -706,14 +748,17 @@ export class McpDispatchServer {
         const next = view.next ? `\n\nnext: ${view.next.id} — ${view.reason}` : `\n\nnext: none — ${view.reason}`;
         const walk = this.deps.config.routing?.dispatchWalk;
         const rule = walk?.enabled === true
-            ? `\nwalk: a lane is stopped after ${Math.round(walk.idleMs / 1000)}s with no activity (relay traffic, output or file change); the last lane is never stopped`
+            ? `\nwalk: a lane is stopped after ${Math.round(walk.idleMs / 1000)}s with no activity (relay traffic, output, owned process CPU or file change); the last lane is never stopped`
             : "\nwalk: off — only the first lane runs";
         return textResult(`tier: ${view.tier ?? "default"}${rule}\n\n${lines.join("\n")}${next}`);
     }
-    toolStatus(args) {
+    async toolStatus(args) {
         const jobId = readString(args, "jobId");
-        if (!jobId)
+        if (!jobId) {
+            await this.refreshAllBrokerJobs();
             return textResult(this.recentJobs());
+        }
+        await this.refreshBrokerJob(jobId);
         const job = this.jobs.find(jobId);
         if (!job)
             return this.unknownJob(jobId);
@@ -721,10 +766,11 @@ export class McpDispatchServer {
             return textResult(describeJob(job, this.now()));
         return textResult(jobAnswer(job, this.now()), isFailureStatus(job.status));
     }
-    toolResult(args) {
+    async toolResult(args) {
         const jobId = readString(args, "jobId");
         if (!jobId)
             return textResult("dispatch_result requires jobId", true);
+        await this.refreshBrokerJob(jobId);
         const job = this.jobs.find(jobId);
         if (!job)
             return this.unknownJob(jobId);
@@ -753,18 +799,55 @@ export class McpDispatchServer {
             `lane: ${elsewhere.laneId}${elsewhere.spec ? ` (${elsewhere.spec})` : ""}`,
             "status: running",
             `elapsed: ${elapsed}s`,
+            "activity: unavailable",
+            "walk-verdict: unavailable",
             `record: running in another llm-relay MCP server process (pid ${elsewhere.pid})`,
         ].join("\n") +
-            "\n\nThis process cannot report its progress or cancel it. Poll again: its answer appears " +
-            "here once it ends.");
+            "\n\nThis process cannot observe that process's live activity or cancel it. " +
+            "`walk-verdict: unavailable` means keep polling rather than infer from elapsed time or silence; " +
+            "its answer appears here once it ends.");
     }
-    toolCancel(args) {
+    async toolCancel(args) {
         const jobId = readString(args, "jobId");
         if (!jobId)
             return textResult("dispatch_cancel requires jobId", true);
         const job = this.jobs.find(jobId);
         if (!job)
             return this.unknownJob(jobId);
+        if (job.status !== "running") {
+            return textResult(`${jobId} was already ${job.status}`);
+        }
+        const executionId = this.jobs.brokerExecution(jobId);
+        if (executionId !== undefined) {
+            const client = this.deps.laneExecutionClient;
+            if (client === undefined) {
+                return textResult(`could not cancel ${jobId}: the daemon execution client is unavailable; the job was left running`, true);
+            }
+            let result;
+            try {
+                result = await client.request({ action: "cancel", executionId });
+            }
+            catch {
+                return textResult(`could not cancel ${jobId}: the daemon execution client failed; the job was left running`, true);
+            }
+            if (!result.ok) {
+                if (result.kind === "rejected" && result.status === 404 && result.message === UNKNOWN_LANE_EXECUTION_MESSAGE) {
+                    this.jobs.markBrokerKilled(jobId, "the relay daemon is reachable but no longer knows this recovered lane execution");
+                    await this.recordTreeDelta(jobId);
+                    return textResult(`${jobId} was already killed`, true);
+                }
+                return textResult(`could not cancel ${jobId}: ${result.message}; the daemon-owned execution was left untouched`, true);
+            }
+            if (!this.jobs.applyBrokerSnapshot(jobId, result.execution)) {
+                return textResult(`could not confirm cancellation of ${jobId}: the daemon returned a mismatched execution snapshot`, true);
+            }
+            if (result.execution.status !== "running")
+                await this.recordTreeDelta(jobId);
+            const current = this.jobs.find(jobId);
+            return textResult(current?.status === "cancelled"
+                ? `cancelled ${jobId}`
+                : `${jobId} was already ${current?.status ?? result.execution.status}`);
+        }
         const cancelled = this.jobs.cancel(jobId);
         if (cancelled)
             void this.recordTreeDelta(jobId);
@@ -815,6 +898,7 @@ export class McpDispatchServer {
             readOnly: args["readOnly"] === true,
             scope: readStringArray(args, "scope"),
             tier: view.tier ?? undefined,
+            host: view.host,
             timeoutMs: readNumber(args, "timeoutMs") ?? DEFAULT_LANE_TIMEOUT_MS,
             idleMs: walk !== null ? walk.idleMs : null,
             system: readString(args, "system"),
@@ -830,6 +914,7 @@ export class McpDispatchServer {
         });
         if (!readOnlyVerdictResult.ok)
             return textResult(readOnlyVerdictResult.refusal, true);
+        await this.brokerStartup;
         const first = view.ladder.find((l) => l.id === ordered[0]) ?? view.next;
         const job = this.jobs.create(first.id, first.spec, opts.cwd, opts.dispatchSource, taskLabel(task));
         this.jobs.noteWalkScope(job.id, { enabled: walk !== null, lanesNotTried: notTried, forced });
@@ -846,7 +931,10 @@ export class McpDispatchServer {
             this.jobs.fail(job.id, `dispatch walk failed: ${e.message}`);
             return "done";
         })
-            .finally(() => this.activityTags.delete(job.id));
+            .finally(() => {
+            this.activityTags.delete(job.id);
+            this.processCpu.delete(job.id);
+        });
         return this.awaitOrPoll(job.id, settled, waitMs.waitMs, {
             clamp: waitMs.clamped ? { requested: waitMs.requested, ceiling, key: ceilingKey } : undefined,
             progressToken: blocking?.progress === true ? ctx.progressToken : undefined,
@@ -871,6 +959,7 @@ export class McpDispatchServer {
     }
     async runWalk(jobId, view, laneIds, task, opts) {
         await this.startTreeDelta(jobId, opts);
+        let ranAttempt = false;
         for (let i = 0; i < laneIds.length; i++) {
             if (this.jobs.get(jobId)?.status !== "running")
                 return "done";
@@ -883,6 +972,12 @@ export class McpDispatchServer {
             const readOnly = this.bindReadOnlyOrSkip(jobId, lane, opts);
             if (readOnly.skipped)
                 continue;
+            if (ranAttempt) {
+                await this.resetLaneTreeActivity(jobId);
+                if (this.jobs.get(jobId)?.status !== "running")
+                    return "done";
+            }
+            ranAttempt = true;
             this.jobs.setCurrentLane(jobId, lane.id, lane.spec, lane.timeToAnswer);
             if (readOnly.bound !== undefined)
                 this.jobs.noteReadOnly(jobId, lane.id, readOnly.bound.binding);
@@ -919,6 +1014,11 @@ export class McpDispatchServer {
                 requestedMode: opts.mode,
                 adHoc: lane.adHoc === true,
             }, outcome.run.stdout.length, { status, wallClockMs: elapsedMs, exitCode: outcome.run.code });
+            if (status !== "completed" && !isLast && this.jobs.brokerExecution(jobId) !== undefined) {
+                this.jobs.clearBrokerExecution(jobId);
+                this.liveBrokerSnapshots.delete(jobId);
+                this.brokerCpu.delete(jobId);
+            }
             if (status === "completed" || isLast) {
                 await this.recordTreeDelta(jobId);
                 this.jobs.complete(jobId, outcome.run, status === "completed" ? undefined : (outcome.semanticFailure ?? reason), outcome.relay);
@@ -941,8 +1041,168 @@ export class McpDispatchServer {
         if (opts.mode !== "agent")
             return;
         const before = await this.readTree(opts.cwd);
-        if (before !== null)
-            this.trees.set(jobId, { cwd: opts.cwd, before, scope: opts.scope });
+        if (before !== null) {
+            this.trees.set(jobId, { cwd: opts.cwd, before, scope: opts.scope, activityLastSeen: before });
+            this.jobs.noteStartingTree(jobId, before, opts.scope);
+        }
+    }
+    async restoreBrokerOrphans() {
+        const rows = this.jobs.takeBrokerOrphans();
+        await Promise.all(rows.map(async (row) => {
+            const job = this.jobs.adoptBrokerRunning(row);
+            if (job === undefined)
+                return;
+            if (row.startingTree !== undefined) {
+                const before = {
+                    prefix: row.startingTree.prefix,
+                    entries: new Map(row.startingTree.entries),
+                };
+                this.trees.set(row.jobId, {
+                    cwd: row.cwd,
+                    before,
+                    scope: row.startingTree.scope,
+                });
+            }
+            this.noteBrokerRecoveryUnavailable(row.jobId, "recovered-broker-pending");
+        }));
+    }
+    async refreshAllBrokerJobs() {
+        const pending = this.jobs
+            .list()
+            .filter((job) => job.status === "running" && this.jobs.brokerExecution(job.id) !== undefined)
+            .map((job) => this.refreshBrokerJob(job.id));
+        await Promise.all(pending);
+    }
+    async refreshBrokerJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (job !== undefined && job.restored !== true)
+            return false;
+        const executionId = this.jobs.brokerExecution(jobId);
+        if (executionId === undefined)
+            return false;
+        const client = this.deps.laneExecutionClient;
+        if (client === undefined) {
+            this.noteBrokerRecoveryUnavailable(jobId, "broker-client-unavailable");
+            return true;
+        }
+        let result;
+        try {
+            result = await client.request({ action: "status", executionId });
+        }
+        catch {
+            this.noteBrokerRecoveryUnavailable(jobId, "broker-client-threw");
+            return true;
+        }
+        if (!result.ok) {
+            if (result.kind === "rejected" && result.status === 404 && result.message === UNKNOWN_LANE_EXECUTION_MESSAGE) {
+                const killed = this.jobs.markBrokerKilled(jobId, "the relay daemon is reachable but no longer knows this recovered lane execution; " +
+                    "the execution ended outside the retained broker window or the daemon restarted");
+                if (killed) {
+                    this.brokerCpu.delete(jobId);
+                    await this.recordTreeDelta(jobId);
+                }
+            }
+            else {
+                this.noteBrokerRecoveryUnavailable(jobId, result.kind === "invalid-response" ? "broker-response-invalid" : "broker-unavailable");
+            }
+            return true;
+        }
+        const snapshot = result.execution;
+        if (!this.jobs.applyBrokerSnapshot(jobId, snapshot)) {
+            this.noteBrokerRecoveryUnavailable(jobId, "broker-response-mismatch");
+            return true;
+        }
+        if (snapshot.status === "running") {
+            await this.noteRecoveredBrokerLiveness(jobId, snapshot);
+        }
+        else {
+            this.brokerCpu.delete(jobId);
+            await this.recordTreeDelta(jobId);
+        }
+        return true;
+    }
+    noteBrokerRecoveryUnavailable(jobId, source) {
+        const job = this.jobs.get(jobId);
+        if (job === undefined || job.status !== "running")
+            return;
+        this.jobs.noteLiveness(jobId, {
+            activity: "unmonitored",
+            verdict: "no-idle-stop",
+            checkedAt: this.now(),
+            idleBaselineAt: job.activity?.attemptStartedAt ?? job.startedAt,
+            lastActivityAt: job.liveness?.lastActivityAt ?? null,
+            source,
+            idleMs: null,
+        });
+    }
+    async noteRecoveredBrokerLiveness(jobId, snapshot) {
+        const now = this.now();
+        const seen = [
+            { at: snapshot.lastOutputAt, source: "lane-output" },
+            snapshot.relayInFlight !== undefined && snapshot.relayInFlight > 0
+                ? { at: now, source: "relay-in-flight" }
+                : { at: snapshot.relayLastActivityAt, source: "relay-traffic" },
+        ];
+        if (snapshot.cpuMs !== undefined) {
+            const previous = this.brokerCpu.get(jobId);
+            this.brokerCpu.set(jobId, snapshot.cpuMs);
+            if (previous !== undefined && snapshot.cpuMs - previous >= PROCESS_CPU_ACTIVITY_MS) {
+                seen.push({ at: now, source: "process-cpu" });
+            }
+        }
+        const tree = this.trees.get(jobId);
+        const reading = tree === undefined ? null : await this.readTree(tree.cwd);
+        if (tree !== undefined && reading !== null) {
+            const previous = tree.activityLastSeen;
+            tree.activityLastSeen = reading;
+            if (previous !== undefined) {
+                seen.push(sameTree(previous, reading)
+                    ? { at: newestChangeMs(tree.cwd, reading), source: "file-change" }
+                    : { at: now, source: "working-tree" });
+            }
+        }
+        const previous = this.jobs.get(jobId)?.liveness;
+        if (previous?.lastActivityAt !== null && previous?.lastActivityAt !== undefined) {
+            seen.push({ at: previous.lastActivityAt, source: previous.source });
+        }
+        const latest = newestActivity(seen);
+        const activity = snapshot.relayInFlight !== undefined && snapshot.relayInFlight > 0
+            ? "active"
+            : latest === null
+                ? "unmonitored"
+                : now - latest.at < IDLE_POLL_MS
+                    ? "active"
+                    : "quiet";
+        this.jobs.noteLiveness(jobId, {
+            activity,
+            verdict: "no-idle-stop",
+            checkedAt: now,
+            idleBaselineAt: snapshot.startedAt,
+            lastActivityAt: latest?.at ?? null,
+            source: latest?.source ?? "recovered-broker",
+            idleMs: null,
+        });
+    }
+    async restoreKilledTreeDeltas() {
+        const adopted = this.jobs.takeAdoptedStartingTrees();
+        await Promise.all(adopted.map(async ({ jobId, cwd, startingTree }) => {
+            const after = await this.readTree(cwd);
+            if (after === null)
+                return;
+            const before = { prefix: startingTree.prefix, entries: new Map(startingTree.entries) };
+            const delta = renderTreeDelta(cwd, before, after, startingTree.scope);
+            this.jobs.noteTreeDelta(jobId, `${delta}\n  note: measured at restart adoption time, not at the time the job was killed`);
+        }));
+    }
+    async resetLaneTreeActivity(jobId) {
+        const tree = this.trees.get(jobId);
+        if (tree === undefined)
+            return;
+        const reading = await this.readTree(tree.cwd);
+        if (reading === null)
+            delete tree.activityLastSeen;
+        else
+            tree.activityLastSeen = reading;
     }
     async recordTreeDelta(jobId) {
         const tree = this.trees.get(jobId);
@@ -999,7 +1259,8 @@ export class McpDispatchServer {
             spec: lane.spec,
             status: SKIPPED_LANE_STATUS,
             elapsedMs: 0,
-            reason: `lane "${lane.id}" declares capability ${lane.capability}, below this ${opts.tier} dispatch`,
+            reason: `lane "${lane.id}" has derived capability ${lane.capability}` +
+                `${lane.capabilityBasis ? ` (${lane.capabilityBasis})` : ""}, below this ${opts.tier} dispatch`,
         });
         this.jobs.noteSkippedLane(jobId);
         return true;
@@ -1007,26 +1268,56 @@ export class McpDispatchServer {
     async latestActivity(jobId) {
         const now = this.now();
         const seen = [
-            { at: this.jobs.get(jobId)?.activity?.lastOutputAt, source: "lane output" },
+            { at: this.jobs.get(jobId)?.activity?.lastOutputAt, source: "lane-output" },
         ];
+        const broker = this.liveBrokerSnapshots.get(jobId);
+        if (broker !== undefined) {
+            seen.push(broker.relayInFlight !== undefined && broker.relayInFlight > 0
+                ? { at: now, source: "relay-in-flight" }
+                : { at: broker.relayLastActivityAt, source: "relay-traffic" });
+            if (broker.cpuMs !== undefined) {
+                const previous = this.brokerCpu.get(jobId);
+                this.brokerCpu.set(jobId, broker.cpuMs);
+                if (previous !== undefined && broker.cpuMs - previous >= PROCESS_CPU_ACTIVITY_MS) {
+                    seen.push({ at: now, source: "process-cpu" });
+                }
+            }
+        }
         const tag = this.activityTags.get(jobId);
-        if (tag !== undefined && this.deps.readLaneActivity !== undefined) {
+        if (broker === undefined && tag !== undefined && this.deps.readLaneActivity !== undefined) {
             const traffic = await this.deps.readLaneActivity(tag).catch(() => null);
             seen.push(traffic !== null && traffic.inFlight > 0
-                ? { at: now, source: "a request in flight at the relay" }
-                : { at: traffic?.lastActivityAt, source: "relay traffic" });
+                ? { at: now, source: "relay-in-flight" }
+                : { at: traffic?.lastActivityAt, source: "relay-traffic" });
         }
         const early = newestActivity(seen);
         if (early !== null && now - early.at < IDLE_POLL_MS)
             return early;
+        const pids = broker === undefined ? this.jobs.runningPids(jobId) : [];
+        if (pids.length > 0 && this.deps.readProcessCpu !== undefined) {
+            const cpuMs = await this.deps.readProcessCpu(pids).catch(() => null);
+            if (typeof cpuMs === "number" && Number.isFinite(cpuMs) && cpuMs >= 0) {
+                const previous = this.processCpu.get(jobId);
+                this.processCpu.set(jobId, cpuMs);
+                if (previous !== undefined && cpuMs - previous >= PROCESS_CPU_ACTIVITY_MS) {
+                    seen.push({ at: this.now(), source: "process-cpu" });
+                }
+            }
+        }
+        const afterCpu = newestActivity(seen);
+        const afterCpuNow = this.now();
+        if (afterCpu !== null && afterCpuNow - afterCpu.at < IDLE_POLL_MS)
+            return afterCpu;
         const tree = this.trees.get(jobId);
         const reading = tree === undefined ? null : await this.readTree(tree.cwd);
         if (tree !== undefined && reading !== null) {
-            const previous = tree.lastSeen ?? tree.before;
-            tree.lastSeen = reading;
-            seen.push(sameTree(previous, reading)
-                ? { at: newestChangeMs(tree.cwd, reading), source: "a file change" }
-                : { at: now, source: "a working tree change" });
+            const previous = tree.activityLastSeen;
+            tree.activityLastSeen = reading;
+            if (previous !== undefined) {
+                seen.push(sameTree(previous, reading)
+                    ? { at: newestChangeMs(tree.cwd, reading), source: "file-change" }
+                    : { at: now, source: "working-tree" });
+            }
         }
         return newestActivity(seen);
     }
@@ -1052,19 +1343,48 @@ export class McpDispatchServer {
     }
     async runOneLane(jobId, lane, task, opts, idleMs, invoke) {
         const attemptStart = this.now();
-        const started = this.startLane(jobId, lane, task, opts, invoke);
+        const started = await this.startLane(jobId, lane, task, opts, invoke);
         if ("refusal" in started)
             return { run: emptyRun(), abandoned: false, refusal: started.refusal };
-        this.jobs.registerProcess(jobId, started);
+        if (started.brokerExecutionId === undefined) {
+            this.jobs.registerProcess(jobId, started);
+        }
+        this.processCpu.delete(jobId);
+        this.brokerCpu.delete(jobId);
         const guarded = started.result.catch((e) => ({
             run: { code: null, stdout: "", stderr: e.message, timedOut: false },
             abandoned: false,
             semanticFailure: e.message,
         }));
-        if (idleMs === null)
+        if (idleMs === null) {
+            this.jobs.noteLiveness(jobId, {
+                activity: "unmonitored",
+                verdict: "no-idle-stop",
+                checkedAt: attemptStart,
+                idleBaselineAt: attemptStart,
+                lastActivityAt: null,
+                source: "attempt-start",
+                idleMs: null,
+            });
             return guarded;
-        const settled = guarded.then((o) => ({ kind: "settled", outcome: o }));
+        }
+        this.jobs.noteLiveness(jobId, {
+            activity: "starting",
+            verdict: "keep-running",
+            checkedAt: attemptStart,
+            idleBaselineAt: attemptStart,
+            lastActivityAt: null,
+            source: "attempt-start",
+            idleMs,
+        });
+        let settledOutcome = null;
+        const settled = guarded.then((o) => {
+            settledOutcome = o;
+            return { kind: "settled", outcome: o };
+        });
         let lastActive = attemptStart;
+        let lastRealActivity = null;
+        let lastSource = "attempt-start";
         for (;;) {
             const raced = await Promise.race([settled, pollTimer(Math.min(IDLE_POLL_MS, idleMs))]);
             if (raced.kind === "settled")
@@ -1072,17 +1392,177 @@ export class McpDispatchServer {
             if (this.jobs.get(jobId)?.status !== "running")
                 break;
             const seen = await this.latestActivity(jobId);
-            if (seen !== null && seen.at > lastActive) {
+            const afterProbe = await Promise.race([settled, pollTimer(0)]);
+            if (afterProbe.kind === "settled")
+                return afterProbe.outcome;
+            if (settledOutcome !== null)
+                return settledOutcome;
+            if (this.jobs.get(jobId)?.status !== "running")
+                break;
+            const fresh = seen !== null && seen.at > lastActive;
+            if (fresh && seen !== null) {
                 lastActive = seen.at;
-                this.jobs.noteLastActivity(jobId, seen.at, seen.source);
+                lastRealActivity = seen.at;
+                lastSource = seen.source;
             }
-            if (this.now() - lastActive >= idleMs)
+            const checkedAt = this.now();
+            const idle = checkedAt - lastActive >= idleMs;
+            if (idle) {
+                this.jobs.noteLiveness(jobId, {
+                    activity: "advancing",
+                    verdict: "keep-running",
+                    checkedAt,
+                    idleBaselineAt: lastActive,
+                    lastActivityAt: lastRealActivity,
+                    source: lastSource,
+                    idleMs,
+                });
                 break;
+            }
+            this.jobs.noteLiveness(jobId, {
+                activity: fresh ? "active" : "quiet",
+                verdict: "keep-running",
+                checkedAt,
+                idleBaselineAt: lastActive,
+                lastActivityAt: lastRealActivity,
+                source: lastSource,
+                idleMs,
+            });
         }
         started.kill();
+        if (started.waitForKill !== undefined)
+            await started.waitForKill();
         return { run: emptyRun(), abandoned: true };
     }
-    startLane(jobId, lane, task, opts, invokeOverride) {
+    async brokerRequest(request) {
+        const client = this.deps.laneExecutionClient;
+        if (client === undefined) {
+            return { ok: false, kind: "unavailable", status: null, message: "lane execution broker client is unavailable" };
+        }
+        try {
+            return await client.request(request);
+        }
+        catch {
+            return { ok: false, kind: "unavailable", status: null, message: "lane execution broker client failed" };
+        }
+    }
+    brokerSnapshotMatches(snapshot, jobId, laneId, executionId) {
+        return snapshot.executionId === executionId && snapshot.jobId === jobId && snapshot.laneId === laneId;
+    }
+    brokerRun(snapshot) {
+        return {
+            code: snapshot.code ?? null,
+            stdout: snapshot.stdout ?? "",
+            stderr: snapshot.stderr ?? "",
+            timedOut: snapshot.timedOut ?? snapshot.status === "timed_out",
+        };
+    }
+    async waitBrokerLane(jobId, lane, invoke, opts, startedAt, startRequest, initial) {
+        let response = initial;
+        let startConfirmed = initial.ok;
+        for (;;) {
+            if (response.ok) {
+                const snapshot = response.execution;
+                if (!this.brokerSnapshotMatches(snapshot, jobId, lane.id, startRequest.executionId)) {
+                    await pollTimer(BROKER_STATUS_POLL_MS);
+                    response = await this.brokerRequest({ action: "status", executionId: startRequest.executionId });
+                    continue;
+                }
+                startConfirmed = true;
+                if (snapshot.status === "running") {
+                    this.liveBrokerSnapshots.set(jobId, snapshot);
+                    this.jobs.applyBrokerSnapshot(jobId, snapshot);
+                    await pollTimer(BROKER_STATUS_POLL_MS);
+                    response = await this.brokerRequest({ action: "status", executionId: startRequest.executionId });
+                    continue;
+                }
+                this.liveBrokerSnapshots.delete(jobId);
+                this.brokerCpu.delete(jobId);
+                return this.settleSpawnedRun(jobId, lane, invoke, opts, startedAt, this.brokerRun(snapshot));
+            }
+            if (!startConfirmed) {
+                if (response.kind === "rejected" && response.status !== null) {
+                    this.jobs.clearBrokerExecution(jobId);
+                    return failedOutcome(response.message);
+                }
+                await pollTimer(BROKER_STATUS_POLL_MS);
+                response = await this.brokerRequest(startRequest);
+                continue;
+            }
+            if (response.kind === "rejected") {
+                this.jobs.clearBrokerExecution(jobId);
+                this.liveBrokerSnapshots.delete(jobId);
+                this.brokerCpu.delete(jobId);
+                return failedOutcome(response.status === 404
+                    ? "the relay daemon lost the brokered lane execution before it returned a terminal result"
+                    : response.message);
+            }
+            await pollTimer(BROKER_STATUS_POLL_MS);
+            response = await this.brokerRequest({ action: "status", executionId: startRequest.executionId });
+        }
+    }
+    async stopBrokerLane(executionId) {
+        for (;;) {
+            const response = await this.brokerRequest({ action: "cancel", executionId });
+            if (response.ok)
+                return;
+            if (response.kind === "rejected" && ((response.status === 404 && response.message === UNKNOWN_LANE_EXECUTION_MESSAGE) || response.status === 503))
+                return;
+            await pollTimer(BROKER_STATUS_POLL_MS);
+        }
+    }
+    async tryStartBrokerLane(jobId, lane, task, opts, invoke) {
+        if (this.deps.laneExecutionClient === undefined)
+            return null;
+        let executionId = createLaneExecutionId();
+        for (let collision = 0; collision < 3; collision += 1) {
+            const probe = await this.brokerRequest({ action: "status", executionId });
+            if (!probe.ok && probe.kind === "rejected" && probe.status === 404 && probe.message === UNKNOWN_LANE_EXECUTION_MESSAGE)
+                break;
+            if (!probe.ok)
+                return { fallback: probe.message };
+            executionId = createLaneExecutionId();
+            if (collision === 2)
+                return { fallback: "could not allocate a unique daemon execution id" };
+        }
+        const startRequest = {
+            action: "start",
+            executionId,
+            jobId,
+            laneId: lane.id,
+            task,
+            cwd: opts.cwd,
+            timeoutMs: opts.timeoutMs,
+            depth: opts.depth,
+            ...(opts.tier === undefined ? {} : { tier: opts.tier }),
+            ...(opts.readOnly ? { readOnly: true, callerRoot: this.cwd() } : {}),
+            host: opts.host,
+        };
+        this.jobs.noteBrokerExecution(jobId, executionId);
+        this.jobs.noteExecutionOwner(jobId, "relay-daemon");
+        const startedAt = this.now();
+        const initial = await this.brokerRequest(startRequest);
+        if (!initial.ok && initial.kind === "rejected" && initial.status !== null) {
+            this.jobs.clearBrokerExecution(jobId);
+            if (initial.status === 503)
+                return { fallback: initial.message };
+            return {
+                result: Promise.resolve(failedOutcome(initial.message)),
+                kill: () => { },
+            };
+        }
+        let cancelPromise;
+        const result = this.waitBrokerLane(jobId, lane, invoke, opts, startedAt, startRequest, initial);
+        return {
+            result,
+            brokerExecutionId: executionId,
+            kill: () => {
+                cancelPromise ??= this.stopBrokerLane(executionId);
+            },
+            waitForKill: () => cancelPromise ?? Promise.resolve(),
+        };
+    }
+    async startLane(jobId, lane, task, opts, invokeOverride) {
         if (opts.mode === "answer" && lane.kind === "relay") {
             if (!lane.spec) {
                 return {
@@ -1092,7 +1572,7 @@ export class McpDispatchServer {
             }
             const controller = new AbortController();
             const signal = AbortSignal.any([AbortSignal.timeout(opts.timeoutMs), controller.signal]);
-            const tag = newActivityTag();
+            const tag = createLaneActivityTag();
             this.activityTags.set(jobId, tag);
             const result = this.runAnswerFetch(lane.spec, task, opts, signal, tag).then((o) => {
                 const semanticFailure = o.semanticFailure === undefined && !o.run.timedOut && isContentEmpty(o.run.stdout)
@@ -1121,14 +1601,20 @@ export class McpDispatchServer {
                 kill: () => { },
             };
         }
+        const broker = await this.tryStartBrokerLane(jobId, lane, task, opts, declared);
+        if (broker !== null && !("fallback" in broker))
+            return broker;
+        if (broker !== null && "fallback" in broker) {
+            this.jobs.noteExecutionOwner(jobId, "local-fallback");
+        }
         const agy = agyWorkingDirInvoke(declared, opts.cwd);
         const invoke = agy?.invoke ?? declared;
-        const expansion = expandEnvReferences(applyLaneEnv(process.env, invoke.env), this.deps.platform);
+        const expansion = expandEnvReferences(buildLaneEnv(process.env, invoke.env, this.deps.config, this.deps.platform), this.deps.platform);
         const env = expansion.env;
         env[DEPTH_ENV] = String(opts.depth + 1);
-        const tag = newActivityTag();
+        const tag = createLaneActivityTag();
         this.activityTags.set(jobId, tag);
-        env["ANTHROPIC_CUSTOM_HEADERS"] = withActivityHeader(env["ANTHROPIC_CUSTOM_HEADERS"], tag);
+        env["ANTHROPIC_CUSTOM_HEADERS"] = withLaneActivityHeader(env["ANTHROPIC_CUSTOM_HEADERS"], tag);
         this.jobs.noteLaunch(jobId, [...expansion.notes, ...(agy === null ? [] : [agy.note])]);
         const startedAt = this.now();
         this.jobs.beginAttemptActivity(jobId, startedAt);