llm-relay 0.82.2 → 0.83.1

package/dist/mcp/server.js

@@ -1,9 +1,10 @@
-import { DEFAULT_MCP_MAX_WAIT_MS } from "../config-types.js";
+import { DEFAULT_MCP_BLOCKING_WAIT_MS, DEFAULT_MCP_MAX_WAIT_MS, EFFORT_LEVELS } from "../config-types.js";
 import { isToolUseBlock } from "../anthropic.js";
 import { formatAttemptBudget, formatLaneStats, isPassThroughSpec, LANE_UNRELIABLE_STREAK, mcpPassThroughReason } from "../dispatch.js";
 import { laneOfRung } from "../lane-manifest.js";
+import { defaultTreeSnapshot, newestChangeMs, renderTreeDelta, sameTree, } from "./tree-delta.js";
 import { estimateTokensFromCharacters } from "../metadata.js";
-import { DEFAULT_LANE_TIMEOUT_MS, DEFAULT_MAX_DEPTH, DEPTH_ENV, EMPTY_OUTPUT_REASON, LaneJobStore, SKIPPED_LANE_STATUS, attemptWasTried, classifyDispatchedResult, classifyLaneAttempt, checkCwd, currentDepth, defaultAnswerFetch, defaultLaneSpawner, isContentEmpty, readRelayAnnouncements, relayLoopbackUrl, } from "./lane-runner.js";
+import { DEFAULT_LANE_TIMEOUT_MS, DEFAULT_MAX_DEPTH, DEPTH_ENV, EMPTY_OUTPUT_REASON, LaneJobStore, SKIPPED_LANE_STATUS, agyWorkingDirInvoke, attemptWasTried, classifyDispatchedResult, classifyLaneAttempt, checkCwd, currentDepth, defaultAnswerFetch, defaultLaneSpawner, expandEnvReferences, isContentEmpty, readRelayAnnouncements, relayLoopbackUrl, } from "./lane-runner.js";
 import { readOnlyInvoke, readOnlyVerdict } from "./readonly-boundary.js";
 import { agyQuotaStatement } from "./agy-quota-log.js";
 import { nullJobJournal } from "./job-journal.js";
@@ -11,6 +12,7 @@ import { nullJobArchive } from "./job-archive.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;
+export const RECENT_JOBS_LISTED = 20;
 export const MCP_INSTRUCTIONS = "Use dispatch from every MCP host — Claude, Codex, desktop, CLI, or otherwise — to hand a " +
     "whole task to another agent lane and get its answer back. Never choose a host-specific child " +
     "mechanism yourself; whether the lane is a model pool or a peer CLI is resolved here.\n\n" +
