@songsid/agend 2.3.5-alpha.3 → 2.3.5-alpha.5

package/dist/runtime-coordinator.js

@@ -8,9 +8,14 @@ import { atomicWriteFileSync } from "./atomic-write.js";
 import { validateNativeTask } from "./windows-cli-worker.js";
 import { inventoryProbed } from "./windows-cli.js";
 import { isNativeProviderId } from "./windows-cli-providers.js";
+import { assertCredentialProfileCli, assertCredentialProfileName, parseCredentialProfileReport } from "./runtime-credential-profiles.js";
+import { parseAccountIdentity } from "./claude-auth-status.js";
+import { RuntimeUpdateActivity } from "./runtime-update-activity.js";
+import { parseRuntimeUpdateControl, RUNTIME_MANAGED_UPDATE_CAPABILITY, validRuntimeUpdateId } from "./runtime-update-protocol.js";
 import { validatePaneMcpBody } from "./runtime-pane-mcp-protocol.js";
 import { validateRuntimePaneRequest, validateRuntimePaneSnapshot, validateRuntimePaneShutdown } from "./runtime-pane-protocol.js";
-import { RUNTIME_CLAIM_PATH, RUNTIME_CONNECT_PATH, RUNTIME_MAX_FRAME_BYTES, RUNTIME_PAIR_PATH, RUNTIME_ROTATE_PATH, runtimeFingerprintFromHash } from "./runtime-protocol.js";
+import { withNativePaneVerification } from "./runtime-pane-native.js";
+import { RUNTIME_CLAIM_PATH, RUNTIME_CONNECT_PATH, RUNTIME_MAX_FRAME_BYTES, RUNTIME_PAIR_PATH, RUNTIME_ROTATE_PATH, runtimeFingerprintFromHash, parseRuntimeInfo, runtimeInfoCompatible, RUNTIME_REINSTALL_CLOSE_REASON } from "./runtime-protocol.js";
 const PAIR_TTL = 10 * 60_000;
 const MAX_STORE_BYTES = 64 * 1024 * 1024;
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
@@ -18,6 +23,9 @@ const secret = () => randomBytes(32).toString("hex");
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 const equal = (value, digest) => /^[a-f0-9]{64}$/i.test(digest) && timingSafeEqual(Buffer.from(hash(value), "hex"), Buffer.from(digest, "hex"));
 const record = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** A deliberate validation failure whose static message is safe to show the runtime; every other error (I/O, internal) is not. */
+class RuntimeProtocolError extends Error {
+}
 const text = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max && !/[\0\r\n]/.test(v);
 const terminal = (task) => !!task.finishedAt && ["completed", "failed", "cancelled"].includes(task.status);
 const loopback = (address) => address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
@@ -34,10 +42,19 @@ function stable(value, depth = 0) {
         return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stable(value[key], depth + 1)}`).join(",")}}`;
     return JSON.stringify(value) ?? "null";
 }
