agent-relay 11.4.0 → 11.4.2

package/dist/cli/commands/workspace.js

@@ -3,7 +3,17 @@ import { resolveActiveWorkspace } from '@agent-relay/cloud';
 import { maskSecret } from '../lib/redact.js';
 import { printJson, runSdk, withSdkDefaults } from '../lib/sdk-command.js';
 import { readWorkspaceStore, setWorkspaceKey } from '../lib/workspace-store.js';
-import { persistWorkspaceSession, validateWorkspaceSessionName } from '../lib/workspace-session.js';
+import { describeClearedEnrollment, persistWorkspaceSession, pinProjectWorkspaceSession, validateWorkspaceSessionName, } from '../lib/workspace-session.js';
+/**
+ * Say so when moving workspaces drops this project's enrolled fleet node.
+ * Leaving it silent is what produced the split rosters in #1432.
+ */
+function reportClearedEnrollment(result, deps) {
+    const message = describeClearedEnrollment(result);
+    if (message) {
+        deps.log(message);
+    }
+}
 function parsePositiveInteger(value) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -56,14 +66,27 @@ export function registerWorkspaceCommands(program, overrides = {}) {
         await runSdk(deps, async () => {
             const workspaceName = validateWorkspaceSessionName(name);
             const relay = await deps.createWorkspace(workspaceName, o.baseUrl);
-            if (relay.workspaceKey) {
-                persistWorkspaceSession({ name: workspaceName, workspaceKey: relay.workspaceKey });
+            const previousActive = readWorkspaceStore().active;
+            const persisted = relay.workspaceKey
+                ? persistWorkspaceSession({ name: workspaceName, workspaceKey: relay.workspaceKey })
+                : {};
+            if (relay.workspaceKey && previousActive && previousActive !== workspaceName) {
+                deps.error(`⚠  Active workspace changed: ${previousActive} → ${workspaceName}`);
+                deps.error('   Restore with: agent-relay workspace restore');
             }
             // The key is persisted to the workspace store either way; the output
-            // masks it unless the caller explicitly asks for the raw value.
+            // masks it unless the caller explicitly asks for the raw value. A
+            // dropped enrollment rides in the JSON rather than a log line so the
+            // output stays parseable.
             printJson(deps, {
                 name: workspaceName,
                 workspaceKey: relay.workspaceKey && !o.revealSecrets ? maskSecret(relay.workspaceKey) : relay.workspaceKey,
+                ...(persisted.clearedEnrolledNodeId
+                    ? {
+                        clearedEnrolledNodeId: persisted.clearedEnrolledNodeId,
+                        warning: describeClearedEnrollment(persisted),
+                    }
+                    : {}),
             });
         });
     });
@@ -75,6 +98,7 @@ export function registerWorkspaceCommands(program, overrides = {}) {
             const store = readWorkspaceStore();
             printJson(deps, {
                 active: store.active,
+                previous: store.previous,
                 workspaces: Object.keys(store.workspaces),
             });
         });
