agent-relay 12.0.0 → 12.1.0

package/dist/cli/lib/broker-lifecycle.js

@@ -5,6 +5,7 @@ import { HarnessDriverClient } from '@agent-relay/harness-driver';
 import { startServeNode } from '@agent-relay/fleet';
 import { createLogger } from '@agent-relay/utils';
 import { redactCredentialValues } from '@agent-relay/cloud/redact';
+import { brokerIdentityPath, matchesBrokerIdentity, persistBrokerIdentity, readBrokerIdentities, removeBrokerIdentity, } from './broker-process-identity.js';
 import { track } from '../telemetry/index.js';
 import { buildBundledAgentRelayMcpCommand, isBundledBunEntrypointPath } from './agent-relay-mcp-command.js';
 import { errorClassName } from './telemetry-helpers.js';
@@ -747,67 +748,9 @@ function isProcessRunning(pid, deps) {
         deps.killProcess(pid, 0);
         return true;
     }
-    catch {
-        return false;
-    }
-}
-function parsePsAuxLine(line) {
-    const fields = line.trim().split(/\s+/);
-    if (fields.length < 11 || fields[0] === 'USER') {
-        return null;
-    }
-    const pid = Number.parseInt(fields[1], 10);
-    if (Number.isNaN(pid) || pid <= 0) {
-        return null;
-    }
-    return {
-        pid,
-        command: fields.slice(10).join(' '),
-    };
-}
-function commandExecutableBasename(command) {
-    const executable = command.trim().split(/\s+/)[0] ?? '';
-    return path.basename(executable.replace(/^["']|["']$/g, ''));
-}
-function isBrokerExecutableCommand(command) {
-    const basename = commandExecutableBasename(command);
-    return basename === 'agent-relay-broker' || basename.startsWith('agent-relay-broker-');
-}
-function isAttachedBrokerCliCommand(command) {
-    if (command.includes('agent-relay-mcp')) {
-        return false;
-    }
-    // The attached `up` process holds the broker. Skip the transient
-    // `up --background` launcher, which exits as soon as the child is ready.
-    if (!/(?:^|\s)up(?:\s|$)/.test(command) || /(?:^|\s)--background(?:\s|=|$)/.test(command)) {
-        return false;
-    }
-    return /(?:^|\s)(?:\S*agent-relay(?:\.js)?|\S*agent-relay-[^\s]+)(?:\s|$)/.test(command);
-}
-function isBrokerProcessCommand(command) {
-    return isBrokerExecutableCommand(command) || isAttachedBrokerCliCommand(command);
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function commandHasBrokerName(command, brokerName) {
-    const escapedName = escapeRegExp(brokerName);
-    return new RegExp(`(?:^|\\s)--name(?:\\s+|=)${escapedName}(?:\\s|$)`).test(command);
-}
-function commandHasProjectRoot(command, projectRoot) {
-    const escapedRoot = escapeRegExp(path.resolve(projectRoot));
-    return new RegExp(`(?:^|\\s|=|["'])${escapedRoot}(?:$|\\s|["']|${escapeRegExp(path.sep)})`).test(command);
-}
-async function processCwdMatchesProjectRoot(processInfo, projectRoot, deps) {
-    try {
-        const cwdDetails = await deps.execCommand(`lsof -nP -a -p ${processInfo.pid} -d cwd -Fn`);
-        return cwdDetails.stdout
-            .split('\n')
-            .filter((line) => line.startsWith('n'))
-            .some((line) => path.resolve(line.slice(1)) === projectRoot);
-    }
-    catch {
-        return false;
+    catch (error) {
+        // Permission denial proves no exit and must never authorize record deletion.
+        return error?.code === 'EPERM';
     }
 }
 async function terminateProcess(pid, deps, force) {
@@ -829,64 +772,64 @@ async function terminateProcess(pid, deps, force) {
     }
     return waitForProcessExit(pid, 500, deps);
 }
-async function killOrphanedBrokerProcesses(projectRoot, deps, options) {
-    let matchedCount = 0;
-    let killedCount = 0;
-    try {
-        const resolvedProjectRoot = path.resolve(projectRoot);
-        const brokerName = path.basename(resolvedProjectRoot) || 'project';
-        const candidates = [];
-        try {
-            const processList = await deps.execCommand('ps aux');
-            const relayProcesses = processList.stdout
-                .split('\n')
-                .map(parsePsAuxLine)
-                .filter((process) => process !== null)
-                .filter((process) => isBrokerProcessCommand(process.command));
-            const matchedPids = new Set();
-            for (const processInfo of relayProcesses) {
-                if (commandHasProjectRoot(processInfo.command, resolvedProjectRoot)) {
-                    candidates.push(processInfo);
-                    matchedPids.add(processInfo.pid);
-                }
-            }
-            for (const processInfo of relayProcesses) {
-                if (matchedPids.has(processInfo.pid)) {
-                    continue;
-                }
-                const cwdMatches = await processCwdMatchesProjectRoot(processInfo, resolvedProjectRoot, deps);
-                if (!cwdMatches)
-                    continue;
-                if (isBrokerExecutableCommand(processInfo.command) &&
-                    !commandHasBrokerName(processInfo.command, brokerName)) {
-                    continue;
-                }
-                candidates.push(processInfo);
-                matchedPids.add(processInfo.pid);
+async function killOrphanedBrokerProcesses(paths, deps, options) {
+    const identities = readBrokerIdentities(paths, deps);
+    if (!identities) {
+        deps.warn(`Broker identities could not be read in ${path.join(paths.projectRoot, '.agentworkforce', 'relay')}. State retained; inspect the records and verify process ownership before manual recovery.`);
+        return { matchedCount: 1, killedCount: 0 };
+    }
+    const brokerName = options?.brokerName?.trim() ||
+        deps.env.AGENT_RELAY_BROKER_NAME?.trim() ||
+        path.basename(paths.projectRoot) ||
+        'project';
+    const result = { matchedCount: 0, killedCount: 0 };
+    for (const identity of identities) {
+        if (options?.matchBrokerName && identity.brokerName !== brokerName)
+            continue;
+        if (!isProcessRunning(identity.pid, deps)) {
+            if (options?.matchBrokerName) {
+                result.matchedCount++;
+                deps.warn(`Recorded broker has already exited; its identity was retained because no matched exit was observed. Verify ownership before removing ${brokerIdentityPath(paths, deps, identity.brokerName)} and restarting.`);
             }
+            continue;
         }
-        catch {
-            // Expected if ps is unavailable; fall through to no matches.
-        }
-        for (const { pid } of candidates) {
-            if (pid === deps.pid) {
-                continue;
-            }
-            matchedCount += 1;
-            deps.warn(`Killing orphaned broker process (pid: ${pid})`);
-            const killed = await terminateProcess(pid, deps, options?.force === true);
-            if (killed) {
-                killedCount += 1;
-            }
-            else if (options?.force === true) {
-                deps.warn(`Broker orphan process may still be running (pid: ${pid})`);
-            }
+        result.matchedCount++;
+        if (await stopRecordedBroker(paths, identity, deps, options?.force === true))
+            result.killedCount++;
+    }
+    return result;
+}
+async function stopRecordedBroker(paths, identity, deps, force) {
+    // Check the persisted instance immediately before EVERY signal, including
+    // escalation after a wait. Never rediscover ownership from rendered argv.
+    if (!(await matchesBrokerIdentity(identity, paths, deps))) {
+        deps.warn(`Broker identity could not be verified (pid: ${identity.pid}). State retained; verify process ownership before stopping it manually. If the recorded broker has exited, remove its stale identity file: ${brokerIdentityPath(paths, deps, identity.brokerName)}`);
+        return false;
+    }
+    deps.warn(`Killing orphaned broker process (pid: ${identity.pid})`);
+    try {
+        deps.killProcess(identity.pid, 'SIGTERM');
+        // Native graceful shutdown may drain identity/presence work for 3.5s.
+        let exited = await waitForProcessExit(identity.pid, force ? 500 : 5000, deps);
+        if (!exited && force && (await matchesBrokerIdentity(identity, paths, deps))) {
+            deps.killProcess(identity.pid, 'SIGKILL');
+            exited = await waitForProcessExit(identity.pid, 500, deps);
+        }
+        if (exited) {
+            removeBrokerIdentity(paths, identity, deps);
+            return true;
         }
     }
-    catch {
-        // Best-effort orphan cleanup.
+    catch (error) {
+        if (error?.code === 'ESRCH') {
+            // The kernel observed absence after this exact instance was verified.
+            removeBrokerIdentity(paths, identity, deps);
+            return true;
+        }
+        // Retain the record when a matched exit was not observed.
     }
-    return { matchedCount, killedCount };
+    deps.warn(`Broker orphan process may still be running (pid: ${identity.pid})`);
+    return false;
 }
 function ensureBundledAgentRelayMcpCommand(deps) {
     if (deps.env.AGENT_RELAY_MCP_COMMAND?.trim()) {
@@ -907,24 +850,30 @@ async function waitForProcessExit(pid, timeoutMs, deps) {
     }
     return false;
 }
-async function recoverHalfStartedBroker(paths, deps) {
+async function recoverHalfStartedBroker(paths, deps, brokerName) {
     deps.fs.mkdirSync(paths.dataDir, { recursive: true });
     const readiness = await waitForBrokerReadiness(paths, deps, 0, true);
     if (readiness.state === 'running') {
         return 'running';
     }
     if (readiness.state === 'starting') {
-        deps.warn(`Broker process is running but the API is not ready; killing half-started broker (pid: ${readiness.conn.pid}).`);
-        const stopped = await terminateProcess(readiness.conn.pid, deps, true);
+        deps.warn(`Broker process is running but the API is not ready; verifying half-started broker ownership (pid: ${readiness.conn.pid}).`);
+        const identities = readBrokerIdentities(paths, deps);
+        const identity = identities?.find((record) => record.pid === readiness.conn.pid);
+        const stopped = identity && (await stopRecordedBroker(paths, identity, deps, true));
         if (!stopped) {
             deps.error(`Failed to stop half-started broker process (pid: ${readiness.conn.pid}). ` +
-                'Run `agent-relay down --force` to retry cleanup, or remove `.agentworkforce/relay/` after stopping the process.');
+                `Verify process ownership manually before stopping it; inspect identities in ${path.join(paths.projectRoot, '.agentworkforce', 'relay')}. Connection metadata alone cannot authorize a signal.`);
             return 'blocked';
         }
         cleanupBrokerFiles(paths, deps);
         return 'recovered';
     }
-    const orphanCleanup = await killOrphanedBrokerProcesses(paths.projectRoot, deps, { force: true });
+    const orphanCleanup = await killOrphanedBrokerProcesses(paths, deps, {
+        force: true,
+        brokerName,
+        matchBrokerName: true,
+    });
     if (orphanCleanup.matchedCount > 0) {
         if (orphanCleanup.killedCount < orphanCleanup.matchedCount) {
             deps.error('Failed to stop all half-started broker processes. ' +
@@ -934,20 +883,29 @@ async function recoverHalfStartedBroker(paths, deps) {
         cleanupBrokerFiles(paths, deps);
         return 'recovered';
     }
-    cleanupBrokerFiles(paths, deps);
     return 'clear';
 }
 function cleanupBrokerFiles(paths, deps) {
+    // A concurrent replacement or another named broker still owns discovery
+    // state. Unreadable records are likewise not permission to remove it.
+    if (readBrokerIdentities(paths, deps)?.length !== 0)
+        return;
+    // A replacement can publish connection.json before its identity is captured.
+    const connection = readBrokerConnectionFromFs(deps.fs, paths.dataDir);
+    if (connection?.pid && isProcessRunning(connection.pid, deps))
+        return;
     const runtimePath = path.join(paths.dataDir, 'runtime.json');
     const relaySockPath = path.join(paths.dataDir, 'relay.sock');
     safeUnlink(path.join(paths.dataDir, CONNECTION_FILENAME), deps);
     safeUnlink(relaySockPath, deps);
     safeUnlink(runtimePath, deps);
     safeUnlink(backgroundStartErrorPath(paths.dataDir), deps);
-    // Clean up lock files and legacy pid files
+    // A lock pathname may still belong to an unverifiable or differently named
+    // live broker. Reusing the existing inode preserves its flock protection.
+    // Only legacy pid files are disposable here.
     try {
         for (const file of deps.fs.readdirSync(paths.dataDir)) {
-            if (file.startsWith('broker-') && (file.endsWith('.lock') || file.endsWith('.pid'))) {
+            if (file.startsWith('broker-') && file.endsWith('.pid')) {
                 safeUnlink(path.join(paths.dataDir, file), deps);
                 continue;
             }
@@ -1135,9 +1093,20 @@ export async function waitForNodeDelivery(relay, deps, waitMs = NODE_DELIVERY_RE
         await deps.sleep(Math.min(STATUS_POLL_INTERVAL_MS, Math.max(0, deadline - deps.now())));
     }
 }
-async function shutdownUpResources(relay, dataDir, deps) {
+async function shutdownUpResources(relay, paths, deps, observedChildExit) {
+    // The SDK clears its child handle on exit/shutdown, so preserve the owned
+    // PID before awaiting shutdown or use the exact observed-child snapshot.
+    const brokerPid = observedChildExit?.pid ?? relay.brokerPid;
+    const identity = readBrokerIdentities(paths, deps)?.find((record) => record.pid === brokerPid);
+    const owned = identity !== undefined && (await matchesBrokerIdentity(identity, paths, deps));
     await relay.shutdown().catch(() => undefined);
-    safeUnlink(path.join(dataDir, CONNECTION_FILENAME), deps);
+    if (observedChildExit && observedChildExit.pid === brokerPid)
+        removeBrokerIdentity(paths, observedChildExit, deps);
+    if (identity && owned && !isProcessRunning(identity.pid, deps))
+        removeBrokerIdentity(paths, identity, deps);
+    if (brokerPid && readBrokerPid(paths.dataDir, deps) === brokerPid) {
+        safeUnlink(path.join(paths.dataDir, CONNECTION_FILENAME), deps);
+    }
 }
 // eslint-disable-next-line complexity
 /**
@@ -1249,7 +1218,23 @@ function recordWorkspaceBindingSource(selection, deps, overrideSource) {
     deps.env[WORKSPACE_BINDING_SOURCE_ENV] = source;
     return source;
 }
+function resolveBrokerName(options, deps, projectRoot) {
+    return (options.brokerName?.trim() ||
+        deps.env.AGENT_RELAY_BROKER_NAME?.trim() ||
+        path.basename(projectRoot) ||
+        'project');
+}
 export async function runUpCommand(options, deps) {
+    if (!['darwin', 'linux'].includes(process.platform)) {
+        deps.error(`Broker lifecycle identity verification is supported only on macOS and Linux; refusing to start on ${process.platform}.`);
+        deps.exit(1);
+        return;
+    }
+    const localOnly = options.localOnly || deps.env.AGENT_RELAY_LOCAL_ONLY === '1';
+    if (localOnly) {
+        deps.env.AGENT_RELAY_LOCAL_ONLY = '1';
+        deps.warn('DEGRADED — LOCAL ONLY: fleet routing, worker presence, remote delivery and remote attachment are disabled.');
+    }
     ensureBundledAgentRelayMcpCommand(deps);
     const paths = deps.getProjectPaths();
     // The stable, default project data dir (`.agentworkforce/relay/`) captured
@@ -1293,7 +1278,7 @@ export async function runUpCommand(options, deps) {
         deps.env.RELAY_API_KEY = options.workspaceKey;
     }
     if (options.background) {
-        const preflight = await recoverHalfStartedBroker(paths, deps);
+        const preflight = await recoverHalfStartedBroker(paths, deps, options.brokerName);
         if (preflight === 'running') {
             const pid = readBrokerPid(paths.dataDir, deps);
             deps.error(pid
@@ -1358,17 +1343,20 @@ export async function runUpCommand(options, deps) {
             }
             for (const cleanupPid of cleanupPids) {
                 deps.warn(`Cleaning up failed broker start (pid: ${cleanupPid})`);
-                const stopped = await terminateProcess(cleanupPid, deps, true);
+                const identity = readBrokerIdentities(paths, deps)?.find((record) => record.pid === cleanupPid);
+                const stopped = cleanupPid === child.pid
+                    ? await terminateProcess(cleanupPid, deps, true)
+                    : identity && (await stopRecordedBroker(paths, identity, deps, true));
                 if (!stopped) {
                     deps.error(`Failed to stop half-started broker process (pid: ${cleanupPid}). ` +
-                        'Run `agent-relay down --force` to retry cleanup, or remove `.agentworkforce/relay/` after stopping the process.');
+                        `Verify process ownership before stopping it manually; inspect identities in ${path.join(paths.projectRoot, '.agentworkforce', 'relay')}.`);
                 }
             }
             cleanupBrokerFiles(paths, deps);
             deps.exit(1);
             return;
         }
-        const enrolledNodeToken = deps.env.RELAY_NODE_TOKEN?.trim();
+        const enrolledNodeToken = localOnly ? undefined : deps.env.RELAY_NODE_TOKEN?.trim();
         const enrolledNodeId = enrolledNodeToken ? deps.env.RELAY_NODE_ID?.trim() : undefined;
         let enrollmentFailureReason;
         if (enrolledNodeToken && !enrolledNodeId) {
@@ -1394,11 +1382,14 @@ export async function runUpCommand(options, deps) {
             let allStopped = true;
             for (const cleanupPid of cleanupPids) {
                 deps.warn(`Cleaning up failed broker start (pid: ${cleanupPid})`);
-                const stopped = await terminateProcess(cleanupPid, deps, true);
+                const identity = readBrokerIdentities(paths, deps)?.find((record) => record.pid === cleanupPid);
+                const stopped = cleanupPid === child.pid
+                    ? await terminateProcess(cleanupPid, deps, true)
+                    : identity && (await stopRecordedBroker(paths, identity, deps, true));
                 if (!stopped) {
                     allStopped = false;
                     deps.error(`Failed to stop broker process after Cloud enrollment startup failed (pid: ${cleanupPid}). ` +
-                        'Run `agent-relay down --force` to retry cleanup.');
+                        `Verify process ownership before stopping it manually; inspect identities in ${path.join(paths.projectRoot, '.agentworkforce', 'relay')}.`);
                 }
             }
             if (allStopped) {
@@ -1407,6 +1398,21 @@ export async function runUpCommand(options, deps) {
             deps.exit(1);
             return;
         }
+        const identityDeadline = deps.now() + DETACHED_START_READY_TIMEOUT_MS;
+        let identityReady = false;
+        while (deps.now() < identityDeadline && isProcessRunning(readiness.conn.pid, deps)) {
+            const record = readBrokerIdentities(paths, deps)?.find((entry) => entry.pid === readiness.conn.pid);
+            if (record && (await matchesBrokerIdentity(record, paths, deps))) {
+                identityReady = true;
+                break;
+            }
+            await deps.sleep(100);
+        }
+        if (!identityReady) {
+            deps.error(`Broker API is ready but process identity was not confirmed (pid: ${readiness.conn.pid}). State retained; verify ownership manually and inspect identities in ${path.join(paths.projectRoot, '.agentworkforce', 'relay')}.`);
+            deps.exit(1);
+            return;
+        }
         deps.log('Broker started.');
         deps.log(`Broker PID: ${readiness.conn.pid}`);
         deps.log('Stop with: agent-relay down');
@@ -1417,12 +1423,22 @@ export async function runUpCommand(options, deps) {
     const basePort = resolveBrokerBasePort(deps);
     deps.fs.mkdirSync(paths.dataDir, { recursive: true });
     const existingPid = readBrokerPid(paths.dataDir, deps);
+    const brokerName = resolveBrokerName(options, deps, paths.projectRoot);
     let relay = null;
     let nodeProviders;
     let reflexCapture;
     let shuttingDown = false;
     let sigintCount = 0;
     let shutdownPromise;
+    let stopWatchingBrokerExit;
+    let managedIdentity;
+    let ownedBrokerExited = false;
+    let rejectBrokerExit;
+    const brokerExit = new Promise((_resolve, reject) => {
+        rejectBrokerExit = reject;
+    });
+    // The child can exit during startup before holdOpen begins racing this promise.
+    void brokerExit.catch(() => undefined);
     const shutdownOnce = async () => {
         if (!shutdownPromise) {
             shuttingDown = true;
@@ -1433,7 +1449,7 @@ export async function runUpCommand(options, deps) {
                 shutdownPromise = (async () => {
                     await reflexCapture?.stop();
                     await nodeProviders?.stop();
-                    await shutdownUpResources(relay, paths.dataDir, deps);
+                    await shutdownUpResources(relay, paths, deps, ownedBrokerExited ? managedIdentity : undefined);
                 })();
             }
         }
@@ -1483,7 +1499,7 @@ export async function runUpCommand(options, deps) {
         applyNodeLogEnv(options, deps);
         // Resolved BEFORE the broker starts so an explicit bad --config fails
         // fast instead of tearing down a broker that just came up.
-        const nodePlan = await resolveNodeDefinitionForUp(paths, options, deps);
+        const nodePlan = localOnly ? undefined : await resolveNodeDefinitionForUp(paths, options, deps);
         const teamsConfig = deps.loadTeamsConfig(paths.projectRoot);
         // The broker advertises spawn:<harness> capacity for this set. A pre-set
         // AGENT_RELAY_NODE_HARNESSES is the operator's authoritative declaration of the
@@ -1491,11 +1507,17 @@ export async function runUpCommand(options, deps) {
         // the project's runnable harnesses (built-in defaults plus teams.json clis and
         // any spawn:<harness> definitions) and passes it to the broker before it registers.
         deps.env.AGENT_RELAY_NODE_HARNESSES = resolveNodeCapacityHarnesses(deps.env.AGENT_RELAY_NODE_HARNESSES, teamsConfig, planCapacitySource(nodePlan));
-        // Kill any orphaned broker processes for this project that lost their PID
-        // files (e.g. user deleted .agentworkforce/relay/ while broker was running).
+        // Recover a broker whose discovery files were lost only while its persisted
+        // process identity and original runtime lock still prove ownership.
         vlog(deps, options.verbose, 'Checking for orphaned broker processes...');
-        await killOrphanedBrokerProcesses(paths.projectRoot, deps);
-        const started = await startBrokerWithPortFallback(paths, basePort, deps, options.brokerName, options.verbose, 
+        const orphanCleanup = await killOrphanedBrokerProcesses(paths, deps, {
+            brokerName,
+            matchBrokerName: true,
+        });
+        if (orphanCleanup.matchedCount > orphanCleanup.killedCount) {
+            throw new Error('Could not verify orphan broker exit; retained its state for a later cleanup.');
+        }
+        const started = await startBrokerWithPortFallback(paths, basePort, deps, brokerName, options.verbose, 
         // Assign `relay` as soon as the broker child process exists, not only
         // once the handshake/status-check retries above also succeed. A
         // SIGTERM/SIGINT arriving during that check window otherwise finds
@@ -1512,6 +1534,16 @@ export async function runUpCommand(options, deps) {
             throw err;
         });
         relay = started.relay;
+        stopWatchingBrokerExit = relay.onBrokerExit?.(() => {
+            ownedBrokerExited = true;
+            if (!shuttingDown)
+                rejectBrokerExit(new Error('Broker exited; stopping the node supervisor.'));
+        });
+        if (relay.brokerPid)
+            managedIdentity = await persistBrokerIdentity(paths, relay.brokerPid, brokerName, deps);
+        if (!managedIdentity) {
+            throw new Error('Could not persist a verified broker process identity. Startup was stopped; ensure ps and lsof are available, process inspection is permitted, and the project identity directory is writable.');
+        }
         try {
             writeBrokerBindingSource(paths.dataDir, workspaceBindingSource, deps);
         }
@@ -1528,7 +1560,10 @@ export async function runUpCommand(options, deps) {
         const joinedWorkspaceId = relay.workspaceId ?? 'unknown';
         // The multi-workspace session always joins a configured membership; it
         // never mints a new workspace the way an unresolved single key does.
-        if (workspaceSelection || joinsMultiWorkspaceSession) {
+        if (localOnly) {
+            deps.log('Workspace: local only; configured credentials are used only for delivery-record reconciliation');
+        }
+        else if (workspaceSelection || joinsMultiWorkspaceSession) {
             deps.log(`Workspace: joined ${joinedWorkspaceId}`);
         }
         else {
@@ -1560,7 +1595,9 @@ export async function runUpCommand(options, deps) {
             // can't be written (read-only dir, etc.).
         }
         vlog(deps, options.verbose, 'Starting node capability providers (if any)...');
-        nodeProviders = await startNodeCapabilityProviders(paths, relay, options, deps, nodePlan);
+        nodeProviders = localOnly
+            ? undefined
+            : await startNodeCapabilityProviders(paths, relay, options, deps, nodePlan);
         // When Reflex is enabled, periodically sync + push local session history to
         // relayhistory-cloud in-process via the ai-hist-native addon (no subprocess).
         // No-op when disabled or the addon isn't available.
@@ -1571,7 +1608,9 @@ export async function runUpCommand(options, deps) {
             // Node delivery can't connect until the broker mints its node token, which
             // now happens in the background after `Broker started.`. Budget for that
             // mint window plus the connect so a slow mint doesn't abort auto-spawn.
-            const delivery = await waitForNodeDelivery(relay, deps, NODE_TOKEN_WAIT_MS + NODE_DELIVERY_READY_TIMEOUT_MS);
+            const delivery = localOnly
+                ? { ready: true, status: null }
+                : await waitForNodeDelivery(relay, deps, NODE_TOKEN_WAIT_MS + NODE_DELIVERY_READY_TIMEOUT_MS);
             if (!delivery.ready) {
                 deps.error('Refusing to auto-spawn agents because broker node delivery is not connected.');
                 deps.error(`Node delivery: ${formatNodeDeliveryStatus(delivery.status)}`);
@@ -1594,7 +1633,7 @@ export async function runUpCommand(options, deps) {
         else if (options.spawn === true && !teamsConfig) {
             deps.warn('Warning: --spawn specified but no teams.json found');
         }
-        const holdOpen = deps.holdOpen();
+        const holdOpen = Promise.race([deps.holdOpen(), brokerExit]);
         if (nodeProviders?.done) {
             await Promise.race([holdOpen, nodeProviders.done]);
         }
@@ -1622,6 +1661,7 @@ export async function runUpCommand(options, deps) {
         deps.exit(1);
     }
     finally {
+        stopWatchingBrokerExit?.();
         crashGuard.dispose();
     }
 }
@@ -1681,7 +1721,16 @@ export async function runDownCommand(options, deps) {
     const conn = readBrokerConnectionFromFs(deps.fs, paths.dataDir);
     if (!conn) {
         if (options.force) {
-            await killOrphanedBrokerProcesses(paths.projectRoot, deps, { force: true });
+            const result = await killOrphanedBrokerProcesses(paths, deps, { force: true });
+            if (result.matchedCount > result.killedCount) {
+                deps.error('Could not verify broker exit; retained its state for a later cleanup.');
+                deps.exit(1);
+                return;
+            }
+            if (result.matchedCount === 0) {
+                deps.log('No verified orphan broker found; retained existing state.');
+                return;
+            }
             cleanupBrokerFiles(paths, deps);
             deps.log('Cleaned up (was not running)');
         }
@@ -1701,40 +1750,52 @@ export async function runDownCommand(options, deps) {
         deps.log('Cleaned up stale state (process was not running)');
         return;
     }
+    const identities = readBrokerIdentities(paths, deps);
+    const identity = identities?.find((record) => record.pid === pid);
+    if (!identity || !(await matchesBrokerIdentity(identity, paths, deps))) {
+        deps.error(`Broker identity could not be verified (pid: ${pid}); retained its state. Verify ownership before stopping the process manually; inspect identities in ${path.join(paths.projectRoot, '.agentworkforce', 'relay')}. Connection metadata alone cannot authorize a signal.`);
+        deps.exit(1);
+        return;
+    }
     try {
         deps.log(`Stopping broker (pid: ${pid})...`);
         deps.killProcess(pid, 'SIGTERM');
-        const exited = await waitForProcessExit(pid, timeout, deps);
+        let exited = await waitForProcessExit(pid, timeout, deps);
         if (!exited) {
             // eslint-disable-next-line max-depth
             if (options.force) {
                 deps.log('Graceful shutdown timed out, forcing...');
-                // eslint-disable-next-line max-depth
-                try {
-                    deps.killProcess(pid, 'SIGKILL');
-                    await waitForProcessExit(pid, 2000, deps);
-                }
-                catch {
-                    // Ignore kill errors.
+                if (identity && !(await matchesBrokerIdentity(identity, paths, deps))) {
+                    throw new Error('Broker identity changed before escalation; retained its state.');
                 }
+                deps.killProcess(pid, 'SIGKILL');
+                exited = await waitForProcessExit(pid, 2000, deps);
             }
             else {
                 deps.log(`Graceful shutdown timed out after ${timeout}ms. Use --force to kill.`);
                 return;
             }
         }
+        if (!exited) {
+            throw new Error('Could not verify broker exit; retained its state for a later cleanup.');
+        }
+        if (identity)
+            removeBrokerIdentity(paths, identity, deps);
         cleanupBrokerFiles(paths, deps);
         deps.log('Stopped');
+        return;
     }
     catch (err) {
         const withCode = err;
         if (withCode.code === 'ESRCH') {
+            removeBrokerIdentity(paths, identity, deps);
             cleanupBrokerFiles(paths, deps);
             deps.log('Cleaned up stale state');
             return;
         }
         deps.error(`Error stopping broker: ${toErrorMessage(err)}`);
     }
+    deps.exit(1);
 }
 export async function runStatusCommand(deps, options) {
     const paths = deps.getProjectPaths();
@@ -1762,16 +1823,24 @@ export async function runStatusCommand(deps, options) {
         deps.exit(1);
         return;
     }
-    deps.log('Status: RUNNING');
-    deps.log('Mode: broker (stdio)');
+    const statusDetails = readiness.statusDetails ?? (waitMs > 0 ? null : await readBrokerStatusDetails(readiness.conn));
+    const localOnly = statusDetails?.status.mode === 'local_only' || readiness.conn.operation_mode === 'local_only';
+    deps.log(localOnly ? 'Status: DEGRADED (LOCAL ONLY)' : 'Status: RUNNING');
+    deps.log(localOnly ? 'Mode: local only' : 'Mode: broker (stdio)');
+    if (localOnly) {
+        deps.warn('Cross-machine routing, worker presence, remote delivery and remote attachment: DISABLED');
+        const reconciliation = statusDetails?.status.degraded?.reconciliation;
+        if (reconciliation) {
+            deps.log(`Reconciliation: ${reconciliation.connected ? 'connected (audit only)' : reconciliation.configured ? 'disconnected' : 'not configured'}; pending records: ${reconciliation.pending_records}`);
+        }
+    }
     deps.log(`PID: ${readiness.conn.pid}`);
     deps.log(`Project: ${paths.projectRoot}`);
     const source = workspaceBindingSource(readiness.conn.workspace_source);
     deps.log(source
         ? `Workspace source: ${workspaceBindingSourceLabel(source)}`
         : 'Workspace source: unknown (startup provenance was not recorded)');
-    // Query the running broker for additional status info
-    const statusDetails = readiness.statusDetails ?? (waitMs > 0 ? null : await readBrokerStatusDetails(readiness.conn));
+    // Additional runtime details use the same bounded snapshot as the mode above.
     if (!statusDetails || statusDetails.session === null) {
         deps.warn('Broker API details unavailable (request failed or exceeded the 2s limit).');
     }