+/** The CLI rows' `supports` flags AgEnD knows; any other key a Runtime adds is not kept. */
+const SUPPORT_KEYS = ["execution", "resume", "model", "mcp"];
+const MODEL_SOURCES = ["cli-cache", "official-catalog", "cli-list", "unavailable"];
+/**
+ * A Runtime's inventory, copied field by field from an allowlist: a field AgEnD does not know is not kept (so it can never be stored or served back
+ * by /ui/runtimes), every text field has a length limit, and the account identity and the credential profile report are accepted in their
+ * closed, masked form only. A refusal names the field and the reason, never the rejected value: an unmasked e-mail must not reach a log, a close
+ * reason or an error message from here.
+ */
 function inventory(value) {
     if (!record(value) || typeof value.home !== "string" || value.home.length > 1024 || !Array.isArray(value.clis) || value.clis.length > 16)
-        throw Error("Invalid runtime inventory");
-    const seen = new Set();
+        throw new RuntimeProtocolError("Invalid runtime inventory");
+    const seen = new Set(), clis = [];
     for (const row of value.clis) {
         if (!record(row) || !isNativeProviderId(row.id) || seen.has(row.id) || !record(row.supports)
             || typeof row.runnable !== "boolean" || typeof row.readOnlySupport !== "boolean"
@@ -45,18 +62,60 @@ function inventory(value) {
             || !(row.path === null || text(row.path, 2048)) || !(row.version === null || text(row.version, 256))
             || typeof row.permissionNote !== "string" || row.permissionNote.length > 2048
             || !Array.isArray(row.models) || row.models.length > 256)
-            throw Error("Invalid runtime CLI inventory");
-        for (const model of row.models)
+            throw new RuntimeProtocolError("Invalid runtime CLI inventory");
+        const models = row.models.map(model => {
             if (!record(model) || !text(model.id, 256) || model.name !== undefined && !text(model.name, 256)
                 || model.description !== undefined && (typeof model.description !== "string" || model.description.length > 2048))
-                throw Error("Invalid runtime model inventory");
+                throw new RuntimeProtocolError("Invalid runtime model inventory");
+            return { id: model.id, ...(model.name !== undefined ? { name: model.name } : {}), ...(model.description !== undefined ? { description: model.description } : {}) };
+        });
         if (Object.values(row.supports).some(v => typeof v !== "boolean"))
-            throw Error("Invalid runtime capabilities");
+            throw new RuntimeProtocolError("Invalid runtime capabilities");
+        if (row.reason !== undefined && (typeof row.reason !== "string" || row.reason.length > 1024))
+            throw new RuntimeProtocolError("Invalid runtime CLI inventory");
+        const supports = Object.fromEntries(SUPPORT_KEYS.filter(key => Object.hasOwn(row.supports, key)).map(key => [key, row.supports[key]]));
+        const entry = { id: row.id, path: row.path, version: row.version, authenticated: row.authenticated, runnable: row.runnable, supports: supports,
+            readOnlySupport: row.readOnlySupport, permissionNote: row.permissionNote, models,
+            ...(row.reason !== undefined ? { reason: row.reason } : {}),
+            ...(MODEL_SOURCES.includes(row.modelsSource) ? { modelsSource: row.modelsSource } : {}) };
         seen.add(row.id);
+        clis.push(entry);
     }
     if (Buffer.byteLength(JSON.stringify(value)) > RUNTIME_MAX_FRAME_BYTES / 2)
-        throw Error("Runtime inventory is too large");
-    return structuredClone(value);
+        throw new RuntimeProtocolError("Runtime inventory is too large");
+    if (value.probedAt !== undefined && value.probedAt !== null && (typeof value.probedAt !== "number" || !Number.isFinite(value.probedAt)))
+        throw new RuntimeProtocolError("Invalid runtime inventory");
+    const probe = { clis, home: value.home, ...(value.probedAt !== undefined ? { probedAt: value.probedAt } : {}),
+        ...(typeof value.hostname === "string" && value.hostname.trim() && value.hostname.length <= 255 && !/[\x00-\x1f\x7f]/.test(value.hostname) ? { hostname: value.hostname.trim() } : {}) };
+    const field = (error) => /^Invalid (?:credential profile report|account identity): [A-Za-z ,.]{1,48}$/.test(String(error?.message)) ? String(error.message).replace(/^Invalid (?:credential profile report|account identity): /, "") : "invalid";
+    if (value.credentialProfiles !== undefined) {
+        try {
+            probe.credentialProfiles = parseCredentialProfileReport(value.credentialProfiles);
+        }
+        catch (error) {
+            throw new RuntimeProtocolError(`Invalid runtime credential profiles (${field(error)})`);
+        }
+    }
+    const identities = new Map(value.clis.map(row => [row.id, row.identity]));
+    for (const row of probe.clis) {
+        const identity = identities.get(row.id);
+        if (identity === undefined)
+            continue;
+        if (row.id !== "claude-code" || row.authenticated !== true)
+            throw new RuntimeProtocolError("Invalid runtime CLI identity (only a signed-in Claude Code has one)");
+        try {
+            row.identity = parseAccountIdentity(identity);
+        }
+        catch (error) {
+            throw new RuntimeProtocolError(`Invalid runtime CLI identity (${field(error)})`);
+        }
+    }
+    return probe;
+}
+function machineView(machine) {
+    return { ...structuredClone(machine), ...(machine.inventory ? { inventory: withNativePaneVerification(machine.inventory) } : {}), runtimeCompatibility: machine.runtimeInfo
+            ? runtimeInfoCompatible(machine.runtimeInfo) ? "compatible" : "incompatible"
+            : machine.bootId ? "legacy" : "unknown" };
 }
 /**
  * M-2239 P2-1 (#2936 review): the journal is compacted, never just capped. A settled command (failed, or accepted with a
@@ -82,6 +141,8 @@ export class RuntimeCoordinator {
     pending = new Map();
     paneToolPending = new Set();
     panePending = new Map();
+    /** Physical handler ownership survives socket replacement and transport deadlines. */
+    machineActivity = new Map();
     listeners = new Set();
     limits = new Map();
     heartbeat;
@@ -124,6 +185,9 @@ export class RuntimeCoordinator {
         for (const command of this.state.commands)
             if (command.state === "pending")
                 command.state = interrupted(command);
+        for (const row of this.state.machines)
+            if (row.machine.runtimeInfo !== undefined)
+                row.machine.runtimeInfo = parseRuntimeInfo(row.machine.runtimeInfo);
         this.save();
         this.heartbeat = setInterval(() => {
             for (const connection of this.connections.values()) {
@@ -169,8 +233,8 @@ export class RuntimeCoordinator {
     }
     entry(id) { const row = this.state.machines.find(v => v.machine.id === id); if (!row)
         throw Error("Runtime machine not found"); return row; }
-    listMachines() { return this.state.machines.map(row => structuredClone(row.machine)); }
-    machine(id) { const row = this.state.machines.find(v => v.machine.id === id); return row ? structuredClone(row.machine) : null; }
+    listMachines() { return this.state.machines.map(row => machineView(row.machine)); }
+    machine(id) { const row = this.state.machines.find(v => v.machine.id === id); return row ? machineView(row.machine) : null; }
     subscribe(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
     createPairing() {
         this.state.pairings = this.state.pairings.filter(row => row.expiresAt > this.now());
@@ -246,6 +310,7 @@ export class RuntimeCoordinator {
         if (connection) {
             this.connections.delete(id);
             this.rejectPending(connection, "Runtime machine was revoked");
+            this.options.warn?.({ machineId: id, code: 1008, reason: "Machine revoked" }, "Runtime connection closed because the machine was revoked");
             connection.ws.close(1008, "Machine revoked");
         }
         this.emit({ type: "machine", machineId: id });
@@ -394,20 +459,31 @@ export class RuntimeCoordinator {
         const old = this.connections.get(row.machine.id);
         if (old) {
             this.rejectPending(old, "Runtime connection was replaced; execution must be reconciled");
+            this.options.warn?.({ machineId: row.machine.id, code: 1008, reason: "Connection replaced" }, "Runtime connection closed because the same machine credential connected again");
             old.ws.close(1008, "Connection replaced");
         }
         row.machine.generation++;
         row.machine.status = "offline";
         this.save();
-        const connection = { ws, machineId: row.machine.id, generation: row.machine.generation, ready: false, alive: true, helloTimer: setTimeout(() => ws.close(1008, "Runtime hello required"), 10_000) };
+        const activity = this.machineActivity.get(row.machine.id) ?? new RuntimeUpdateActivity();
+        this.machineActivity.set(row.machine.id, activity);
+        const connection = { ws, machineId: row.machine.id, generation: row.machine.generation, ready: false, alive: true, activity, helloTimer: setTimeout(() => ws.close(1008, "Runtime hello required"), 10_000) };
         connection.helloTimer.unref();
         this.connections.set(row.machine.id, connection);
         ws.on("pong", () => { connection.alive = true; if (this.current(connection))
             row.machine.lastSeenAt = this.now(); });
-        ws.on("message", (data, binary) => { if (binary) {
-            ws.close(1008, "Runtime requires JSON text frames");
-            return;
-        } void this.message(connection, data).catch(() => ws.close(1008, "Invalid runtime message")); });
+        ws.on("message", (data, binary) => {
+            if (binary) {
+                ws.close(1008, "Runtime requires JSON text frames");
+                return;
+            }
+            void this.message(connection, data).catch(error => {
+                // The cause (a static validation message) goes to the log and, trimmed, to the runtime so its terminal can show it.
+                const reason = error instanceof RuntimeProtocolError ? `Invalid runtime message: ${error.message}`.replace(/[^ -~]/g, "?").slice(0, 120) : "Invalid runtime message";
+                this.options.warn?.({ machineId: connection.machineId, code: 1008, reason, detail: error instanceof Error ? error.message : String(error) }, "Runtime connection closed because of an invalid runtime message");
+                ws.close(1008, reason);
+            });
+        });
         ws.on("error", () => { });
         ws.on("close", () => {
             clearTimeout(connection.helloTimer);
@@ -434,6 +510,8 @@ export class RuntimeCoordinator {
         connection.ws.send(frame);
     }
     rejectPending(connection, reason) {
+        connection.update?.fence.release();
+        connection.update = undefined;
         for (const [id, pending] of this.panePending)
             if (pending.machineId === connection.machineId && pending.generation === connection.generation) {
                 this.panePending.delete(id);
@@ -458,7 +536,7 @@ export class RuntimeCoordinator {
     }
     validateTask(command, value) {
         if (command.operation !== "run" || !record(command.payload) || !record(command.payload.task) || !record(value))
-            throw Error("Unexpected runtime task");
+            throw new RuntimeProtocolError("Unexpected runtime task");
         const input = command.payload.task;
         if (value.id !== input.requestId || value.cli !== input.cli || value.cwd !== input.cwd || value.sandbox !== input.sandbox || (value.model ?? "") !== (input.model ?? "")
             || !["starting", "running", "cancelling", "completed", "failed", "cancelled"].includes(String(value.status))
@@ -469,38 +547,154 @@ export class RuntimeCoordinator {
             || value.threadId !== undefined && !text(value.threadId, 256)
             || value.threadId !== undefined && command.payload.resumeSessionId !== undefined && value.threadId !== command.payload.resumeSessionId
             || value.outcomeConfirmed !== undefined && typeof value.outcomeConfirmed !== "boolean")
-            throw Error("Invalid runtime task snapshot");
+            throw new RuntimeProtocolError("Invalid runtime task snapshot");
         return { id: value.id, cli: value.cli, cwd: value.cwd, sandbox: value.sandbox, ...(value.model ? { model: value.model } : {}),
             status: value.status, startedAt: value.startedAt, output: value.output,
             ...(value.finishedAt !== undefined ? { finishedAt: value.finishedAt } : {}), ...(value.error ? { error: value.error } : {}), ...(value.threadId ? { threadId: value.threadId } : {}), ...(value.outcomeConfirmed !== undefined ? { outcomeConfirmed: value.outcomeConfirmed } : {}) };
     }
+    admitting(connection) {
+        return connection.ready && !connection.update && connection.activity.accepting && this.current(connection)
+            && this.entry(connection.machineId).machine.status === "online" && connection.ws.readyState === WebSocket.OPEN;
+    }
+    updateIdle(connection) {
+        const machine = connection.machineId;
+        return connection.activity.pending === 0 && !this.hasActiveTask(machine) && connection.ws.bufferedAmount === 0
+            && ![...this.pending.values(), ...this.panePending.values()].some(pending => pending.machineId === machine)
+            && ![...this.paneToolPending].some(key => key.startsWith(`${machine}:`));
+    }
+    /** Trial metadata is staged until activation: no online event or probe can admit work early. */
+    promoteRuntime(connection) {
+        const row = this.entry(connection.machineId), hello = connection.hello;
+        row.machine.bootId = connection.bootId;
+        row.machine.status = "online";
+        row.machine.lastSeenAt = this.now();
+        if (hello.runtimeInfo)
+            row.machine.runtimeInfo = hello.runtimeInfo;
+        else
+            delete row.machine.runtimeInfo;
+        if (hello.paneProtocol === 1)
+            row.machine.paneProtocol = 1;
+        else
+            delete row.machine.paneProtocol;
+        if (hello.inventory !== undefined) {
+            row.machine.inventory = hello.inventory;
+            row.machine.inventoryUpdatedAt = this.now();
+        }
+        this.save();
+    }
+    updateControl(connection, value) {
+        if (!connection.ready || !connection.managedUpdate)
+            throw new RuntimeProtocolError("Runtime update was not negotiated");
+        const control = parseRuntimeUpdateControl(value, "client");
+        const reply = (phase) => this.send(connection, { v: 1, type: "update.control", id: control.id, bootId: connection.bootId, generation: connection.generation, phase });
+        if (control.bootId !== connection.bootId || control.generation !== connection.generation) {
+            reply("cancelled");
+            return;
+        }
+        const owned = connection.update;
+        if (owned?.phase === "trial") {
+            if (control.phase !== "activate" || owned.id !== control.id) {
+                reply("busy");
+                return;
+            }
+            if (!owned.fence.current() || !this.updateIdle(connection)) {
+                reply("busy");
+                return;
+            }
+            // The supervisor has persisted its activation intent. Lost acknowledgement is uncertain, never rollback permission.
+            owned.fence.release();
+            connection.update = undefined;
+            connection.activatedUpdateId = control.id;
+            this.promoteRuntime(connection);
+            reply("activated");
+            this.emit({ type: "machine", machineId: connection.machineId });
+            if (!inventoryProbed(this.entry(connection.machineId).machine.inventory))
+                void this.call(connection.machineId, "probe", { force: true }).catch(() => { });
+            return;
+        }
+        if (control.phase === "activate" && connection.activatedUpdateId === control.id) {
+            reply("activated");
+            return;
+        }
+        if (control.phase === "prepare") {
+            if (owned) {
+                reply(owned.id === control.id ? owned.phase === "committed" ? "commit" : "prepared" : "busy");
+                return;
+            }
+            const fence = connection.activity.tryFence(control.id, () => this.current(connection) && connection.ready && connection.ws.readyState === WebSocket.OPEN, () => this.updateIdle(connection));
+            if (!fence) {
+                reply("busy");
+                return;
+            }
+            connection.update = { id: control.id, phase: "prepared", fence };
+            reply("prepared");
+            return;
+        }
+        if (!owned || owned.id !== control.id) {
+            reply("cancelled");
+            return;
+        }
+        if (owned.phase === "committed") {
+            reply("commit");
+            return;
+        }
+        if (control.phase === "ready" && owned.fence.current() && this.updateIdle(connection)) {
+            owned.phase = "committed";
+            reply("commit");
+            return;
+        }
+        // A cancellation/busy reply is queued before admitting any later request on this ordered connection.
+        reply(control.phase === "ready" ? "busy" : "cancelled");
+        owned.fence.release();
+        connection.update = undefined;
+    }
     async message(connection, raw) {
         if (!this.current(connection))
             return;
         const value = JSON.parse(raw.toString());
         if (!record(value) || value.v !== 1 || !text(value.type, 32))
-            throw Error("Invalid runtime frame");
+            throw new RuntimeProtocolError("Invalid runtime frame");
         const row = this.entry(connection.machineId);
         connection.alive = true;
+        if (value.type === "update.control") {
+            this.updateControl(connection, value);
+            return;
+        }
         if (!connection.ready) {
             if (value.type !== "hello" || !text(value.bootId, 128))
-                throw Error("Runtime hello required");
-            connection.ready = true;
+                throw new RuntimeProtocolError("Runtime hello required");
+            const runtimeInfo = parseRuntimeInfo(value.runtimeInfo);
+            if (runtimeInfo && !runtimeInfoCompatible(runtimeInfo)) {
+                // Version skew fails clearly: no welcome, no work, and the Runtime is told to run the install command again. Its report is
+                // kept (it stays offline) so Settings can show which version needs reinstalling; the pairing itself is untouched.
+                row.machine.runtimeInfo = runtimeInfo;
+                row.machine.lastSeenAt = this.now();
+                this.save();
+                this.emit({ type: "machine", machineId: connection.machineId });
+                this.options.warn?.({ machineId: connection.machineId, code: 1008, reason: "Runtime incompatible", detail: `version ${runtimeInfo.version ?? "unknown"}, protocols ${runtimeInfo.protocolVersions.join(",")}, capabilities ${runtimeInfo.capabilities.join(",")}` }, "Runtime connection refused: its version is not compatible with this AgEnD");
+                connection.ws.close(1008, RUNTIME_REINSTALL_CLOSE_REASON);
+                return;
+            }
+            const managed = runtimeInfo?.capabilities.includes(RUNTIME_MANAGED_UPDATE_CAPABILITY) === true;
+            if (managed && !validRuntimeUpdateId(value.bootId) || value.updateTrialId !== undefined && (!managed || !validRuntimeUpdateId(value.updateTrialId)))
+                throw new RuntimeProtocolError("Invalid Runtime update handshake");
+            const reportedInventory = value.inventory === undefined ? undefined : inventory(value.inventory);
             connection.bootId = value.bootId;
-            clearTimeout(connection.helloTimer);
-            row.machine.bootId = value.bootId;
-            row.machine.status = "online";
-            row.machine.lastSeenAt = this.now();
-            if (value.paneProtocol === 1)
-                row.machine.paneProtocol = 1;
-            else
-                delete row.machine.paneProtocol;
-            if (value.inventory !== undefined) {
-                row.machine.inventory = inventory(value.inventory);
-                row.machine.inventoryUpdatedAt = this.now();
+            connection.managedUpdate = managed;
+            connection.hello = { runtimeInfo, ...(value.paneProtocol === 1 ? { paneProtocol: 1 } : {}), inventory: reportedInventory };
+            if (value.updateTrialId !== undefined) {
+                const fence = connection.activity.tryFence(value.updateTrialId, () => this.current(connection), () => this.updateIdle(connection));
+                if (!fence)
+                    throw new RuntimeProtocolError("Runtime update trial is busy");
+                connection.update = { id: value.updateTrialId, phase: "trial", fence };
             }
-            this.save();
-            this.send(connection, { v: 1, type: "welcome", machineId: connection.machineId, generation: connection.generation });
+            connection.ready = true;
+            clearTimeout(connection.helloTimer);
+            if (!connection.update)
+                this.promoteRuntime(connection);
+            this.send(connection, { v: 1, type: "welcome", machineId: connection.machineId, generation: connection.generation, ...(managed ? { updateProtocol: 1 } : {}) });
+            if (connection.update)
+                return; // A trial has authenticated, but cannot receive tasks or an automatic CLI probe.
             this.emit({ type: "machine", machineId: connection.machineId });
             // alpha.2 polish (dev-claude's no-chat e2e): a runner that brings no CLI inventory (just paired, nothing detected
             // yet) is asked for its own report now — its detection runs on that PC, never on this fleet's loop — so the first
@@ -513,21 +707,25 @@ export class RuntimeCoordinator {
             return;
         }
         row.machine.lastSeenAt = this.now();
+        if (connection.update?.phase === "trial")
+            throw new RuntimeProtocolError("Runtime update trial has not activated");
         if (value.type === "pane.tool.request") {
             if (row.machine.paneProtocol !== 1 || Object.keys(value).some(key => !["v", "type", "id", "body"].includes(key)) || !UUID.test(String(value.id)))
-                throw Error("Invalid pane MCP transport request");
+                throw new RuntimeProtocolError("Invalid pane MCP transport request");
             const body = validatePaneMcpBody(value.body), id = value.id;
             const key = `${connection.machineId}:${connection.generation}:${id}`;
             if (this.paneToolPending.size >= 128 || this.paneToolPending.has(key))
-                throw Error("Pane MCP transport backlog or duplicate request");
+                throw new RuntimeProtocolError("Pane MCP transport backlog or duplicate request");
             let active = true;
             const current = () => active && !this.closed && this.current(connection) && connection.ready && connection.ws.readyState === WebSocket.OPEN;
             this.paneToolPending.add(key);
             let timer;
             try {
-                if (!current() || !this.options.handlePaneMcp)
-                    throw Error("Pane MCP scope unavailable");
-                const result = await Promise.race([this.options.handlePaneMcp(connection.machineId, body, current), new Promise((_resolve, reject) => {
+                if (!current() || !this.options.handlePaneMcp || !connection.activity.accepting || connection.activity.pending >= 128)
+                    throw new RuntimeProtocolError("Pane MCP scope unavailable");
+                // The activity token belongs to the underlying handler, not the deadline race that may finish first.
+                const physical = connection.activity.run(() => this.options.handlePaneMcp(connection.machineId, body, current));
+                const result = await Promise.race([physical, new Promise((_resolve, reject) => {
                         timer = setTimeout(() => { active = false; reject(Error("Pane MCP deadline")); }, 80_000);
                         timer.unref();
                     })]);
@@ -547,19 +745,19 @@ export class RuntimeCoordinator {
         }
         if (value.type === "pane.output") {
             if (row.machine.paneProtocol !== 1)
-                throw Error("Pane protocol was not negotiated");
+                throw new RuntimeProtocolError("Pane protocol was not negotiated");
             const snapshot = validateRuntimePaneSnapshot(value.snapshot);
             this.emit({ type: "pane", machineId: connection.machineId, pane: snapshot });
             return;
         }
         if (value.type === "pane.response") {
             if (row.machine.paneProtocol !== 1 || !UUID.test(String(value.id)) || typeof value.ok !== "boolean")
-                throw Error("Invalid pane transport response");
+                throw new RuntimeProtocolError("Invalid pane transport response");
             const pending = this.panePending.get(value.id);
             if (!pending)
                 return; // A late reply proves nothing and never replays a command.
             if (pending.machineId !== connection.machineId || pending.generation !== connection.generation)
-                throw Error("Pane response belongs to another connection");
+                throw new RuntimeProtocolError("Pane response belongs to another connection");
             this.panePending.delete(value.id);
             clearTimeout(pending.timer);
             if (value.ok)
@@ -577,7 +775,7 @@ export class RuntimeCoordinator {
         }
         if (value.type === "task") {
             if (!record(value.task) || !Number.isSafeInteger(value.seq) || value.seq < 1)
-                throw Error("Invalid runtime task event");
+                throw new RuntimeProtocolError("Invalid runtime task event");
             const taskValue = value.task;
             const command = this.state.commands.find(command => command.id === taskValue.id && command.machineId === connection.machineId && command.operation === "run");
             if (!command) {
@@ -585,13 +783,13 @@ export class RuntimeCoordinator {
                 // is acknowledged by its tombstone and changes nothing. An unknown id, or another machine's, still closes.
                 if (this.tombstoned(connection.machineId, taskValue.id))
                     return;
-                throw Error("Runtime task does not belong to this machine");
+                throw new RuntimeProtocolError("Runtime task does not belong to this machine");
             }
             const task = this.validateTask(command, value.task);
             if (value.seq <= command.seq)
                 return;
             if (command.task && terminal(command.task) && !terminal(task))
-                throw Error("Runtime task cannot restart");
+                throw new RuntimeProtocolError("Runtime task cannot restart");
             command.seq = value.seq;
             command.task = task;
             command.state = "accepted";
@@ -601,12 +799,12 @@ export class RuntimeCoordinator {
         }
         if (value.type === "response") {
             if (!text(value.id, 128) || typeof value.ok !== "boolean")
-                throw Error("Invalid runtime response");
+                throw new RuntimeProtocolError("Invalid runtime response");
             const pending = this.pending.get(value.id), command = this.state.commands.find(command => command.id === value.id);
             if (!command || command.machineId !== connection.machineId) {
                 if (!command && this.tombstoned(connection.machineId, value.id))
                     return;
-                throw Error("Runtime response does not belong to this machine");
+                throw new RuntimeProtocolError("Runtime response does not belong to this machine");
             }
             if (!pending || pending.generation !== connection.generation)
                 return;
@@ -651,30 +849,30 @@ export class RuntimeCoordinator {
         }
         if (value.type === "tool.call") {
             if (!text(value.id, 128) || !text(value.runId, 128))
-                throw Error("Invalid runtime tool call");
+                throw new RuntimeProtocolError("Invalid runtime tool call");
             const command = this.state.commands.find(command => command.id === value.runId && command.machineId === connection.machineId && command.operation === "run");
             try {
-                if (!command || !record(command.payload) || !record(command.payload.mcp) || command.task && terminal(command.task) || !this.options.handleMcp)
-                    throw Error("Runtime tool call has no active turn");
+                if (!connection.activity.accepting || connection.activity.pending >= 128 || !command || !record(command.payload) || !record(command.payload.mcp) || command.task && terminal(command.task) || !this.options.handleMcp)
+                    throw new RuntimeProtocolError("Runtime tool call has no active turn");
                 const body = value.body;
                 if (!record(body) || Object.keys(body).some(key => !["op", "method", "params", "callId"].includes(key))
                     || body.op !== "native-mcp" || !record(body.params) || Buffer.byteLength(JSON.stringify(body)) > 64 * 1024)
-                    throw Error("Invalid runtime MCP request");
+                    throw new RuntimeProtocolError("Invalid runtime MCP request");
                 if (body.method === "tools/list") {
                     if (Object.keys(body.params).length || body.callId !== undefined)
-                        throw Error("Invalid runtime MCP listing");
+                        throw new RuntimeProtocolError("Invalid runtime MCP listing");
                 }
                 else if (body.method === "tools/call") {
                     if (!text(body.callId, 128) || !/^[A-Za-z0-9._:-]+$/.test(body.callId)
                         || Object.keys(body.params).some(key => !["name", "arguments"].includes(key)) || typeof body.params.name !== "string"
                         || !Array.isArray(command.payload.mcp.tools) || !command.payload.mcp.tools.includes(body.params.name)
                         || body.params.arguments !== undefined && !record(body.params.arguments))
-                        throw Error("Runtime MCP tool is outside this turn");
+                        throw new RuntimeProtocolError("Runtime MCP tool is outside this turn");
                     stable(body.params);
                 }
                 else
-                    throw Error("Invalid runtime MCP operation");
-                const result = await this.options.handleMcp(connection.machineId, value.runId, body);
+                    throw new RuntimeProtocolError("Invalid runtime MCP operation");
+                const result = await connection.activity.run(() => this.options.handleMcp(connection.machineId, value.runId, body));
                 if (!this.current(connection))
                     return;
                 this.send(connection, { v: 1, type: "tool.result", id: value.id, ok: true, result });
@@ -685,7 +883,7 @@ export class RuntimeCoordinator {
             }
             return;
         }
-        throw Error("Unknown runtime message");
+        throw new RuntimeProtocolError("Unknown runtime message");
     }
     tombstoned(machineId, id) {
         return typeof id === "string" && this.state.tombstones.some(row => row.id === id && row.machineId === machineId);
@@ -720,10 +918,31 @@ export class RuntimeCoordinator {
     }
     task(id) { const task = this.state.commands.find(command => command.id === id && command.operation === "run")?.task; return task ? structuredClone(task) : null; }
     tasks() { return this.state.commands.flatMap(command => command.operation === "run" && command.task ? [{ machineId: command.machineId, task: structuredClone(command.task) }] : []); }
+    /** Include journaled sends whose acknowledgement is still missing, so reopening diagnostics cannot hide an uncertain run. */
+    diagnosticTasks(machineId) {
+        return this.state.commands.flatMap(command => {
+            if (command.operation !== "run" || command.machineId !== machineId)
+                return [];
+            if (command.task)
+                return [structuredClone(command.task)];
+            let input;
+            try {
+                input = validateNativeTask(command.payload.task);
+            }
+            catch {
+                return [];
+            }
+            const uncertain = command.state === "uncertain", rejected = command.state === "failed";
+            return [{ id: command.id, cli: input.cli, cwd: input.cwd, sandbox: input.sandbox, ...(input.model ? { model: input.model } : {}),
+                    startedAt: command.createdAt, status: uncertain || rejected ? "failed" : "starting", output: "",
+                    ...(rejected ? { outcomeConfirmed: true, error: command.error || "Runtime request failed" } : {}),
+                    ...(uncertain ? { outcomeConfirmed: false, error: "Remote execution outcome is unconfirmed. Reconnect this runtime to reconcile before sending another task." } : {}) }];
+        }).sort((a, b) => b.startedAt - a.startedAt).slice(0, 20);
+    }
     hasActiveTask(machineId) { return this.state.commands.some(command => command.machineId === machineId && command.operation === "run" && command.state !== "failed" && (!command.task || !terminal(command.task) || command.task.outcomeConfirmed === false)); }
     paneTransportEpoch(machineId) {
         const connection = this.connections.get(machineId);
-        return connection?.ready && connection.ws.readyState === WebSocket.OPEN && this.current(connection) ? `${this.paneEpoch}:${machineId}:${connection.generation}` : null;
+        return connection && this.admitting(connection) ? `${this.paneEpoch}:${machineId}:${connection.generation}` : null;
     }
     /** Pane input replay/sequence authority lives in its pane ledger; reads never fill the exec-task journal. */
     async callPane(machineId, raw, maxAgents = 4) {
@@ -731,8 +950,8 @@ export class RuntimeCoordinator {
         if (!Number.isInteger(maxAgents) || maxAgents < 1 || maxAgents > 16)
             throw Error("Invalid machine pane limit");
         const machine = this.entry(machineId).machine, connection = this.connections.get(machineId);
-        if (this.closed || machine.status !== "online" || machine.paneProtocol !== 1 || !connection?.ready || !this.current(connection))
-            throw Error("Pane runtime is offline or unsupported");
+        if (this.closed || machine.status !== "online" || machine.paneProtocol !== 1 || !connection || !this.admitting(connection))
+            throw Error("Pane runtime is offline, updating or unsupported");
         if (this.panePending.size >= 64)
             throw Error("Pane transport capacity reached");
         const id = randomUUID();
@@ -769,13 +988,17 @@ export class RuntimeCoordinator {
             throw Error("Unsupported runtime operation");
         const machine = this.entry(machineId).machine;
         const connection = this.connections.get(machineId);
-        if (machine.status !== "online" || !connection?.ready || !this.current(connection))
-            throw Error("Runtime machine is offline");
+        if (machine.status !== "online" || !connection || !this.admitting(connection))
+            throw Error("Runtime machine is offline or updating");
         let id = randomUUID(), normalized = payload;
         if (operation === "run") {
-            if (!record(payload) || Object.keys(payload).some(k => !["task", "resumeSessionId", "context", "mcp"].includes(k)))
+            if (!record(payload) || Object.keys(payload).some(k => !["task", "resumeSessionId", "context", "mcp", "credentialProfile"].includes(k)))
                 throw Error("Invalid runtime run payload");
             const task = validateNativeTask(payload.task);
+            if (payload.credentialProfile !== undefined) {
+                assertCredentialProfileName(payload.credentialProfile);
+                assertCredentialProfileCli(task.cli);
+            }
             if (payload.resumeSessionId !== undefined && !text(payload.resumeSessionId, 256) || payload.context !== undefined && (typeof payload.context !== "string" || payload.context.length > 2000 || payload.context.includes("\0")))
                 throw Error("Invalid runtime turn context");
             if (payload.mcp !== undefined && (!record(payload.mcp) || Object.keys(payload.mcp).some(k => k !== "tools") || !Array.isArray(payload.mcp.tools) || !payload.mcp.tools.length || payload.mcp.tools.length > 128 || payload.mcp.tools.some(v => typeof v !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(v))))
@@ -847,6 +1070,8 @@ export class RuntimeCoordinator {
             return;
         this.closed = true;
         clearInterval(this.heartbeat);
+        for (const activity of this.machineActivity.values())
+            activity.close();
         for (const connection of this.connections.values()) {
             clearTimeout(connection.helloTimer);
             this.rejectPending(connection, "Runtime coordinator stopped; reconcile before retrying");