@@ -116,8 +140,9 @@ export function registerWorkspaceCommands(program, overrides = {}) {
         .argument('<key>', 'Workspace key')
         .action(async (name, key) => {
         await runSdk(deps, async () => {
-            persistWorkspaceSession({ name, workspaceKey: key });
+            const result = persistWorkspaceSession({ name, workspaceKey: key });
             deps.log(`Joined and switched to workspace "${name}".`);
+            reportClearedEnrollment(result, deps);
         });
     });
     group
@@ -131,8 +156,49 @@ export function registerWorkspaceCommands(program, overrides = {}) {
             if (!workspace) {
                 throw new Error(`Unknown workspace "${name}". Add it with \`relay workspace set_key ${name} <key>\`.`);
             }
-            persistWorkspaceSession({ name, workspaceKey: workspace.key });
+            const result = persistWorkspaceSession({ name, workspaceKey: workspace.key });
             deps.log(`Switched to workspace "${name}".`);
+            reportClearedEnrollment(result, deps);
+        });
+    });
+    group
+        .command('restore')
+        .description('Switch back to the previously active workspace')
+        .action(async () => {
+        await runSdk(deps, async () => {
+            const store = readWorkspaceStore();
+            const previous = store.previous;
+            if (!previous) {
+                throw new Error('No previous workspace is recorded.');
+            }
+            if (previous === store.active) {
+                throw new Error(`The recorded previous workspace "${previous}" is already active.`);
+            }
+            const workspace = Object.hasOwn(store.workspaces, previous) ? store.workspaces[previous] : undefined;
+            if (!workspace) {
+                throw new Error(`The recorded previous workspace "${previous}" no longer exists.`);
+            }
+            const current = store.active;
+            persistWorkspaceSession({ name: previous, workspaceKey: workspace.key });
+            deps.log(`Switched to workspace "${previous}" (was ${current ?? 'none'}).`);
+        });
+    });
+    group
+        .command('rebind')
+        .description("Pin this project's broker to a stored workspace")
+        .argument('<name>', 'Stored workspace name')
+        .action(async (name) => {
+        await runSdk(deps, async () => {
+            const workspaceName = validateWorkspaceSessionName(name);
+            const store = readWorkspaceStore();
+            const workspace = Object.hasOwn(store.workspaces, workspaceName)
+                ? store.workspaces[workspaceName]
+                : undefined;
+            if (!workspace) {
+                throw new Error(`Unknown workspace "${workspaceName}". Add it with \`relay workspace set_key ${workspaceName} <key>\`.`);
+            }
+            pinProjectWorkspaceSession({ workspaceKey: workspace.key });
+            deps.log(`Rebound this project's broker to workspace "${workspaceName}". Restart the broker to apply it.`);
         });
     });
 }

package/dist/cli/commands/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/cli/commands/workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/cli/commands/workspace.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAWA,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAYA,cAAc,gBAAgB,CAAC"}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { runAiSdkSidecarMain } from '@agent-relay/harnesses';
 import { runCli } from './bootstrap.js';
 import { describeError } from './lib/describe-error.js';
