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

package/dist/runtime-client.js

@@ -1,26 +1,47 @@
 /** Standalone, outbound-only native runtime. Imports no Fleet, database, bot or Linux native dependency. */
 import WebSocket from "ws";
-import { readPaneSystemBootId } from "./runtime-pane-boot.js";
+import { readPaneSystemBootId, reusedRuntimeLockPid } from "./runtime-pane-boot.js";
 import { createServer } from "node:http";
 import { hostname } from "node:os";
 import { randomBytes, randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { WindowsCliBridge, nativeWindowsTransport, WINDOWS_CLI_INVENTORY_FILE } from "./windows-cli.js";
-import { validateNativeTask, validWindowsAgentId } from "./windows-cli-worker.js";
+import { probeCredentialProfileStatus, validateNativeTask, validWindowsAgentId } from "./windows-cli-worker.js";
 import { validNativeSessionId } from "./windows-cli-providers.js";
+import { RUNTIME_CREDENTIAL_CAPABILITY, credentialLoginRequired, credentialProfileReport, isCredentialProfileCli, listCredentialProfileNames, rememberCredentialStatus, requireCredentialProfile, credentialCacheStamp, assertCredentialProfileName, assertCredentialProfileCli } from "./runtime-credential-profiles.js";
 import { runtimeJobDigest, validateRuntimeServer } from "./runtime-client-store.js";
-import { RUNTIME_ROTATE_PATH, runtimeClaimFingerprint } from "./runtime-protocol.js";
+import { RUNTIME_ROTATE_PATH, RUNTIME_REINSTALL_CLOSE_PREFIX, runtimeClaimFingerprint } from "./runtime-protocol.js";
+import { readRuntimeInfo } from "./runtime-build-info.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, validateRuntimePaneShutdown } from "./runtime-pane-protocol.js";
 export { RUNTIME_PANE_MODULES } from "./runtime-pane-assets.js";
+const REPAIR = "run .\\agend-runtime.cmd disconnect in this folder (add the same --profile if you used one), then double-click connect-agend.bat and enter a new pairing code.";
+/** Plain-language cause and next step for a stop AgEnD caused. AgEnD answers an unknown and a revoked credential with the same bare 401, so "refused" covers both. */
+export function describeRuntimeStop(reason) {
+    switch (reason.kind) {
+        case "refused": return `${reason.detail === "HTTP 403" ? "The connection was refused with HTTP 403. If AgEnD's address goes through a proxy, check the proxy's settings too. " : ""}AgEnD did not accept this computer's saved connection, so the Runtime stopped. Open AgEnD Settings -> Runtime: if this computer is missing or revoked, or AgEnD's data was reset, it must be paired again; ${REPAIR} If the pairing was made against a different AgEnD address than this folder's, use the download that matches it.`;
+        case "reinstall": return "AgEnD refused this Runtime because its version is not compatible with this AgEnD (it was installed from a different AgEnD release). Your pairing is kept. Re-run the install command shown in AgEnD Settings -> Runtime -> Connect a computer (Windows PowerShell tab) on this computer; it installs the matching Runtime next to this one and never deletes the version that is running. Then start it again with agend-runtime run (add the same --profile if you used one). If you installed from the ZIP, download the ZIP from the same page and double-click connect-agend.bat.";
+        case "revoked": return `This computer was revoked in AgEnD Settings -> Runtime, so the Runtime stopped. To connect it again, ${REPAIR}`;
+        case "replaced": return "This computer connected to AgEnD again from somewhere else, so AgEnD closed this connection. A pairing allows one live connection. Close the other Runtime window (or the other computer that uses a copy of this profile), then double-click connect-agend.bat again. Each computer needs its own pairing code.";
+        case "incompatible": return "This Runtime could not understand a message from AgEnD, so it stopped. This usually means the Runtime and AgEnD are different versions, or the address points at something that is not this AgEnD. Download the Windows Runtime again from AgEnD Settings -> Runtime, extract it, and double-click connect-agend.bat.";
+        case "rejected": return `AgEnD rejected a message from this Runtime${reason.detail ? ` (${reason.detail})` : ""}. Usual causes: leftover data from pairing this profile with a different AgEnD server, or a Runtime/AgEnD version mismatch. If this profile was used with another AgEnD server, ${REPAIR} If pairing reports an unfinished job from another pairing, follow that message: check that no CLI it started is still running, delete jobs.json in the profile folder, then pair again. Otherwise download the Windows Runtime again from AgEnD Settings -> Runtime, extract it, and double-click connect-agend.bat.`;
+    }
+}
 const MAX_FRAME = 256 * 1024;
 const MAX_TOOL = 64 * 1024;
 function object(value) { return !!value && typeof value === "object" && !Array.isArray(value); }
 function message(error) { return error instanceof Error ? error.message.slice(0, 1000) : "Runtime operation failed"; }
 function checkedRun(value) {
-    if (!object(value) || Object.keys(value).some(key => !["task", "resumeSessionId", "context", "mcp"].includes(key)))
+    if (!object(value) || Object.keys(value).some(key => !["task", "resumeSessionId", "context", "mcp", "credentialProfile"].includes(key)))
         throw new Error("Invalid runtime run payload");
     const task = validateNativeTask(value.task);
+    // A name and nothing else: a path, a drive letter or a control byte is not a profile name and is refused here, not "cleaned".
+    if (value.credentialProfile !== undefined) {
+        assertCredentialProfileName(value.credentialProfile);
+        assertCredentialProfileCli(task.cli);
+    }
     if (value.resumeSessionId !== undefined && !validNativeSessionId(task.cli, value.resumeSessionId))
         throw new Error("Invalid native conversation ID");
     if (value.context !== undefined && (typeof value.context !== "string" || value.context.length > 2000 || value.context.includes("\0")))
@@ -30,7 +51,7 @@ function checkedRun(value) {
         || value.mcp.tools.some(tool => typeof tool !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(tool))))
         throw new Error("Invalid scoped MCP request");
     return { task, resumeSessionId: value.resumeSessionId, context: value.context,
-        mcp: value.mcp };
+        mcp: value.mcp, ...(value.credentialProfile !== undefined ? { credentialProfile: value.credentialProfile } : {}) };
 }
 function jsonBody(req) {
     return new Promise((accept, reject) => {
@@ -55,6 +76,7 @@ function jsonBody(req) {
 export class RuntimeClient {
     options;
     bootId = randomUUID();
+    runtimeInfo;
     bridge;
     socket = null;
     welcomed = false;
@@ -65,6 +87,8 @@ export class RuntimeClient {
     reconnectAttempt = 0;
     graceTimer = null;
     pollTimer = null;
+    credentialWatch = null;
+    credentialStamp = "";
     credentials = null;
     startupRotation = null;
     paneHost = null;
@@ -81,27 +105,52 @@ export class RuntimeClient {
     mcpPort = 0;
     inventory = null;
     stoppedListeners = new Set();
+    activity = new RuntimeUpdateActivity();
+    stopPromise;
+    generation = 0;
+    updateProtocol = false;
+    preparingUpdate = false;
+    trialFence;
+    updateWait;
+    /** Set only when AgEnD ended the connection and the person must act; a local stop (Ctrl+C) leaves it undefined. */
+    stopReason;
+    /** The socket this Runtime itself closed with 1008 because it could not read AgEnD's frame; that is not AgEnD refusing us. */
+    selfClosed = null;
     constructor(options) {
         this.options = options;
+        const info = readRuntimeInfo({ panes: process.platform === "win32" || !!options.createPaneHost || !!options.openPaneLink });
+        // Offered only when this client has a profile root to resolve names under; otherwise AgEnD must not ask for a profile.
+        if (options.managedUpdate?.trialId !== undefined && !validRuntimeUpdateId(options.managedUpdate.trialId))
+            throw Error("Invalid Runtime update trial");
+        this.runtimeInfo = { ...info, capabilities: [...info.capabilities.filter(name => options.credentialProfilesRoot || name !== RUNTIME_CREDENTIAL_CAPABILITY), ...(options.managedUpdate ? [RUNTIME_MANAGED_UPDATE_CAPABILITY] : [])] };
         this.bridge = options.bridge ?? new WindowsCliBridge(nativeWindowsTransport, join(options.store.directory, WINDOWS_CLI_INVENTORY_FILE));
     }
     report(text) { this.options.report?.(text); }
-    online() { return this.welcomed && this.socket?.readyState === WebSocket.OPEN; }
-    waitUntilStopped() { return this.stopped && this.closed ? Promise.resolve() : new Promise(done => this.stoppedListeners.add(done)); }
+    online() { return !this.trialFence && this.welcomed && this.socket?.readyState === WebSocket.OPEN; }
+    waitUntilStopped() { return this.stopPromise ?? (this.stopped && this.closed ? Promise.resolve() : new Promise(done => this.stoppedListeners.add(done))); }
     async start() {
         if (!this.stopped)
             return;
+        if (this.stopPromise) {
+            await this.stopPromise;
+            this.stopPromise = undefined;
+            this.activity = new RuntimeUpdateActivity();
+        }
         let credentials = this.options.store.credentials();
         if (!credentials)
             throw new Error("Pair this runtime before connecting");
         validateRuntimeServer(credentials.server);
         this.stopped = false;
         this.closed = false;
+        this.stopReason = undefined;
         try {
             const systemBootId = process.platform === "win32" ? await readPaneSystemBootId() : undefined;
             if (this.stopped)
                 throw Error("Runtime start was cancelled");
-            this.unlock = systemBootId ? this.options.store.lock(this.bootId, systemBootId) : this.options.store.lock(this.bootId);
+            const reused = process.platform === "win32" ? await reusedRuntimeLockPid(this.options.store.lockHolder()) : undefined;
+            if (this.stopped)
+                throw Error("Runtime start was cancelled");
+            this.unlock = this.options.store.lock(this.bootId, systemBootId, reused);
             if (credentials.pendingCredential) {
                 const rotating = this.startupRotation = rotateRuntimeCredentials({ store: this.options.store });
                 try {
@@ -114,15 +163,22 @@ export class RuntimeClient {
             }
             if (this.stopped)
                 throw Error("Runtime start was cancelled");
+            this.options.store.adoptMachine(credentials.machineId);
             this.options.store.recoverInterrupted();
             this.credentials = credentials;
+            if (this.options.managedUpdate?.trialId) {
+                this.trialFence = this.activity.tryFence(this.options.managedUpdate.trialId, () => !this.stopped, () => true);
+                if (!this.trialFence)
+                    throw Error("Runtime trial admission is unavailable");
+            }
             // Connect immediately, then publish the last administrator detection from the private profile.
             // A cached read starts no CLI. Only an explicit probe command with force:true performs detection.
             this.connect();
             // A foreground runtime must remain alive while an idle connection is down. Promises and unref'ed retry
             // timers do not keep Node running after the last socket closes; stop() owns and clears this liveness ref.
             this.pollTimer = setInterval(() => this.poll(), this.options.pollMs ?? 250);
-            void this.refreshInventory().catch(() => this.report("CLI discovery failed; refresh it from AgEnD after checking the local installation."));
+            if (!this.trialFence)
+                this.beginDiscovery();
         }
         catch (error) {
             this.stopped = true;
@@ -141,29 +197,33 @@ export class RuntimeClient {
             ?? new WebSocket(url.href, { headers: { Authorization: `Bearer ${this.credentials.credential}` }, followRedirects: false,
                 maxPayload: MAX_FRAME, handshakeTimeout: 15_000, perMessageDeflate: false });
         this.welcomed = false;
+        this.updateProtocol = false;
         this.paneEpoch = randomUUID();
         socket.on("open", () => {
             if (this.stopped || this.socket !== socket) {
                 socket.close();
                 return;
             }
-            this.send({ v: 1, type: "hello", bootId: this.bootId, name: this.credentials.name, platform: process.platform,
+            this.send({ v: 1, type: "hello", bootId: this.bootId, name: this.credentials.name, platform: process.platform, runtimeInfo: this.runtimeInfo,
+                ...(this.trialFence ? { updateTrialId: this.trialFence.id } : {}),
                 ...(process.platform === "win32" || this.options.createPaneHost || this.options.openPaneLink ? { paneProtocol: 1 } : {}),
                 ...(this.inventory ? { inventory: this.inventory } : {}) });
         });
         socket.on("message", (bytes, binary) => {
             const size = Array.isArray(bytes) ? bytes.reduce((sum, part) => sum + part.byteLength, 0) : bytes.byteLength;
             if (binary || size > MAX_FRAME || this.socket !== socket) {
+                this.selfClosed = socket;
                 socket.close(1008, "Invalid runtime frame");
                 return;
             }
-            void this.receive(bytes.toString()).catch(() => socket.close(1008, "Invalid runtime protocol"));
+            void this.receive(bytes.toString()).catch(() => { this.selfClosed = socket; socket.close(1008, "Invalid runtime protocol"); });
         });
         socket.on("error", () => { });
         socket.on("unexpected-response", (_req, response) => {
             response.resume();
             if (response.statusCode === 401 || response.statusCode === 403) {
                 this.report("Runtime credential was refused. Re-pair after the machine is authorized.");
+                this.stopReason = { kind: "refused", ...(response.statusCode === 403 ? { detail: "HTTP 403" } : {}) };
                 void this.stop();
             }
             else
@@ -175,14 +235,22 @@ export class RuntimeClient {
             this.socket = null;
             this.welcomed = false;
             this.paneEpoch = randomUUID();
+            if (this.updateWait) {
+                const pending = this.updateWait;
+                this.updateWait = undefined;
+                clearTimeout(pending.timer);
+                pending.reject(Error("Runtime update connection changed"));
+            }
             if (this.paneHost && "connectionChanged" in this.paneHost)
                 this.paneHost.connectionChanged();
             this.rejectTools();
             if (this.stopped)
                 return;
             if (code === 1008) {
-                this.report("Runtime connection was refused, revoked or replaced. Check pairing and protocol compatibility before reconnecting.");
-                void this.stop({ retirePanes: reason.toString() === "Machine revoked" });
+                const why = reason.toString().replace(/[^ -~]/g, "?").slice(0, 120);
+                this.report(this.selfClosed === socket ? "This Runtime could not read a message from AgEnD and closed the connection." : `AgEnD closed the connection (code 1008${why ? `: ${why}` : ""}).`);
+                this.stopReason = this.selfClosed === socket ? { kind: "incompatible" } : { kind: why === "Machine revoked" ? "revoked" : why === "Connection replaced" ? "replaced" : why.startsWith(RUNTIME_REINSTALL_CLOSE_PREFIX) ? "reinstall" : "rejected", ...(why ? { detail: why } : {}) };
+                void this.stop({ retirePanes: why === "Machine revoked" });
                 return;
             }
             this.report("Disconnected. Existing execution is not replayed; reconnecting…");
@@ -224,18 +292,42 @@ export class RuntimeClient {
             if (value.machineId !== this.credentials?.machineId || !Number.isSafeInteger(value.generation))
                 throw new Error("Runtime machine identity mismatch");
             this.welcomed = true;
+            this.generation = value.generation;
+            this.updateProtocol = value.updateProtocol === 1;
             this.reconnectAttempt = 0;
             if (this.graceTimer) {
                 clearTimeout(this.graceTimer);
                 this.graceTimer = null;
             }
             this.report("Connected to AgEnD.");
-            for (const job of this.options.store.list())
-                this.publish(job);
+            if (!this.trialFence)
+                for (const job of this.options.store.list())
+                    this.publish(job);
+            this.options.managedUpdate?.authenticated?.({ bootId: this.bootId, generation: this.generation, ...(this.updateProtocol ? { updateProtocol: 1 } : {}), runtimeInfo: this.runtimeInfo });
+            return;
+        }
+        if (value.type === "update.control") {
+            const control = parseRuntimeUpdateControl(value, "server"), pending = this.updateWait;
+            if (!pending || control.bootId !== this.bootId || control.generation !== this.generation || control.id !== pending.id || !pending.phases.includes(control.phase))
+                return;
+            if (control.phase === "activated") {
+                if (this.trialFence?.id !== control.id || !this.trialFence.current() || !this.locallyIdle())
+                    throw Error("Runtime trial is no longer idle");
+                this.trialFence.release();
+                this.trialFence = undefined;
+                // Release synchronously: the server's next ordered frame may already contain ordinary work.
+                for (const job of this.options.store.list())
+                    this.publish(job);
+                this.beginDiscovery();
+            }
+            this.updateWait = undefined;
+            clearTimeout(pending.timer);
+            pending.accept(control.phase);
             return;
         }
         if (value.type === "revoked") {
             this.report("This machine was revoked by AgEnD.");
+            this.stopReason = { kind: "revoked" };
             await this.stop({ retirePanes: true });
             return;
         }
@@ -281,9 +373,16 @@ export class RuntimeClient {
             const request = validateRuntimePaneRequest(value.request);
             this.machinePaneLimit = value.maxAgents;
             const epoch = this.paneEpoch;
+            let leave;
             try {
+                leave = this.activity.enter();
                 const host = await this.panes();
-                const result = await host.request(request, () => epoch === this.paneEpoch && this.online());
+                // A terminal for an agent with no profile of its own starts under this pairing's default profile, when there is one. The default is passed
+                // beside the launch, not inside it: the host decides with it only for a pane that is new, so a pane that is already running reattaches
+                // whatever the default has become since.
+                const fallback = request.action === "open" && request.launch.credentialProfile === undefined ? this.credentialProfileFor(request.launch.cli, undefined) : undefined;
+                const forHost = request.action === "open" && fallback !== undefined ? { ...request, defaultCredentialProfile: fallback } : request;
+                const result = await host.request(forHost, () => epoch === this.paneEpoch && this.online());
                 if (request.action === "shutdown") {
                     validateRuntimePaneShutdown(result, request.hostBootId);
                     // Explicit coordinator disable, not a disconnect: the next enabled request discovers a new host boot.
@@ -299,6 +398,9 @@ export class RuntimeClient {
             catch (error) {
                 this.send({ v: 1, type: "pane.response", id: value.id, ok: false, error: message(error) });
             }
+            finally {
+                leave?.();
+            }
             return;
         }
         if (value.type !== "request" || typeof value.id !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value.id)
@@ -332,6 +434,7 @@ export class RuntimeClient {
             else
                 this.paneOpening = import("./runtime-pane-link.js").then(({ RuntimePaneLink }) => (this.options.openPaneLink ?? RuntimePaneLink.open.bind(RuntimePaneLink))({
                     directory: this.options.store.directory, server: this.credentials.server, machineId: this.credentials.machineId,
+                    ...(this.options.credentialProfilesRoot ? { credentialRoot: this.options.credentialProfilesRoot } : {}),
                     online: () => !this.stopped && this.online(), maxAgents: () => this.machinePaneLimit, epoch: () => this.paneEpoch, output, mcp: (body, current) => this.paneMcp(body, current),
                 })).then(host => this.paneHost = host);
             const opening = this.paneOpening;
@@ -340,7 +443,8 @@ export class RuntimeClient {
         }
         return this.paneOpening;
     }
-    paneMcp(raw, current) {
+    paneMcp(raw, current) { return this.activity.run(() => this.forwardPaneMcp(raw, current)); }
+    forwardPaneMcp(raw, current) {
         const body = validatePaneMcpBody(raw), epoch = this.paneEpoch;
         if (!current() || !this.online() || this.pendingPaneTools.size >= 32)
             return Promise.reject(Error("Pane MCP transport is unavailable"));
@@ -389,15 +493,94 @@ export class RuntimeClient {
         if (task)
             this.update(task);
     } }
-    async refreshInventory(force = false) {
-        const inventory = await this.bridge.probe({ force });
+    /** Which profile a run uses: the one the agent named, else this pairing's default (Claude Code only), else none (the Runtime's own environment). */
+    credentialProfileFor(cli, named) {
+        if (named !== undefined)
+            return named;
+        return cli === "claude-code" && this.options.credentialProfilesRoot ? this.options.store.credentialDefault() : undefined;
+    }
+    stamp() { return credentialCacheStamp(this.options.credentialProfilesRoot, join(this.options.store.directory, "credential-default.json")); }
+    /**
+     * Re-report on its own after `agend-runtime login` / `profile default` (run in another window) changed the sign-in cache: the account shown
+     * in AgEnD follows a profile that was signed in to another account, without an administrator pressing "Detect again". Reads the cache only.
+     */
+    watchCredentialCache() {
+        if (!this.options.credentialProfilesRoot)
+            return;
+        this.credentialStamp = this.stamp();
+        this.credentialWatch = setInterval(() => {
+            if (!this.activity.accepting)
+                return;
+            const now = this.stamp();
+            if (now === this.credentialStamp)
+                return;
+            this.credentialStamp = now;
+            void this.refreshInventory(false).catch(() => { });
+        }, this.options.credentialWatchMs ?? 5000);
+        this.credentialWatch.unref?.();
+    }
+    statusOf(cli, directory) {
+        if (this.options.credentialStatus)
+            return this.options.credentialStatus(cli, directory);
+        if (this.options.credentialLogin)
+            return this.options.credentialLogin(cli, directory).then(loggedIn => ({ loggedIn }));
+        return probeCredentialProfileStatus(cli, directory);
+    }
+    remember(root, cli, name, answer) {
+        rememberCredentialStatus(root, cli, name, answer);
+        this.credentialStamp = this.stamp(); // our own write is not "another window"
+    }
+    /** The folder of a profile that exists AND is signed in on this computer; anything else refuses, never the default account. */
+    async credentialHome(cli, name) {
+        const root = this.options.credentialProfilesRoot;
+        if (!root)
+            throw new Error("This Runtime has no credential profile folder, so it cannot select an account. Update or restart the Runtime.");
+        if (!isCredentialProfileCli(cli))
+            throw new Error("Credential profiles on a Windows Runtime support Claude Code only");
+        const directory = requireCredentialProfile(root, cli, name);
+        const answer = await this.statusOf(cli, directory);
+        this.remember(root, cli, name, answer);
+        if (answer.loggedIn !== true)
+            throw credentialLoginRequired(cli, name, answer.loggedIn);
+        return directory;
+    }
+    /** Names and signed-in yes/no only. `force` (an explicit "Detect again") asks each profile's CLI; otherwise the last known answer is reported. */
+    async credentialReport(force) {
+        const root = this.options.credentialProfilesRoot;
+        if (!root)
+            return undefined;
+        if (force)
+            for (const name of listCredentialProfileNames(root, "claude-code")) {
+                try {
+                    this.remember(root, "claude-code", name, await this.statusOf("claude-code", requireCredentialProfile(root, "claude-code", name)));
+                }
+                catch {
+                    this.remember(root, "claude-code", name, { loggedIn: null });
+                }
+            }
+        let name;
+        try {
+            name = this.options.store.credentialDefault();
+        }
+        catch { /* reported as no default; a run refuses with the real error */ }
+        return credentialProfileReport(root, name);
+    }
+    beginDiscovery() {
+        void this.refreshInventory().catch(() => this.report("CLI discovery failed; refresh it from AgEnD after checking the local installation."));
+        this.watchCredentialCache();
+    }
+    refreshInventory(force = false) { return this.activity.run(() => this.readInventory(force)); }
+    async readInventory(force) {
+        const probed = await this.bridge.probe({ force }), credentialProfiles = await this.credentialReport(force);
+        const inventory = credentialProfiles ? { ...probed, credentialProfiles } : probed;
         this.inventory = inventory;
         if (this.online())
             this.send({ v: 1, type: "inventory", inventory });
         return inventory;
     }
     /** Testable command surface. Mutation identity is committed before calling the native bridge. */
-    async operation(operation, payload) {
+    operation(operation, payload) { return this.activity.run(() => this.ownedOperation(operation, payload)); }
+    async ownedOperation(operation, payload) {
         if (operation === "probe") {
             if (Object.keys(payload).some(key => key !== "force") || (payload.force !== undefined && typeof payload.force !== "boolean"))
                 throw new Error("Invalid discovery request");
@@ -467,13 +650,16 @@ export class RuntimeClient {
             return accepted.job.task;
         this.publish(accepted.job);
         try {
+            // Fail closed, and as a confirmed failed turn: an unknown, unsigned or unusable profile never falls back to another account.
+            const profile = this.credentialProfileFor(task.cli, run.credentialProfile);
+            const credentialHome = profile ? await this.credentialHome(task.cli, profile) : undefined;
             const mcp = payload.mcp ? await this.openMcp(task.requestId, payload.mcp.tools) : undefined;
             if (this.stopped || !this.online())
                 throw new Error("Runtime disconnected before native execution started");
             this.active.add(task.requestId);
             const initial = this.bridge.start(task, () => !this.stopped && this.online(), {
                 ...(payload.resumeSessionId ? { resumeSessionId: payload.resumeSessionId } : {}),
-                ...(payload.context ? { context: payload.context } : {}), ...(mcp ? { mcp } : {}),
+                ...(payload.context ? { context: payload.context } : {}), ...(mcp ? { mcp } : {}), ...(credentialHome ? { credentialHome } : {}),
                 onSettled: settled => this.update(settled),
             });
             this.update(initial);
@@ -487,6 +673,90 @@ export class RuntimeClient {
             return failed;
         }
     }
+    locallyIdle() {
+        return this.activity.pending === 0 && this.active.size === 0 && !this.options.store.blocked()
+            && this.bridge.idleForUpdate?.() === true && this.pendingTools.size === 0 && this.pendingPaneTools.size === 0
+            && !(this.paneOpening && !this.paneHost) && (this.socket?.bufferedAmount ?? 1) === 0;
+    }
+    updateRpc(phase, id, phases) {
+        if (!this.welcomed || !this.updateProtocol || this.socket?.readyState !== WebSocket.OPEN || this.updateWait)
+            return Promise.reject(Error("Runtime update negotiation is unavailable"));
+        return new Promise((accept, reject) => {
+            const pending = { id, phases, accept, reject, timer: setTimeout(() => {
+                    if (this.updateWait === pending)
+                        this.updateWait = undefined;
+                    reject(Error("Runtime update acknowledgement is unconfirmed"));
+                }, 10_000) };
+            pending.timer.unref();
+            this.updateWait = pending;
+            try {
+                this.send({ v: 1, type: "update.control", id, bootId: this.bootId, generation: this.generation, phase });
+            }
+            catch (error) {
+                this.updateWait = undefined;
+                clearTimeout(pending.timer);
+                reject(error);
+            }
+        });
+    }
+    /** Called only by the local supervisor. A timeout or disconnect never authorizes process replacement. */
+    async prepareUpdate(id) {
+        if (!validRuntimeUpdateId(id) || !this.options.managedUpdate || this.trialFence || this.preparingUpdate || !this.online() || !this.updateProtocol)
+            return false;
+        const socket = this.socket, generation = this.generation;
+        const current = () => !this.stopped && this.socket === socket && socket.readyState === WebSocket.OPEN && this.generation === generation;
+        const fence = this.activity.tryFence(id, current, () => this.locallyIdle());
+        if (!fence)
+            return false;
+        this.preparingUpdate = true;
+        let committed = false;
+        try {
+            if (await this.updateRpc("prepare", id, ["prepared", "busy", "cancelled"]) !== "prepared")
+                return false;
+            if (this.options.drainPaneHostForUpdate)
+                await this.options.drainPaneHostForUpdate(() => fence.current());
+            else {
+                const { RuntimePaneLink } = await import("./runtime-pane-link.js");
+                const existing = this.paneHost instanceof RuntimePaneLink && this.paneHost.connected() ? this.paneHost : undefined;
+                if (!existing && (this.options.createPaneHost || this.options.openPaneLink))
+                    throw Error("Injected pane host requires its own positive idle proof");
+                await RuntimePaneLink.drainExistingForUpdate({ directory: this.options.store.directory, server: this.credentials.server, machineId: this.credentials.machineId,
+                    online: () => current(), maxAgents: () => this.machinePaneLimit, epoch: () => this.paneEpoch, mcp: (body, owned) => this.paneMcp(body, owned) }, () => fence.current(), existing);
+            }
+            if (!fence.current() || !this.locallyIdle())
+                return false;
+            if (await this.updateRpc("ready", id, ["commit", "busy", "cancelled"]) !== "commit")
+                return false;
+            fence.commit();
+            committed = true;
+            await this.stop();
+            return true;
+        }
+        catch (error) {
+            if (committed)
+                throw error;
+            return false;
+        }
+        finally {
+            this.preparingUpdate = false;
+            if (!committed) {
+                try {
+                    if (!current() || await this.updateRpc("cancel", id, ["cancelled", "commit"]) !== "cancelled")
+                        socket.terminate();
+                }
+                catch {
+                    socket.terminate();
+                }
+                fence.release();
+            }
+        }
+    }
+    /** The parent persists activation intent before this call; an unconfirmed answer is never rollback permission. */
+    async activateTrial(id) {
+        if (this.trialFence?.id !== id || !this.locallyIdle())
+            return false;
+        return await this.updateRpc("activate", id, ["activated", "busy", "cancelled"]) === "activated";
+    }
     async openMcp(runId, tools) {
         if (!this.mcpOpening)
             this.mcpOpening = new Promise((accept, reject) => {
@@ -504,6 +774,22 @@ export class RuntimeClient {
                         reply(403, { error: "Runtime MCP capability is unavailable" });
                         return;
                     }
+                    let leave;
+                    try {
+                        leave = this.activity.enter();
+                    }
+                    catch {
+                        req.resume();
+                        reply(503, { error: "Runtime update is pending" });
+                        return;
+                    }
+                    const finished = new Promise(done => {
+                        const settle = () => { res.off("finish", settle); res.off("close", settle); done(); };
+                        res.once("finish", settle);
+                        res.once("close", settle);
+                        if (res.destroyed || res.writableFinished)
+                            settle();
+                    });
                     void jsonBody(req).then(async (body) => {
                         if (!object(body) || body.op !== "native-mcp" || !["tools/list", "tools/call"].includes(String(body.method))
                             || !object(body.params) || Object.keys(body).some(key => !["op", "method", "params", "callId"].includes(key)))
@@ -519,7 +805,7 @@ export class RuntimeClient {
                         if (Buffer.byteLength(JSON.stringify(result) ?? "") > MAX_TOOL)
                             throw new Error("Runtime MCP result is too large");
                         reply(200, result);
-                    }).catch(() => reply(403, { error: "Runtime MCP request was refused or its execution expired" }));
+                    }).catch(() => reply(403, { error: "Runtime MCP request was refused or its execution expired" })).finally(async () => { await finished; leave(); });
                 });
                 server.on("error", reject);
                 server.listen(0, "127.0.0.1", () => { const address = server.address(); if (!address || typeof address === "string") {
@@ -560,20 +846,36 @@ export class RuntimeClient {
         }
         this.pendingTools.clear();
     }
-    async stop(options = {}) {
+    stop(options = {}) {
+        if (this.stopPromise)
+            return this.stopPromise;
         if (this.stopped)
-            return;
+            return Promise.resolve();
         this.stopped = true;
         this.welcomed = false;
+        this.activity.close();
+        // Own cleanup before callbacks (bridge.close, pane cleanup) can re-enter stop().
+        return this.stopPromise = Promise.resolve().then(() => this.stopOwned(options));
+    }
+    async stopOwned(options) {
+        if (this.updateWait) {
+            const pending = this.updateWait;
+            this.updateWait = undefined;
+            clearTimeout(pending.timer);
+            pending.reject(Error("Runtime update stopped"));
+        }
         if (this.reconnectTimer)
             clearTimeout(this.reconnectTimer);
         if (this.graceTimer)
             clearTimeout(this.graceTimer);
         if (this.pollTimer)
             clearInterval(this.pollTimer);
+        if (this.credentialWatch)
+            clearInterval(this.credentialWatch);
         this.reconnectTimer = null;
         this.graceTimer = null;
         this.pollTimer = null;
+        this.credentialWatch = null;
         this.rejectTools();
         this.mcpTokens.clear();
         this.bridge.close();
@@ -609,7 +911,6 @@ export class RuntimeClient {
                 this.update({ ...old.task, status: "failed", finishedAt: Date.now(), outcomeConfirmed: false,
                     error: "Runtime stopped before native process shutdown was confirmed. Inspect processes before recovery." });
         }
-        this.closed = true;
         if (this.mcpServer) {
             const server = this.mcpServer;
             this.mcpServer = null;
@@ -618,6 +919,7 @@ export class RuntimeClient {
         }
         this.unlock?.();
         this.unlock = null;
+        this.closed = true;
         for (const done of this.stoppedListeners)
             done();
         this.stoppedListeners.clear();
@@ -672,6 +974,7 @@ export async function pairRuntime(input) {
     const server = validateRuntimeServer(input.server);
     if (!input.code.trim() || input.code.length > 256 || /[\x00-\x1f]/.test(input.code) || !input.name.trim() || input.name.length > 100)
         throw new Error("Enter a valid pairing code and machine name");
+    input.store.assertCanPair();
     const paired = await post(server, "/runtime/v1/pair", { code: input.code.trim(), name: input.name.trim(), platform: process.platform, hostname: hostname() }, input.signal);
     if (paired.status !== 201 || paired.data.status !== "pending" || typeof paired.data.machineId !== "string" || typeof paired.data.claimSecret !== "string")
         throw new Error(`Runtime pairing was refused (HTTP ${paired.status})`);
@@ -683,7 +986,14 @@ export async function pairRuntime(input) {
         if (claimed.status === 200 && claimed.data.status === "approved" && claimed.data.machineId === paired.data.machineId
             && typeof claimed.data.credential === "string" && /^[A-Za-z0-9._-]{16,256}$/.test(claimed.data.credential)) {
             const credentials = { server: server.origin, machineId: paired.data.machineId, credential: claimed.data.credential, name: input.name.trim() };
+            // Save first: the one-time credential cannot be issued again. A ledger that changed since the check above is reported after it is safe.
             input.store.saveCredentials(credentials);
+            try {
+                input.store.adoptMachine(credentials.machineId, true);
+            }
+            catch (error) {
+                throw new Error(`The computer was paired and its credential is saved. ${error instanceof Error ? error.message : "Its job ledger could not be updated."}`);
+            }
             input.report?.("Runtime paired. Its machine credential was saved in the private local profile.");
             return credentials;
         }
@@ -695,6 +1005,6 @@ export async function pairRuntime(input) {
             input.signal?.addEventListener("abort", abort, { once: true });
         });
     }
-    throw new Error("Runtime pairing was cancelled or expired");
+    throw new Error(input.signal?.aborted ? "Runtime pairing was cancelled" : "Runtime pairing expired before the computer was approved. Open AgEnD Settings -> Runtime, then double-click connect-agend.bat again and enter a new pairing code.");
 }
 //# sourceMappingURL=runtime-client.js.map