@@ -55,7 +57,8 @@ const TOOLS = [
             "environment and idle timeouts are handled here, so you never build a command line. If the " +
             "lane is still running, returns a jobId to poll with dispatch_status — it blocks at most " +
             "routing.mcp.maxWaitMs first, so a slow lane degrades to polling instead of hitting the " +
-            "host's tool timeout. In Codex " +
+            "host's tool timeout. In Claude Code, a call that carries a progress token instead waits " +
+            "for the answer (up to routing.mcp.blockingWaitMs) and reports progress. In Codex " +
             "Desktop, use this instead of a pool/* collaboration child, which the ChatGPT launcher " +
             "rejects before the custom provider or relay is reached. Set mode to \"answer\" for a " +
             "question, draft, summary, or second opinion that needs no file access — it posts straight " +
@@ -111,13 +114,22 @@ const TOOLS = [
                 },
                 waitMs: {
                     type: "number",
-                    description: "How long to block before returning a jobId instead (default routing.mcp.maxWaitMs; " +
-                        "a larger waitMs is clamped to that ceiling and the clamp is announced in the reply).",
+                    description: "How long to block before returning a jobId instead (default routing.mcp.maxWaitMs, or " +
+                        "routing.mcp.blockingWaitMs for a Claude Code call that asked for progress; a larger " +
+                        "waitMs is clamped to that ceiling and the clamp is announced in the reply).",
                 },
                 timeoutMs: {
                     type: "number",
                     description: `Hard ceiling on the lane run (default ${DEFAULT_LANE_TIMEOUT_MS}).`,
                 },
+                scope: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Agent mode only: the paths or globs (relative to cwd) the task may change. The answer " +
+                        "always lists what changed in the git tree (a `tree delta` block); with scope, every " +
+                        "changed path outside it is marked OUT OF SCOPE. The relay reports only — it never " +
+                        "refuses or reverts.",
+                },
                 readOnly: {
                     type: "boolean",
                     description: "Declare that this dispatch must not mutate anything — a review, a survey, a second " +
@@ -139,12 +151,15 @@ const TOOLS = [
     {
         name: "dispatch_status",
         title: "Check a dispatched job",
-        description: "Report whether a dispatched lane is still running, and for how long. Poll this after " +
-            "dispatch returned a jobId. Wait at least a few seconds between polls.",
+        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 " +
+            "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: {
             type: "object",
-            properties: { jobId: { type: "string", description: "The jobId dispatch returned." } },
-            required: ["jobId"],
+            properties: {
+                jobId: { type: "string", description: "The jobId dispatch returned. Omit it to list recent jobs." },
+            },
             additionalProperties: false,
         },
     },
@@ -215,6 +230,13 @@ export function resolveWaitMs(requested, ceiling) {
     }
     return { waitMs: requested, clamped: false, requested };
 }