+import { exitAfterFlush } from './lib/flush-stdio.js';
 export * from './bootstrap.js';
 function isEntrypoint() {
     const invocationPath = process.argv[1];
@@ -19,13 +20,16 @@ function isEntrypoint() {
 }
 if (isEntrypoint()) {
     const main = process.argv[2] === '__ai-sdk-sidecar' ? runAiSdkSidecarMain(process.argv.slice(3)) : runCli();
-    main.catch((err) => {
+    main.catch(async (err) => {
         // Commander will have already printed a helpful message for parse errors.
         // For other top-level failures, surface them to stderr and exit non-zero.
         // `describeError` keeps a non-Error rejection (e.g. `{ status: 401 }` from
         // a broker client) readable instead of collapsing it to `[object Object]`.
         process.stderr.write(`${describeError(err)}\n`);
-        process.exit(1);
+        // Flush first: on macOS a piped stderr is asynchronous, so exiting in this
+        // tick would discard the message we just wrote and leave the caller with a
+        // silent non-zero exit.
+        await exitAfterFlush(1);
     });
 }
 //# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,cAAc,gBAAgB,CAAC;AAE/B,SAAS,YAAY;IACnB,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5G,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACjB,0EAA0E;QAC1E,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,cAAc,gBAAgB,CAAC;AAE/B,SAAS,YAAY;IACnB,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5G,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,0EAA0E;QAC1E,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,2EAA2E;QAC3E,2EAA2E;QAC3E,wBAAwB;QACxB,MAAM,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/lib/broker-lifecycle.d.ts

@@ -1,9 +1,12 @@
 import { type FleetNodeDefinition } from '@agent-relay/fleet';
 import type { CoreDependencies, CoreProjectPaths, CoreRelay } from '../commands/core.js';
 import { type NodeDefinitionDescriptor } from './node-provider-child.js';
+import { type WorkspaceSelection } from './project-workspace-key.js';
 type UpOptions = {
     spawn?: boolean;
     background?: boolean;
+    /** Internal marker set only on the detached child re-exec. */
+    backgroundChild?: boolean;
     verbose?: boolean;
     workspaceKey?: string;
     stateDir?: string;
@@ -31,11 +34,15 @@ type DownOptions = {
     timeout?: string;
     stateDir?: string;
 };
+export declare const WORKSPACE_BINDING_SOURCE_ENV = "AGENT_RELAY_WORKSPACE_SOURCE";
+export type WorkspaceBindingSource = WorkspaceSelection['source'] | 'created' | 'multi-workspace';
 export interface BrokerConnection {
     url: string;
     port: number;
     api_key: string;
     pid: number;
+    /** Non-secret provenance recorded by the CLI after the broker handshake. */
+    workspace_source?: WorkspaceBindingSource;
 }
 type NodeDeliveryStatus = {
     tokenPresent: boolean;

package/dist/cli/lib/broker-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/broker-lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"broker-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/broker-lifecycle.ts"],"names":[],"mappings":"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"}

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

@@ -1,8 +1,10 @@
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 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 { track } from '../telemetry/index.js';
 import { buildBundledAgentRelayMcpCommand } from './agent-relay-mcp-command.js';
 import { errorClassName } from './telemetry-helpers.js';
@@ -12,13 +14,14 @@ import { describeNodeDefinitionViaNode, descriptorCapacitySource, startNodeJsNod
 import { describeError } from './describe-error.js';
 import { maskSecret } from './redact.js';
 import { startReflexCapture } from './reflex-capture.js';
-import { projectWorkspaceKeyPath, writeProjectWorkspaceKey } from './project-workspace-key.js';
-import { promoteWorkspaceKeyEnvAlias } from './workspace-env.js';
+import { readProjectWorkspaceSession, resolveWorkspaceSelection, writeProjectWorkspaceKey, } from './project-workspace-key.js';
 const MAX_API_PORT_ATTEMPTS = 25;
 const MAX_PORT = 65535;
 const DEFAULT_BROKER_BASE_PORT = 3888;
 /** The broker writes this file with URL, port, API key, and PID. */
 const CONNECTION_FILENAME = 'connection.json';
+const BACKGROUND_START_ERROR_FILENAME = 'background-start-error.log';
+export const WORKSPACE_BINDING_SOURCE_ENV = 'AGENT_RELAY_WORKSPACE_SOURCE';
 const STATUS_POLL_INTERVAL_MS = 500;
 const DETACHED_START_READY_TIMEOUT_MS = 10_000;
 const NODE_DELIVERY_READY_TIMEOUT_MS = 10_000;
@@ -188,7 +191,7 @@ export function describeErrorWithCause(err) {
         parts.push(detail);
     if (codes.length > 0)
         parts.push(`[${codes.join(', ')}]`);
-    return parts.join(' — ');
+    return redactCredentialValues(parts.join(' — '));
 }
 /**
  * Pick the best `error_class` for telemetry. Prefer a network-style code from
@@ -534,6 +537,77 @@ function safeUnlink(filePath, deps) {
         // Best-effort cleanup.
     }
 }
+function workspaceBindingSource(value) {
+    return value === 'flag' ||
+        value === 'env' ||
+        value === 'project' ||
+        value === 'store' ||
+        value === 'created' ||
+        value === 'multi-workspace'
+        ? value
+        : undefined;
+}
+function workspaceBindingSourceLabel(source) {
+    switch (source) {
+        case 'flag':
+            return 'command-line flag (--workspace-key / --wk)';
+        case 'env':
+            return 'environment (RELAY_WORKSPACE_KEY > AGENT_RELAY_WORKSPACE_KEY > RELAY_API_KEY)';
+        case 'project':
+            return 'repository pin (.agentworkforce/relay/workspace-key.json)';
+        case 'store':
+            return 'machine-global active workspace (~/.agentworkforce/relay/workspaces.json)';
+        case 'created':
+            return 'created (no configured workspace resolved)';
+        case 'multi-workspace':
+            return 'multi-workspace session ($RELAY_WORKSPACES_JSON)';
+    }
+}
+/** True when `RELAY_WORKSPACES_JSON` carries at least one membership. The broker's
+ * `startup_session_set_with_options` checks this env var before any single
+ * workspace key (flag, env, repository pin, or machine-global store), so the
+ * CLI's precedence ladder must defer to it for provenance too — otherwise
+ * `node up` / `node status` can report a source the broker never used. */
+function usesMultiWorkspaceEnv(env) {
+    return Boolean(env.RELAY_WORKSPACES_JSON?.trim());
+}
+function writeBrokerBindingSource(dataDir, source, deps) {
+    const connectionPath = path.join(dataDir, CONNECTION_FILENAME);
+    const connection = readBrokerConnectionFromFs(deps.fs, dataDir);
+    if (!connection)
+        return;
+    // Every CLI invocation resolves the broker through this file, so a
+    // concurrent writer must never observe a partial or clobbered write.
+    // Write to a private tmp file and rename it into place, which is atomic
+    // on the same filesystem.
+    const tmpPath = `${connectionPath}.tmp-${process.pid}-${randomUUID()}`;
+    deps.fs.writeFileSync(tmpPath, `${JSON.stringify({ ...connection, workspace_source: source }, null, 2)}\n`, 'utf-8');
+    deps.fs.renameSync(tmpPath, connectionPath);
+}
+function backgroundStartErrorPath(dataDir) {
+    return path.join(dataDir, BACKGROUND_START_ERROR_FILENAME);
+}
+function readBackgroundStartError(dataDir, deps) {
+    try {
+        return deps.fs.readFileSync(backgroundStartErrorPath(dataDir), 'utf-8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function recordBackgroundStartError(message, dataDir, isDetachedChild, deps) {
+    if (!isDetachedChild)
+        return;
+    try {
+        // Never trust a project-loaded environment variable as a filesystem path.
+        // Detached startup owns one fixed diagnostic file inside its resolved
+        // broker state directory; foreground failures do not write it at all.
+        deps.fs.writeFileSync(backgroundStartErrorPath(dataDir), `${message}\n`, 'utf-8');
+    }
+    catch {
+        // Diagnostics must never replace the original startup error.
+    }
+}
 function readBrokerPid(dataDir, _deps) {
     const conn = readBrokerConnectionFromFs(_deps.fs, dataDir);
     return conn?.pid ?? null;
@@ -739,6 +813,7 @@ function cleanupBrokerFiles(paths, deps) {
     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
     try {
         for (const file of deps.fs.readdirSync(paths.dataDir)) {
@@ -777,6 +852,9 @@ function childUpArgsForDetachedStart(options, deps) {
     if (options.verbose === true && !args.includes('--verbose')) {
         args.push('--verbose');
     }
+    if (!args.includes('--background-child')) {
+        args.push('--background-child');
+    }
     return args;
 }
 /** Drop each named option and, for the space-separated form, its value token. */
@@ -859,11 +937,14 @@ async function checkBrokerReadiness(paths, deps, requireApi) {
     }
     return { state: 'starting', conn };
 }
-async function waitForBrokerReadiness(paths, deps, waitMs, requireApi, verbose) {
+async function waitForBrokerReadiness(paths, deps, waitMs, requireApi, verbose, stopWhenPidExits) {
     const deadline = deps.now() + waitMs;
     let latest = await checkBrokerReadiness(paths, deps, requireApi);
     vlog(deps, verbose, `Broker readiness: ${latest.state}`);
     while (latest.state !== 'running' && waitMs > 0 && deps.now() < deadline) {
+        if (stopWhenPidExits && !isProcessRunning(stopWhenPidExits, deps)) {
+            return latest;
+        }
         await deps.sleep(Math.min(STATUS_POLL_INTERVAL_MS, Math.max(0, deadline - deps.now())));
         const previousState = latest.state;
         latest = await checkBrokerReadiness(paths, deps, requireApi);
@@ -988,39 +1069,58 @@ function planCapacitySource(plan) {
     }
     return plan.mode === 'in-process' ? plan.definition : descriptorCapacitySource(plan.descriptor);
 }
-/** Read the minimal project session needed during broker startup. */
-function readPinnedProjectWorkspaceSession(dataDir, deps) {
-    try {
-        const parsed = JSON.parse(deps.fs.readFileSync(projectWorkspaceKeyPath(dataDir), 'utf8'));
-        const workspaceKey = typeof parsed.workspaceKey === 'string' ? parsed.workspaceKey.trim() || undefined : undefined;
-        if (!workspaceKey) {
-            return undefined;
-        }
-        const enrolledNodeId = typeof parsed.enrolledNodeId === 'string' ? parsed.enrolledNodeId.trim() || undefined : undefined;
-        return {
-            workspaceKey,
-            ...(enrolledNodeId ? { enrolledNodeId } : {}),
-        };
-    }
-    catch {
+/**
+ * Apply the resolved workspace to the environment the broker (and any detached
+ * child) inherits, and report which source won. Returns the pinned project
+ * session when the repository pin supplied the selection.
+ */
+function applyWorkspaceSelection(selection, deps, projectDataDir) {
+    if (!selection) {
+        deps.log('Workspace: none selected (no --workspace-key, no RELAY_WORKSPACE_KEY, no repository pin, ' +
+            'no active workspace in the machine-global store). A new workspace will be created.');
         return undefined;
     }
-}
-/** Resume the pinned project session unless explicit credentials override it. */
-function resumePinnedProjectWorkspace(options, deps, projectDataDir) {
-    const explicitEnvWorkspaceKey = promoteWorkspaceKeyEnvAlias(deps.env);
-    if (options.workspaceKey?.trim() || explicitEnvWorkspaceKey || deps.env.RELAY_NODE_TOKEN?.trim()) {
+    deps.log(`Workspace source: ${describeWorkspaceSource(selection.source)} (${selection.origin})`);
+    // Normalize every winning source to the primary env var inherited by the
+    // broker and any detached child. Keep a caller-supplied RELAY_API_KEY intact
+    // when an explicit flag or environment variable won.
+    deps.env.RELAY_WORKSPACE_KEY = selection.key;
+    if (selection.source === 'project' || selection.source === 'store') {
+        deps.env.RELAY_API_KEY = selection.key;
+    }
+    if (selection.source !== 'project') {
         return undefined;
     }
-    const session = readPinnedProjectWorkspaceSession(projectDataDir, deps);
-    if (session) {
-        deps.env.RELAY_WORKSPACE_KEY = session.workspaceKey;
-        deps.env.RELAY_API_KEY = session.workspaceKey;
-        if (session.enrolledNodeId) {
-            deps.env.AGENT_RELAY_ENROLLED_NODE_ID = session.enrolledNodeId;
-        }
+    const pinned = readProjectWorkspaceSession(projectDataDir, deps.fs);
+    if (pinned?.enrolledNodeId) {
+        deps.env.AGENT_RELAY_ENROLLED_NODE_ID = pinned.enrolledNodeId;
+    }
+    return pinned;
+}
+/** Human-readable name for a precedence-ladder step, for the startup line. */
+function describeWorkspaceSource(source) {
+    switch (source) {
+        case 'flag':
+            return 'command-line flag';
+        case 'env':
+            return 'environment';
+        case 'project':
+            return 'repository pin';
+        case 'store':
+            return 'machine-global active workspace';
     }
-    return session;
+}
+/**
+ * Preserve the original source across `--background` re-exec. The detached
+ * child sees the normalized RELAY_WORKSPACE_KEY as an env selection, so this
+ * marker carries only provenance; it never participates in resolution.
+ */
+function recordWorkspaceBindingSource(selection, deps, overrideSource) {
+    const inheritedSource = workspaceBindingSource(deps.env[WORKSPACE_BINDING_SOURCE_ENV]);
+    const source = overrideSource ??
+        (selection?.source === 'env' && inheritedSource ? inheritedSource : (selection?.source ?? 'created'));
+    deps.env[WORKSPACE_BINDING_SOURCE_ENV] = source;
+    return source;
 }
 export async function runUpCommand(options, deps) {
     ensureBundledAgentRelayMcpCommand(deps);
@@ -1031,7 +1131,25 @@ export async function runUpCommand(options, deps) {
     // --state-dir), so the key must be persisted here even when broker state is
     // redirected elsewhere.
     const projectWorkspaceKeyDataDir = paths.dataDir;
-    const resumedProjectSession = resumePinnedProjectWorkspace(options, deps, projectWorkspaceKeyDataDir);
+    // The broker's startup_session_set_with_options() checks RELAY_WORKSPACES_JSON
+    // before any single workspace key, so a flag/env/pin/store resolution here
+    // would report provenance the broker never actually used.
+    const joinsMultiWorkspaceSession = usesMultiWorkspaceEnv(deps.env);
+    const workspaceSelection = joinsMultiWorkspaceSession
+        ? undefined
+        : resolveWorkspaceSelection({
+            workspaceKey: options.workspaceKey,
+            env: deps.env,
+            projectDataDir: projectWorkspaceKeyDataDir,
+            fileSystem: deps.fs,
+        });
+    const workspaceBindingSource = recordWorkspaceBindingSource(workspaceSelection, deps, joinsMultiWorkspaceSession ? 'multi-workspace' : undefined);
+    const resumedProjectSession = joinsMultiWorkspaceSession
+        ? undefined
+        : applyWorkspaceSelection(workspaceSelection, deps, projectWorkspaceKeyDataDir);
+    if (joinsMultiWorkspaceSession) {
+        deps.log(`Workspace source: ${workspaceBindingSourceLabel('multi-workspace')}`);
+    }
     // --state-dir overrides where the broker writes state / connection files
     if (options.stateDir) {
         const resolved = path.resolve(options.stateDir);
@@ -1062,6 +1180,8 @@ export async function runUpCommand(options, deps) {
             deps.exit(1);
             return;
         }
+        const startErrorPath = backgroundStartErrorPath(paths.dataDir);
+        safeUnlink(startErrorPath, deps);
         const args = childUpArgsForDetachedStart(options, deps);
         const invocation = detachedCliInvocation(deps, args);
         let child;
@@ -1079,18 +1199,31 @@ export async function runUpCommand(options, deps) {
         }
         child.unref?.();
         vlog(deps, options.verbose, `Spawned detached broker child (pid: ${child.pid ?? 'unknown'}), waiting for readiness...`);
-        const readiness = await waitForBrokerReadiness(paths, deps, DETACHED_START_READY_TIMEOUT_MS, true, options.verbose);
+        const readiness = await waitForBrokerReadiness(paths, deps, DETACHED_START_READY_TIMEOUT_MS, true, options.verbose, child.pid);
         if (readiness.state !== 'running') {
             const pid = readiness.state === 'starting' ? readiness.conn.pid : child.pid;
-            deps.error(pid
-                ? `Broker background start did not become ready within ${DETACHED_START_READY_TIMEOUT_MS / 1000}s (pid: ${pid}).`
-                : `Broker background start did not become ready within ${DETACHED_START_READY_TIMEOUT_MS / 1000}s.`);
+            const childExited = typeof child.pid === 'number' && child.pid > 0 && !isProcessRunning(child.pid, deps);
+            if (childExited) {
+                deps.error(`Broker background child exited before becoming ready (pid: ${child.pid}).`);
+            }
+            else {
+                deps.error(pid
+                    ? `Broker background start did not become ready within ${DETACHED_START_READY_TIMEOUT_MS / 1000}s (pid: ${pid}).`
+                    : `Broker background start did not become ready within ${DETACHED_START_READY_TIMEOUT_MS / 1000}s.`);
+            }
             if (readiness.state === 'starting') {
                 deps.error('Broker process is running, but the API did not become ready.');
             }
+            const detachedError = readBackgroundStartError(paths.dataDir, deps);
+            if (detachedError) {
+                deps.error(`Detached broker error: ${detachedError}`);
+            }
+            else if (childExited) {
+                deps.error('Retry without --background to see the broker startup error.');
+            }
             deps.error('Run `agent-relay status --wait-for=10` for details, or `agent-relay down --force` to clean up.');
             const cleanupPids = new Set();
-            if (typeof child.pid === 'number' && child.pid > 0) {
+            if (typeof child.pid === 'number' && child.pid > 0 && isProcessRunning(child.pid, deps)) {
                 cleanupPids.add(child.pid);
             }
             if (readiness.state === 'starting') {
@@ -1150,6 +1283,7 @@ export async function runUpCommand(options, deps) {
         deps.log('Broker started.');
         deps.log(`Broker PID: ${readiness.conn.pid}`);
         deps.log('Stop with: agent-relay down');
+        safeUnlink(startErrorPath, deps);
         deps.exit(0);
         return;
     }
@@ -1207,10 +1341,30 @@ export async function runUpCommand(options, deps) {
         await killOrphanedBrokerProcesses(paths.projectRoot, deps);
         const started = await startBrokerWithPortFallback(paths, basePort, deps, options.brokerName, options.verbose);
         relay = started.relay;
+        try {
+            writeBrokerBindingSource(paths.dataDir, workspaceBindingSource, deps);
+        }
+        catch {
+            // Provenance is diagnostic metadata; a broker that came up stays up.
+        }
+        safeUnlink(backgroundStartErrorPath(paths.dataDir), deps);
         deps.log(`Relay API: http://localhost:${started.apiPort}`);
         deps.log(`Project: ${paths.projectRoot}`);
         deps.log('Mode: broker (stdio)');
         deps.log(`Workspace Key: ${relay.workspaceKey ? maskSecret(relay.workspaceKey) : 'unknown'}`);
+        // Minting must be observable: without this line "created a workspace" and
+        // "joined the pinned workspace" print identically.
+        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) {
+            deps.log(`Workspace: joined ${joinedWorkspaceId}`);
+        }
+        else {
+            deps.log(`Workspace: created new workspace ${joinedWorkspaceId}`);
+            deps.log('Pin a workspace for this repository with `agent-relay up --workspace-key <key>`, ' +
+                'or select one machine-wide with `agent-relay workspace switch <name>`.');
+        }
         deps.log('Broker started.');
         // Record the workspace this broker joined (explicitly passed or auto-minted)
         // in the DEFAULT project data dir (not any --state-dir override), so later
@@ -1220,6 +1374,10 @@ export async function runUpCommand(options, deps) {
         try {
             writeProjectWorkspaceKey(projectWorkspaceKeyDataDir, relay.workspaceKey ?? undefined, {
                 enrolledNodeId: deps.env.AGENT_RELAY_ENROLLED_NODE_ID ?? resumedProjectSession?.enrolledNodeId,
+                // Recording the resolved workspace id lets the NEXT start detect a
+                // conflicting source (a stored enrollment in another workspace) before
+                // the broker comes up, instead of after agents land in the wrong place.
+                workspaceId: relay.workspaceId ?? resumedProjectSession?.workspaceId,
             });
         }
         catch {
@@ -1297,11 +1455,13 @@ export async function runUpCommand(options, deps) {
             stage,
             error_class: classifyBrokerStartError(err),
         });
+        const detailedMessage = describeErrorWithCause(err);
+        recordBackgroundStartError(detailedMessage, paths.dataDir, options.backgroundChild === true, deps);
         if (isBrokerAlreadyRunningError(message)) {
             reportAlreadyRunningError(message, paths.dataDir, deps);
         }
         else {
-            deps.error(`Failed to start broker: ${describeErrorWithCause(err)}`);
+            deps.error(`Failed to start broker: ${detailedMessage}`);
         }
         deps.exit(1);
     }
@@ -1447,6 +1607,10 @@ export async function runStatusCommand(deps, options) {
     deps.log('Mode: broker (stdio)');
     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));
     if (statusDetails) {