+function readStringArray(params, key) {
+    const value = params[key];
+    if (!Array.isArray(value))
+        return undefined;
+    const strings = value.filter((v) => typeof v === "string" && v.trim() !== "");
+    return strings.length > 0 ? strings : undefined;
+}
 function readRecord(params, key) {
     const v = params[key];
     return typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
@@ -273,6 +295,23 @@ function laneEvidenceBits(lane) {
         bits.push(`${lane.recentFailures} own failure${lane.recentFailures === 1 ? "" : "s"} in a row`);
     return bits;
 }
+function relayProvenanceLines(job) {
+    const relay = job.relay;
+    if (!relay)
+        return [];
+    const lines = [];
+    if (relay.servedBy)
+        lines.push(`served-by: ${relay.servedBy}`);
+    if (relay.poolAttempts)
+        lines.push(`pool-attempts: ${relay.poolAttempts}`);
+    if (relay.hedged)
+        lines.push(`hedged: ${relay.hedged}`);
+    if (relay.latencyDemoted)
+        lines.push(`latency-demoted: ${relay.latencyDemoted}`);
+    if (relay.degraded)
+        lines.push(`degraded: ${relay.degraded}`);
+    return lines;
+}
 function describeJob(job, now) {
     const elapsed = Math.round(((job.endedAt ?? now) - job.startedAt) / 1000);
     const head = [
@@ -287,22 +326,18 @@ function describeJob(job, now) {
         head.push("timed out: yes");
     if (job.error)
         head.push(`error: ${job.error}`);
-    if (job.relay?.servedBy)
-        head.push(`served-by: ${job.relay.servedBy}`);
-    if (job.relay?.poolAttempts)
-        head.push(`pool-attempts: ${job.relay.poolAttempts}`);
-    if (job.relay?.hedged)
-        head.push(`hedged: ${job.relay.hedged}`);
-    if (job.relay?.latencyDemoted)
-        head.push(`latency-demoted: ${job.relay.latencyDemoted}`);
-    if (job.relay?.degraded)
-        head.push(`degraded: ${job.relay.degraded}`);
+    head.push(...relayProvenanceLines(job));
     if (job.dispatchSource === "fallback")
         head.push("dispatch-source: local-fallback (daemon unreachable)");
-    if (job.restored === true)
-        head.push("record: restored from disk — this job ended before the llm-relay MCP server last restarted");
+    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");
+    }
     if (job.readOnly)
         head.push(`read-only: ${job.readOnly.binding}`);
+    if (job.launch?.length)
+        head.push(`launch: ${job.launch.join("; ")}`);
+    if (job.extended?.length)
+        head.push(`extended: ${job.extended.join("; ")}`);
     const usually = runningTimeToAnswer(job);
     if (usually !== null)
         head.push(usually);
@@ -355,6 +390,10 @@ function describeAttempts(job) {
     return `lanes tried:\n${lines.join("\n")}${capped}`;
 }
 function jobAnswer(job, now) {
+    const answer = jobAnswerBody(job, now);
+    return job.treeDelta === undefined ? answer : `${answer}\n\n${job.treeDelta}`;
+}
+function jobAnswerBody(job, now) {
     const header = describeJob(job, now);
     const body = job.stdout.trim();
     const nothingAnswered = job.status !== "running"
@@ -412,6 +451,14 @@ function flagValue(args, flag) {
     const joined = args.find((a) => a.startsWith(`${flag}=`));
     return joined === undefined ? null : joined.slice(flag.length + 1);
 }
+export const LANE_ACTIVITY_WINDOW_MS = 60_000;
+function budgetTimer(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(() => resolve({ kind: "budget" }), ms);
+        if (typeof t.unref === "function")
+            t.unref();
+    });
+}
 function laneAnswered(r) {
     return r.code === 0 && !r.timedOut && !isContentEmpty(r.stdout);
 }
@@ -454,6 +501,8 @@ function laneSummary(lane, inFlight) {
         bits.push(formatLaneStats(lane.stats));
     return bits.join(" ");
 }
+export const BLOCKING_WAIT_CLIENTS = ["claude-code"];
+export const PROGRESS_INTERVAL_MS = 30_000;
 export class McpDispatchServer {
     deps;
     jobs;
@@ -463,6 +512,9 @@ export class McpDispatchServer {
     cwd;
     maxDepth;
     buffer = "";
+    clientName;
+    cancellable = new Map();
+    trees = new Map();
     constructor(deps) {
         this.deps = deps;
         this.jobs = new LaneJobStore(deps.journal ?? nullJobJournal, deps.archive ?? nullJobArchive);
@@ -505,12 +557,20 @@ export class McpDispatchServer {
             this.deps.write(encodeMessage({ jsonrpc: "2.0", id: 0, error: { code: RPC_PARSE_ERROR, message: "invalid JSON" } }));
             return;
         }
-        if (isJsonRpcNotification(parsed))
+        if (isJsonRpcNotification(parsed)) {
+            if (parsed.method === "notifications/cancelled")
+                this.cancelRequest(parsed.params);
             return;
+        }
         if (!isJsonRpcRequest(parsed))
             return;
+        const abort = new AbortController();
+        if (parsed.method === "tools/call")
+            this.cancellable.set(parsed.id, abort);
         try {
-            const result = await this.route(parsed.method, parsed.params);
+            const result = await this.route(parsed.method, parsed.params, abort.signal);
+            if (abort.signal.aborted)
+                return;
             if (result === undefined) {
                 this.send(errorResponse(parsed.id, RPC_METHOD_NOT_FOUND, `unknown method: ${parsed.method}`));
                 return;
@@ -520,8 +580,20 @@ export class McpDispatchServer {
         catch (e) {
             this.send(errorResponse(parsed.id, RPC_INTERNAL_ERROR, e.message));
         }
+        finally {
+            if (this.cancellable.get(parsed.id) === abort)
+                this.cancellable.delete(parsed.id);
+        }
     }
-    async route(method, params) {
+    cancelRequest(params) {
+        if (typeof params !== "object" || params === null)
+            return;
+        const id = params["requestId"];
+        if (typeof id !== "string" && typeof id !== "number")
+            return;
+        this.cancellable.get(id)?.abort();
+    }
+    async route(method, params, signal) {
         switch (method) {
             case "initialize":
                 return this.initialize(params);
@@ -530,13 +602,16 @@ export class McpDispatchServer {
             case "tools/list":
                 return { tools: TOOLS };
             case "tools/call":
-                return this.callTool(params);
+                return this.callTool(params, signal);
             default:
                 return undefined;
         }
     }
     initialize(params) {
         const p = (typeof params === "object" && params !== null ? params : {});
+        const info = p["clientInfo"];
+        const name = typeof info === "object" && info !== null ? info["name"] : undefined;
+        this.clientName = typeof name === "string" ? name : undefined;
         return {
             protocolVersion: negotiateProtocolVersion(p["protocolVersion"]),
             capabilities: { tools: { listChanged: false } },
@@ -544,7 +619,7 @@ export class McpDispatchServer {
             instructions: MCP_INSTRUCTIONS,
         };
     }
-    async callTool(params) {
+    async callTool(params, signal) {
         const p = (typeof params === "object" && params !== null ? params : {});
         const name = p["name"];
         const args = (typeof p["arguments"] === "object" && p["arguments"] !== null
@@ -553,12 +628,18 @@ export class McpDispatchServer {
         if (typeof name !== "string") {
             throw Object.assign(new Error("tools/call requires a tool name"), { code: RPC_INVALID_PARAMS });
         }
-        return this.withVersionNotice(await this.runTool(name, args));
+        const meta = p["_meta"];
+        const token = typeof meta === "object" && meta !== null ? meta["progressToken"] : undefined;
+        const ctx = {
+            progressToken: typeof token === "string" || typeof token === "number" ? token : undefined,
+            signal,
+        };
+        return this.withVersionNotice(await this.runTool(name, args, ctx));
     }
-    async runTool(name, args) {
+    async runTool(name, args, ctx) {
         switch (name) {
             case "dispatch":
-                return this.toolDispatch(args);
+                return this.toolDispatch(args, ctx);
             case "dispatch_status":
                 return this.toolStatus(args);
             case "dispatch_result":
@@ -608,32 +689,72 @@ export class McpDispatchServer {
     toolStatus(args) {
         const jobId = readString(args, "jobId");
         if (!jobId)
-            return textResult("dispatch_status requires jobId", true);
-        const job = this.jobs.get(jobId);
+            return textResult(this.recentJobs());
+        const job = this.jobs.find(jobId);
         if (!job)
-            return textResult(`unknown jobId: ${jobId}`, true);
-        return textResult(describeJob(job, this.now()));
+            return this.unknownJob(jobId);
+        if (job.status === "running")
+            return textResult(describeJob(job, this.now()));
+        return textResult(jobAnswer(job, this.now()), isFailureStatus(job.status));
     }
     toolResult(args) {
         const jobId = readString(args, "jobId");
         if (!jobId)
             return textResult("dispatch_result requires jobId", true);
-        const job = this.jobs.get(jobId);
+        const job = this.jobs.find(jobId);
         if (!job)
-            return textResult(`unknown jobId: ${jobId}`, true);
+            return this.unknownJob(jobId);
         return textResult(jobAnswer(job, this.now()), isFailureStatus(job.status));
     }
+    recentJobs() {
+        const now = this.now();
+        const rows = this.jobs.recent(RECENT_JOBS_LISTED);
+        if (rows.length === 0)
+            return "No dispatched jobs are recorded on this machine.";
+        const lines = rows.map((r) => {
+            const seconds = Math.max(0, Math.round(((r.endedAt ?? now) - r.startedAt) / 1000));
+            const where = r.elsewhere ? " [another MCP server process]" : "";
+            const label = r.label ? ` — ${r.label}` : "";
+            return `${r.id}  ${r.status}  ${seconds}s  ${r.laneId}${where}${label}`;
+        });
+        return `recent jobs (newest first):\n${lines.join("\n")}\n\nPass a jobId to read one.`;
+    }
+    unknownJob(jobId) {
+        const elsewhere = this.jobs.runningElsewhere(jobId);
+        if (elsewhere === undefined)
+            return textResult(`unknown jobId: ${jobId}`, true);
+        const elapsed = Math.max(0, Math.round((this.now() - elsewhere.startedAt) / 1000));
+        return textResult([
+            `job: ${jobId}`,
+            `lane: ${elsewhere.laneId}${elsewhere.spec ? ` (${elsewhere.spec})` : ""}`,
+            "status: running",
+            `elapsed: ${elapsed}s`,
+            `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.");
+    }
     toolCancel(args) {
         const jobId = readString(args, "jobId");
         if (!jobId)
             return textResult("dispatch_cancel requires jobId", true);
-        const job = this.jobs.get(jobId);
+        const job = this.jobs.find(jobId);
         if (!job)
-            return textResult(`unknown jobId: ${jobId}`, true);
+            return this.unknownJob(jobId);
         const cancelled = this.jobs.cancel(jobId);
+        if (cancelled)
+            void this.recordTreeDelta(jobId);
         return textResult(cancelled ? `cancelled ${jobId}` : `${jobId} was already ${job.status}`);
     }
-    async toolDispatch(args) {
+    blockingWaitFor(ctx, maxWaitMs) {
+        if (ctx.progressToken === undefined)
+            return null;
+        if (this.clientName === undefined || !BLOCKING_WAIT_CLIENTS.includes(this.clientName))
+            return null;
+        const cap = this.deps.config.routing?.mcp?.blockingWaitMs ?? DEFAULT_MCP_BLOCKING_WAIT_MS;
+        return cap > 0 ? Math.max(cap, maxWaitMs) : null;
+    }
+    async toolDispatch(args, ctx) {
         const task = readString(args, "task");
         if (!task)
             return textResult("dispatch requires a non-empty task", true);
@@ -661,6 +782,7 @@ export class McpDispatchServer {
             cwd: readString(args, "cwd") ?? this.cwd(),
             depth,
             readOnly: args["readOnly"] === true,
+            scope: readStringArray(args, "scope"),
             tier: view.tier ?? undefined,
             timeoutMs: readNumber(args, "timeoutMs") ?? DEFAULT_LANE_TIMEOUT_MS,
             attemptMs: walk !== null ? walk.attemptMs : null,
@@ -678,17 +800,25 @@ export class McpDispatchServer {
         if (!readOnlyVerdictResult.ok)
             return textResult(readOnlyVerdictResult.refusal, true);
         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);
+        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 });
-        const ceiling = this.deps.config.routing?.mcp?.maxWaitMs ?? DEFAULT_MCP_MAX_WAIT_MS;
+        const maxWaitMs = this.deps.config.routing?.mcp?.maxWaitMs ?? DEFAULT_MCP_MAX_WAIT_MS;
+        const blocking = this.blockingWaitFor(ctx, maxWaitMs);
+        const ceiling = blocking ?? maxWaitMs;
+        const ceilingKey = blocking === null ? "routing.mcp.maxWaitMs" : "routing.mcp.blockingWaitMs";
         const waitMs = resolveWaitMs(args["waitMs"], ceiling);
         if ("refusal" in waitMs)
             return textResult(waitMs.refusal, true);
-        const settled = this.runWalk(job.id, view, ordered, task, opts).catch((e) => {
+        const settled = this.runWalk(job.id, view, ordered, task, opts).catch(async (e) => {
+            await this.recordTreeDelta(job.id);
             this.jobs.fail(job.id, `dispatch walk failed: ${e.message}`);
             return "done";
         });
-        return this.awaitOrPoll(job.id, settled, waitMs.waitMs, waitMs.clamped ? { requested: waitMs.requested, ceiling } : undefined);
+        return this.awaitOrPoll(job.id, settled, waitMs.waitMs, {
+            clamp: waitMs.clamped ? { requested: waitMs.requested, ceiling, key: ceilingKey } : undefined,
+            progressToken: blocking === null ? undefined : ctx.progressToken,
+            signal: ctx.signal,
+        });
     }
     walkOrder(view, walk, forced, nextId) {
         const runnable = (id) => forced || !this.isPassThroughLane(view.ladder.find((l) => l.id === id));
@@ -707,6 +837,7 @@ export class McpDispatchServer {
         }
     }
     async runWalk(jobId, view, laneIds, task, opts) {
+        await this.startTreeDelta(jobId, opts);
         for (let i = 0; i < laneIds.length; i++) {
             if (this.jobs.get(jobId)?.status !== "running")
                 return "done";
@@ -714,7 +845,7 @@ export class McpDispatchServer {
             const lane = laneId === undefined ? undefined : view.ladder.find((l) => l.id === laneId);
             if (lane === undefined)
                 continue;
-            if (this.skipIfAtConcurrencyCap(jobId, lane))
+            if (this.skipBeforeStart(jobId, lane, opts))
                 continue;
             const readOnly = this.bindReadOnlyOrSkip(jobId, lane, opts);
             if (readOnly.skipped)
@@ -731,6 +862,7 @@ export class McpDispatchServer {
             if (this.jobs.get(jobId)?.status === "cancelled")
                 return "done";
             if (outcome.refusal !== undefined) {
+                await this.recordTreeDelta(jobId);
                 this.jobs.fail(jobId, outcome.refusal);
                 return "done";
             }
@@ -756,6 +888,7 @@ export class McpDispatchServer {
                 adHoc: lane.adHoc === true,
             }, outcome.run.stdout.length, { status, wallClockMs: elapsedMs, exitCode: outcome.run.code });
             if (status === "completed" || isLast) {
+                await this.recordTreeDelta(jobId);
                 this.jobs.complete(jobId, outcome.run, status === "completed" ? undefined : (outcome.semanticFailure ?? reason), outcome.relay);
                 return "done";
             }
@@ -764,6 +897,7 @@ export class McpDispatchServer {
         const ran = attempts.filter((a) => attemptWasTried(a.status)).length;
         const allSkipped = attempts.length > 0 && ran === 0;
         const skipReasons = [...new Set(attempts.filter((a) => !attemptWasTried(a.status)).map((a) => a.reason ?? "skipped"))];
+        await this.recordTreeDelta(jobId);
         this.jobs.fail(jobId, allSkipped
             ? `every lane in the selection order was skipped before it ran: ${skipReasons.join("; ")}`
             : ran === 0
@@ -771,6 +905,29 @@ export class McpDispatchServer {
                 : `no lane answered, and the ladder no longer holds the remaining lanes in the selection order (${ran} tried)`);
         return "done";
     }
+    async startTreeDelta(jobId, opts) {
+        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 });
+    }
+    async recordTreeDelta(jobId) {
+        const tree = this.trees.get(jobId);
+        if (tree === undefined)
+            return;
+        this.trees.delete(jobId);
+        const after = await this.readTree(tree.cwd);
+        this.jobs.noteTreeDelta(jobId, renderTreeDelta(tree.cwd, tree.before, after, tree.scope));
+    }
+    async readTree(cwd) {
+        try {
+            return await (this.deps.treeSnapshot ?? defaultTreeSnapshot)(cwd);
+        }
+        catch {
+            return null;
+        }
+    }
     budgetWithheld(view, laneIds, i) {
         return !laneIds.slice(i + 1).some((id) => {
             const later = view.ladder.find((l) => l.id === id);
@@ -793,6 +950,50 @@ export class McpDispatchServer {
         this.jobs.noteSkippedLane(jobId);
         return true;
     }
+    skipBeforeStart(jobId, lane, opts) {
+        return this.skipIfAtConcurrencyCap(jobId, lane) || this.skipIfBelowTier(jobId, lane, opts);
+    }
+    skipIfBelowTier(jobId, lane, opts) {
+        if (lane.capability === undefined || opts.tier === undefined)
+            return false;
+        if (this.jobs.get(jobId)?.forcedLane === true)
+            return false;
+        const packet = EFFORT_LEVELS.indexOf(opts.tier);
+        const rung = EFFORT_LEVELS.indexOf(lane.capability);
+        if (packet < 0 || rung < 0 || rung >= packet)
+            return false;
+        this.jobs.recordAttempt(jobId, {
+            laneId: lane.id,
+            spec: lane.spec,
+            status: SKIPPED_LANE_STATUS,
+            elapsedMs: 0,
+            reason: `lane "${lane.id}" declares capability ${lane.capability}, below this ${opts.tier} dispatch`,
+        });
+        this.jobs.noteSkippedLane(jobId);
+        return true;
+    }
+    async laneStillWorking(jobId) {
+        const now = this.now();
+        const lastOutput = this.jobs.get(jobId)?.activity?.lastOutputAt;
+        if (typeof lastOutput === "number" && now - lastOutput <= LANE_ACTIVITY_WINDOW_MS) {
+            return `it wrote output ${Math.round((now - lastOutput) / 1000)}s ago`;
+        }
+        const tree = this.trees.get(jobId);
+        if (tree === undefined)
+            return null;
+        const reading = await this.readTree(tree.cwd);
+        if (reading === null)
+            return null;
+        const previous = tree.lastSeen ?? tree.before;
+        tree.lastSeen = reading;
+        if (!sameTree(previous, reading))
+            return "its working tree changed";
+        const newest = newestChangeMs(tree.cwd, reading);
+        if (newest !== null && now - newest <= LANE_ACTIVITY_WINDOW_MS) {
+            return `a file in its working tree changed ${Math.max(0, Math.round((now - newest) / 1000))}s ago`;
+        }
+        return null;
+    }
     bindReadOnlyOrSkip(jobId, lane, opts) {
         if (!opts.readOnly)
             return { skipped: false };
@@ -825,16 +1026,20 @@ export class McpDispatchServer {
         }));
         if (budgetMs === null)
             return guarded;
-        const raced = await Promise.race([
-            guarded.then((o) => ({ kind: "settled", outcome: o })),
-            new Promise((resolve) => {
-                const t = setTimeout(() => resolve({ kind: "budget" }), budgetMs);
-                if (typeof t.unref === "function")
-                    t.unref();
-            }),
-        ]);
-        if (raced.kind === "settled")
-            return raced.outcome;
+        const settled = guarded.then((o) => ({ kind: "settled", outcome: o }));
+        let waitMs = budgetMs;
+        for (;;) {
+            const raced = await Promise.race([settled, budgetTimer(waitMs)]);
+            if (raced.kind === "settled")
+                return raced.outcome;
+            if (this.jobs.get(jobId)?.status !== "running")
+                break;
+            const working = await this.laneStillWorking(jobId);
+            if (working === null)
+                break;
+            this.jobs.noteExtension(jobId, lane.id, `${lane.id} kept past its ${Math.round(budgetMs / 1000)}s budget because ${working}`);
+            waitMs = LANE_ACTIVITY_WINDOW_MS;
+        }
         started.kill();
         return { run: emptyRun(), abandoned: true };
     }
@@ -864,8 +1069,8 @@ export class McpDispatchServer {
         const cwdCheck = checkCwd(opts.cwd, this.deps.allowedRoots);
         if (!cwdCheck.ok)
             return { refusal: `dispatch refused: ${cwdCheck.reason}` };
-        const invoke = invokeOverride ?? lane.invoke;
-        if (!invoke) {
+        const declared = invokeOverride ?? lane.invoke;
+        if (!declared) {
             const why = lane.unreachable ??
                 (lane.spec !== undefined && this.isPassThroughLane(lane)
                     ? mcpPassThroughReason(lane.spec)
@@ -875,8 +1080,12 @@ export class McpDispatchServer {
                 kill: () => { },
             };
         }
-        const env = applyLaneEnv(process.env, invoke.env);
+        const agy = agyWorkingDirInvoke(declared, opts.cwd);
+        const invoke = agy?.invoke ?? declared;
+        const expansion = expandEnvReferences(applyLaneEnv(process.env, invoke.env), this.deps.platform);
+        const env = expansion.env;
         env[DEPTH_ENV] = String(opts.depth + 1);
+        this.jobs.noteLaunch(jobId, [...expansion.notes, ...(agy === null ? [] : [agy.note])]);
         const startedAt = this.now();
         this.jobs.beginAttemptActivity(jobId, startedAt);
         let run;
@@ -1029,15 +1238,33 @@ export class McpDispatchServer {
         const text = extractAnswerText(parsed, opts.schema !== undefined);
         return { run: { code: 0, stdout: text, stderr: "", timedOut: false }, relay };
     }
-    async awaitOrPoll(jobId, settled, waitMs, clamp) {
-        const raced = await Promise.race([
-            settled,
-            new Promise((resolve) => {
-                const t = setTimeout(() => resolve("pending"), waitMs);
-                if (typeof t.unref === "function")
-                    t.unref();
-            }),
-        ]);
+    async awaitOrPoll(jobId, settled, waitMs, opts = {}) {
+        const { clamp, progressToken, signal } = opts;
+        const timers = [];
+        const startedAt = this.now();
+        if (progressToken !== undefined) {
+            const tick = setInterval(() => this.sendProgress(jobId, progressToken, startedAt), PROGRESS_INTERVAL_MS);
+            if (typeof tick.unref === "function")
+                tick.unref();
+            timers.push(tick);
+        }
+        let raced;
+        try {
+            raced = await Promise.race([
+                settled,
+                new Promise((resolve) => {
+                    const t = setTimeout(() => resolve("pending"), waitMs);
+                    if (typeof t.unref === "function")
+                        t.unref();
+                    timers.push(t);
+                    signal?.addEventListener("abort", () => resolve("pending"), { once: true });
+                }),
+            ]);
+        }
+        finally {
+            for (const t of timers)
+                clearTimeout(t);
+        }
         const current = this.jobs.get(jobId);
         if (!current)
             return textResult(`unknown jobId: ${jobId}`, true);
@@ -1045,12 +1272,32 @@ export class McpDispatchServer {
             const waitedS = Math.round(waitMs / 1000);
             const announcement = clamp === undefined
                 ? ""
-                : `waited ${waitedS} s (waitMs ${clamp.requested} clamped to routing.mcp.maxWaitMs ${clamp.ceiling})\n`;
+                : `waited ${waitedS} s (waitMs ${clamp.requested} clamped to ${clamp.key} ${clamp.ceiling})\n`;
             return textResult(`${describeJob(current, this.now())}\n\n${announcement}Still running after ${waitedS}s. ` +
                 `Poll dispatch_status with jobId "${jobId}", then call dispatch_result.`);
         }
         return textResult(jobAnswer(current, this.now()), isFailureStatus(current.status));
     }
+    sendProgress(jobId, progressToken, startedAt) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== "running")
+            return;
+        const elapsed = Math.max(1, Math.round((this.now() - startedAt) / 1000));
+        try {
+            this.deps.write(encodeMessage({
+                jsonrpc: "2.0",
+                method: "notifications/progress",
+                params: { progressToken, progress: elapsed, message: `${jobId} running on ${job.laneId} for ${elapsed}s` },
+            }));
+        }
+        catch (e) {
+            logStderr(`progress write failed: ${e.message}`);
+        }
+    }
+}
+export function taskLabel(task) {
+    const line = task.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+    return line.length > 80 ? `${line.slice(0, 77)}...` : line;
 }
 function extractAnswerText(parsed, hasSchema) {
     const message = parsed;