agent-relay 12.1.0 → 12.2.0

package/dist/cli/commands/fleet.js

@@ -1,15 +1,20 @@
 import { randomUUID } from 'node:crypto';
+import path from 'node:path';
 import { InvalidArgumentError } from 'commander';
-import { CloudFleetSandboxProvisionError, deleteCloudFleetSandbox, ensureCloudFleetSandbox, } from '@agent-relay/cloud';
+import { findProjectRoot } from '@agent-relay/config';
+import { CloudFleetSandboxProvisionError, deleteCloudFleetSandbox, ensureCloudFleetSandbox, materializeCloudRelayfileRepository, resolveWorkspaceByKey, } from '@agent-relay/cloud';
 import { HarnessDriverClient } from '@agent-relay/harness-driver';
 import { createWorkspaceClient, RelayPlacementError, } from '@agent-relay/sdk';
 import { withDefaults } from './core.js';
 import { buildRows, collectWithRetry, formatPretty, readRemoteLiveAgents, readLocalBrokerMaps, } from './fleet-agent.js';
 import { readBrokerConnection } from '../lib/broker-lifecycle.js';
+import { spawnAgentWithClient } from '../lib/client-factory.js';
+import { connectProjectBrokerClient } from '../lib/project-broker-client.js';
 import { isAvailableFleetNode } from '../lib/fleet-live-agents.js';
 import { declaredWorkforceMetadata } from '../lib/registration-metadata.js';
 import { redactSecrets } from '../lib/redact.js';
 import { attributableReleaseReason } from '../lib/release-reason.js';
+import { resolveSandboxRepository } from '../lib/sandbox-repo.js';
 import { spawnPlacementReceipt } from '../lib/spawn-lifecycle.js';
 import { resolveAgentToken, resolveWorkspaceSelection, persistWorkspaceRelaycastTarget, resolveWorkspaceKeyWithSource, resolveWorkspaceTransport, } from '../lib/sdk-client.js';
 import { addSdkOptions, printJson, runSdk, sdkOptionsFromOpts, withSdkDefaults, } from '../lib/sdk-command.js';
@@ -20,6 +25,56 @@ const CLOUD_SANDBOX_ID_PATTERN = /^sbx_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-
 function spawnInvocationWithPlacement(invocation) {
     return { ...invocation, placement: spawnPlacementReceipt(invocation) };
 }
+function assertSandboxRepositoryRevision(sandbox, selection) {
+    if (!selection)
+        return;
+    const expected = { [selection.repository]: selection.revision };
+    if (sandbox.outcome === 'provisioning_timeout') {
+        throw new Error(`Sandbox node '${sandbox.nodeName}' did not become ready within ${sandbox.waitedMs}ms; the repository revision was not verified.`);
+    }
+    const actual = sandbox.repoRevisions?.[selection.repository];
+    if (actual !== selection.revision || Object.keys(sandbox.repoRevisions ?? {}).length !== 1) {
+        throw new Error(`Cloud did not echo the requested repository revision for ${selection.repository}; update Cloud before retrying this sandbox launch.`);
+    }
+    // Keep the shape check explicit at the CLI boundary too: injected/test
+    // implementations and older Cloud clients must not bypass the attestation.
+    if (JSON.stringify(sandbox.repoRevisions) !== JSON.stringify(expected)) {
+        throw new Error(`Cloud returned an unexpected repository revision for ${selection.repository}.`);
+    }
+}
+function pathContains(parent, child) {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return (relative === '' ||
+        (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
+}
+function liveRelayfileMountPaths(materialization, requested) {
+    const contentRoot = materialization.contentRoot;
+    const sentinelRoot = path.posix.dirname(materialization.sentinelPath);
+    const requestedPaths = requested ?? [];
+    if (requestedPaths.length > 13) {
+        throw new Error('--sandbox-relayfile-path accepts at most 13 paths when a live repository, its source metadata, and workspace skills are mounted.');
+    }
+    const contentAncestor = requestedPaths.find((candidate) => {
+        const root = candidate
+            .trim()
+            .replace(/\/\*\*$/, '')
+            .replace(/\/$/, '');
+        return contentRoot === root || contentRoot.startsWith(`${root}/`);
+    });
+    if (contentAncestor && contentAncestor.trim() !== `${contentRoot}/**`) {
+        throw new Error(`Relayfile path ${JSON.stringify(contentAncestor)} contains the repository source root; omit it so Relay can mount ${contentRoot}/** as a decoded working tree.`);
+    }
+    return [...new Set([`${contentRoot}/**`, `${sentinelRoot}/**`, '/.skills/**', ...requestedPaths])];
+}
+function liveRelayfileWorkerCwd(mountRoot, materialization, relativeCwd) {
+    const root = mountRoot.replace(/\/+$/, '') || '/';
+    const sourceRoot = `${root === '/' ? '' : root}${materialization.contentRoot}`;
+    return relativeCwd ? `${sourceRoot}/${relativeCwd}` : sourceRoot;
+}
+function mountedRelayfilePath(mountRoot, remotePath) {
+    const root = mountRoot.replace(/\/+$/, '') || '/';
+    return `${root === '/' ? '' : root}${remotePath}`;
+}
 // The targeted spawn path (relay.messaging.placement.spawn) returns an
 // invocation whose `placement` is the SDK's own evidence object
 // (`state: 'accepted' | 'ready'`, `confirmed`). `spawnPlacementReceipt`
@@ -67,13 +122,19 @@ function withFleetDefaults(overrides = {}) {
     return {
         core,
         sdk,
+        cwd: () => process.cwd(),
+        connectLocalBroker: async (cwd) => connectProjectBrokerClient(cwd),
         createFleetWorkspaceClient: (options) => {
             const { workspaceKey, baseUrl } = resolveWorkspaceTransport(options);
             return createWorkspaceClient({ workspaceKey, baseUrl });
         },
         resolveWorkspaceSelection,
+        resolveSandboxRepository,
+        findProjectRoot,
+        resolveWorkspaceByKey,
         persistWorkspaceRelaycastTarget,
         ensureCloudFleetSandbox,
+        materializeCloudRelayfileRepository,
         deleteCloudFleetSandbox,
         log: (...args) => console.log(...args),
         warn: (...args) => console.warn(...args),
@@ -138,13 +199,15 @@ export function registerFleetCommands(program, overrides = {}) {
     });
     addSdkOptions(group
         .command('spawn')
-        .description('Spawn an agent on a fleet node')
+        .description('Spawn locally by default, or select a fleet node or Cloud sandbox explicitly')
         .argument('<cli>', 'AI CLI to launch', parseFleetCli)
         .requiredOption('--name <name>', 'Worker agent name')
         .requiredOption('--task <text>', 'Initial task instructions')
+        .option('--auto-place', 'Request automatic eligible-node placement in the Relay workspace')
         .option('--node <name>', 'Target a specific fleet node')
         .option('--target-node <name>', 'Alias for --node')
-        .option('--sandbox', 'Provision a fresh Cloud sandbox node, mount this Relayfile workspace, and spawn there')
+        .option('--sandbox', 'Provision a fresh Cloud sandbox and spawn with a live Relayfile workspace/repository mount')
+        .option('--checkout', 'Materialize the current Git checkout at its exact pushed HEAD (static; requires --sandbox)')
         .option('--sandbox-name <name>', 'Explicit sandbox node name (custom unless --sandbox-id requires matching fleet-sandbox-<UUID>)')
         .option('--sandbox-id <id>', 'Reuse a caller-declared sbx_<UUID> identity for an exact replay')
         .option('--workspace-id <id>', 'Explicit Relay workspace identity required for sandbox provisioning')
@@ -154,7 +217,7 @@ export function registerFleetCommands(program, overrides = {}) {
         .option('--channel <name>', 'Channel for the worker to join')
         .option('--persona <persona>', 'Worker persona (automatic placement)')
         .option('--model <model>', 'Model powering the worker')
-        .option('--cwd <path>', 'Absolute working directory for the spawned worker')
+        .option('--cwd <path>', 'Working directory: defaults to the caller directory for local spawn; maps a local repo-relative path with --sandbox; otherwise selects a path on the remote node')
         .option('--organization <organization>', 'Declared organization for workforce reporting')
         .option('--project <project>', 'Declared project for workforce reporting')
         .option('--workstream <workstream>', 'Declared workstream for workforce reporting')
@@ -164,14 +227,29 @@ export function registerFleetCommands(program, overrides = {}) {
         .option('--no-confirm', 'Report a targeted spawn as soon as the node accepts it, without waiting for the node to confirm the agent actually launched')
         .option('--confirm-timeout <ms>', 'How long a targeted spawn waits for the node to confirm the launch', '120000')).action(async (cli, options) => {
         await runSdk(deps.sdk, async () => {
-            warnIfInferredFromProjectSession(options, deps.warn);
             const clientOptions = sdkOptionsFromOpts(options);
             const name = requiredText(options.name, 'Worker name');
             const task = requiredText(options.task, 'Task');
             let targetNode = optionalText(options.targetNode, 'Target node') ?? optionalText(options.node, 'Node');
             const useSandbox = options.sandbox === true;
+            // Explicit hosted credentials/transport and personas retain their legacy
+            // automatic-placement contract. Ambient credentials and a persisted
+            // Cloud target must never turn a flag-free local spawn into a remote one.
+            const automaticPlacement = options.autoPlace === true ||
+                ['workspaceKey', 'token', 'baseUrl', 'persona'].some((key) => options[key] !== undefined);
+            if (options.autoPlace === true && (useSandbox || targetNode)) {
+                throw new Error('--auto-place cannot be combined with --sandbox, --node, or --target-node.');
+            }
+            if (useSandbox || targetNode || automaticPlacement) {
+                warnIfInferredFromProjectSession(options, deps.warn);
+            }
+            const checkoutRepository = options.checkout === true;
             const sandboxName = optionalText(options.sandboxName, 'Sandbox name');
             const sandboxIdOption = optionalText(options.sandboxId, 'Sandbox ID');
+            // An explicit sandbox identity is a retained/replayable resource. Never
+            // delete it as collateral when a later verification or dispatch step
+            // fails; only clean up sandboxes whose identity this invocation minted.
+            const shouldCleanupSandbox = sandboxIdOption === undefined;
             const explicitWorkspaceId = optionalText(options.workspaceId, 'Workspace ID');
             if (sandboxIdOption !== undefined && !CLOUD_SANDBOX_ID_PATTERN.test(sandboxIdOption)) {
                 throw new Error('--sandbox-id must match lowercase sbx_<UUID> using an RFC 4122 UUID.');
@@ -195,6 +273,9 @@ export function registerFleetCommands(program, overrides = {}) {
             if (!useSandbox && sandboxName) {
                 throw new Error('--sandbox-name requires --sandbox.');
             }
+            if (!useSandbox && checkoutRepository) {
+                throw new Error('--checkout requires --sandbox.');
+            }
             if (!useSandbox && sandboxIdOption) {
                 throw new Error('--sandbox-id requires --sandbox.');
             }
@@ -215,7 +296,8 @@ export function registerFleetCommands(program, overrides = {}) {
             }
             const channel = optionalText(options.channel, 'Channel');
             const model = optionalText(options.model, 'Model');
-            let workerCwd = optionalText(options.cwd, 'Worker cwd');
+            const requestedCwd = optionalText(options.cwd, 'Worker cwd');
+            let workerCwd = requestedCwd;
             const organization = optionalText(options.organization, 'Organization');
             const project = optionalText(options.project, 'Project');
             const workstream = optionalText(options.workstream, 'Workstream');
@@ -229,26 +311,90 @@ export function registerFleetCommands(program, overrides = {}) {
                 throw new Error('--confirm-timeout must be a positive number of milliseconds.');
             }
             let sandbox;
+            let sandboxRepository;
+            let liveRepository;
+            let attachProjectRoot;
             let workspaceRelay;
             let relaycastClientOptions = clientOptions;
             let legacyWorkspaceClientOptions = clientOptions;
             if (useSandbox) {
+                const coreProjectRoot = deps.core.getProjectPaths().projectRoot;
+                const hasExplicitProjectOverride = Boolean(deps.core.env?.AGENT_RELAY_PROJECT?.trim() || process.env.AGENT_RELAY_PROJECT?.trim());
+                if (checkoutRepository || mountSandboxRelayfile) {
+                    // AGENT_RELAY_PROJECT selects the workspace namespace, while static
+                    // checkout and live Relayfile source inference remain anchored to
+                    // the actual Git tree. This also lets --cwd point at a sibling
+                    // checkout when explicitly asked.
+                    const repositoryRootHint = hasExplicitProjectOverride ? process.cwd() : coreProjectRoot;
+                    sandboxRepository = deps.resolveSandboxRepository(repositoryRootHint, requestedCwd);
+                    if (checkoutRepository && !sandboxRepository) {
+                        throw new Error('--checkout requires a GitHub checkout with a clean, pushed commit.');
+                    }
+                    if (checkoutRepository && sandboxRepository) {
+                        workerCwd = sandboxRepository.workerCwd;
+                    }
+                    else if (sandboxRepository) {
+                        // Relative/local --cwd values were consumed by repository
+                        // inference and must be remapped beneath the remote live source
+                        // root after Cloud returns its provider-specific mount path.
+                        workerCwd =
+                            requestedCwd && /^\/(?:srv\/agent-workforce|workspace)(?:\/|$)/.test(requestedCwd)
+                                ? requestedCwd
+                                : undefined;
+                    }
+                }
+                const localRequestedCwd = sandboxRepository &&
+                    requestedCwd &&
+                    !/^\/(?:srv\/agent-workforce|workspace)(?:\/|$)/.test(requestedCwd)
+                    ? path.resolve(process.cwd(), requestedCwd)
+                    : undefined;
+                // With --checkout, `--cwd` selects both the local checkout subdirectory
+                // and its Relay project namespace. Resolve an intentional nested pin
+                // before mapping that path to the static remote checkout; only
+                // placement-safe Git identity crosses the Cloud boundary.
+                const workspaceProjectRoot = hasExplicitProjectOverride
+                    ? coreProjectRoot
+                    : localRequestedCwd
+                        ? deps.findProjectRoot(localRequestedCwd)
+                        : sandboxRepository && pathContains(sandboxRepository.projectRoot, coreProjectRoot)
+                            ? coreProjectRoot
+                            : (sandboxRepository?.projectRoot ?? coreProjectRoot);
+                if (path.resolve(workspaceProjectRoot) !== path.resolve(coreProjectRoot)) {
+                    attachProjectRoot = workspaceProjectRoot;
+                }
+                const sandboxClientOptions = {
+                    ...clientOptions,
+                    projectRoot: workspaceProjectRoot,
+                };
+                relaycastClientOptions = sandboxClientOptions;
                 // Cloud must be the first network authority for a sandbox invocation.
                 // A canonical Relaycast info call would both leak the workspace key and
                 // make it impossible to prove that Cloud's isolated target is the one
                 // subsequently used for registration and dispatch.
-                const workspaceSelection = deps.resolveWorkspaceSelection(clientOptions);
+                const workspaceSelection = deps.resolveWorkspaceSelection({
+                    ...sandboxClientOptions,
+                });
                 legacyWorkspaceClientOptions = {
-                    ...clientOptions,
+                    ...sandboxClientOptions,
                     ...(sandboxProvider === 'agent37' ? {} : { ignorePersistedRelaycastTarget: true }),
                 };
                 let relayWorkspaceId = explicitWorkspaceId ?? workspaceSelection?.workspaceId?.trim();
+                // Older/rebound project pins contain only the canonical key. Resolve
+                // that exact selection with Cloud using a POST body, never a key URL
+                // or an ambient active workspace. Successful target persistence below
+                // records the identity for the next invocation.
+                if (!relayWorkspaceId &&
+                    workspaceSelection?.key &&
+                    (sandboxProvider === undefined || sandboxProvider === 'agent37')) {
+                    const resolved = await deps.resolveWorkspaceByKey(workspaceSelection.key);
+                    relayWorkspaceId = resolved.cloudWorkspaceId;
+                }
                 // Legacy providers remain backward compatible: they may resolve the
                 // workspace from canonical Relaycast. Agent37 may not, because even a
                 // read there mutates rate-limit/presence accounting on the shared
                 // service and defeats the zero-shared-traffic canary proof.
                 if (!relayWorkspaceId && sandboxProvider === undefined) {
-                    throw new Error('Sandbox provisioning without --sandbox-provider requires a persisted Relay workspace identity; run `relay workspace pin` or pass --workspace-id.');
+                    throw new Error('Sandbox provisioning without --sandbox-provider requires a persisted Relay workspace identity; run `relay workspace rebind <name>` or pass --workspace-id.');
                 }
                 if (!relayWorkspaceId && sandboxProvider !== undefined && sandboxProvider !== 'agent37') {
                     workspaceRelay = deps.sdk.createWorkspaceRelay(legacyWorkspaceClientOptions);
@@ -257,9 +403,21 @@ export function registerFleetCommands(program, overrides = {}) {
                 }
                 if (!relayWorkspaceId) {
                     throw new Error(sandboxProvider === 'agent37'
-                        ? 'Agent37 sandbox provisioning requires a persisted Relay workspace identity; run `relay workspace pin` or pass --workspace-id.'
+                        ? 'Agent37 sandbox provisioning requires a persisted Relay workspace identity; run `relay workspace rebind <name>` or pass --workspace-id.'
                         : 'The current Relay workspace did not report an ID for Cloud provisioning.');
                 }
+                if (explicitWorkspaceId !== undefined &&
+                    workspaceSelection?.workspaceId !== undefined &&
+                    explicitWorkspaceId !== workspaceSelection.workspaceId.trim()) {
+                    throw new Error('--workspace-id does not match the captured workspace identity.');
+                }
+                if (!checkoutRepository && mountSandboxRelayfile && sandboxRepository) {
+                    liveRepository = await deps.materializeCloudRelayfileRepository({
+                        workspaceId: relayWorkspaceId,
+                        repository: sandboxRepository.repository,
+                        revision: sandboxRepository.revision,
+                    });
+                }
                 const sandboxId = sandboxIdOption ?? (sandboxName === undefined ? `sbx_${randomUUID()}` : undefined);
                 const deterministicSandboxName = sandboxId === undefined ? undefined : `fleet-sandbox-${sandboxId.slice('sbx_'.length)}`;
                 if (sandboxIdOption !== undefined &&
@@ -276,28 +434,33 @@ export function registerFleetCommands(program, overrides = {}) {
                 const workloadProfile = sandboxProvider === undefined || sandboxProvider === 'agent37'
                     ? 'long-running-agent'
                     : 'standard-long-running-agent';
-                if (explicitWorkspaceId !== undefined &&
-                    workspaceSelection?.workspaceId !== undefined &&
-                    explicitWorkspaceId !== workspaceSelection.workspaceId.trim()) {
-                    throw new Error('--workspace-id does not match the captured workspace identity.');
-                }
                 try {
                     sandbox = await deps.ensureCloudFleetSandbox({
                         workspaceId: relayWorkspaceId,
                         requiredCapability: `spawn:${cli}`,
                         maxAgents: 1,
                         mountRelayfile: mountSandboxRelayfile,
-                        ...(sandboxRelayfilePaths === undefined ? {} : { relayfilePaths: sandboxRelayfilePaths }),
+                        ...(liveRepository
+                            ? { relayfilePaths: liveRelayfileMountPaths(liveRepository, sandboxRelayfilePaths) }
+                            : sandboxRelayfilePaths === undefined
+                                ? {}
+                                : { relayfilePaths: sandboxRelayfilePaths }),
                         ...(sandboxId === undefined ? {} : { sandboxId }),
                         forceProvision: true,
                         ...(sandboxProvider === undefined ? {} : { providerId: sandboxProvider }),
                         workloadProfile,
                         waitTimeoutMs: 90_000,
                         ...(effectiveSandboxName === undefined ? {} : { name: effectiveSandboxName }),
+                        ...(checkoutRepository && sandboxRepository ? { repos: [sandboxRepository.repository] } : {}),
+                        ...(checkoutRepository && sandboxRepository
+                            ? { repoRevisions: { [sandboxRepository.repository]: sandboxRepository.revision } }
+                            : {}),
                     });
+                    assertSandboxRepositoryRevision(sandbox, checkoutRepository ? sandboxRepository : undefined);
                 }
                 catch (error) {
-                    if (error instanceof CloudFleetSandboxProvisionError &&
+                    if (shouldCleanupSandbox &&
+                        error instanceof CloudFleetSandboxProvisionError &&
                         error.confirmedProvisioned &&
                         error.cloudWorkspaceId &&
                         error.sandboxId) {
@@ -314,7 +477,8 @@ export function registerFleetCommands(program, overrides = {}) {
                     else if (error instanceof CloudFleetSandboxProvisionError && error.outcomeUnknown) {
                         deps.warn(`Cloud did not return a complete provisioning response. The outcome is unknown; check Cloud Fleet for node '${error.nodeName ?? effectiveSandboxName ?? 'the requested sandbox'}'${sandboxId === undefined ? '' : ` before retrying with --sandbox-id '${sandboxId}'`} so a sandbox is not left running.`);
                     }
-                    else if (error instanceof CloudFleetSandboxProvisionError &&
+                    else if (shouldCleanupSandbox &&
+                        error instanceof CloudFleetSandboxProvisionError &&
                         error.cloudWorkspaceId &&
                         error.sandboxId) {
                         await deps
@@ -327,6 +491,17 @@ export function registerFleetCommands(program, overrides = {}) {
                             deps.warn(`Provisioning failed after Cloud created sandbox '${error.sandboxId}', and automatic cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
                         });
                     }
+                    if (shouldCleanupSandbox && sandbox && sandbox.outcome !== 'reused') {
+                        await deps
+                            .deleteCloudFleetSandbox({
+                            cloudWorkspaceId: sandbox.cloudWorkspaceId,
+                            sandboxId: sandbox.sandboxId,
+                            ...(sandbox.providerId === undefined ? {} : { providerId: sandbox.providerId }),
+                        })
+                            .catch((cleanupError) => {
+                            deps.warn(`Sandbox repository verification failed and cleanup also failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+                        });
+                    }
                     throw error;
                 }
                 if (sandbox.outcome !== 'provisioning_timeout' && sandbox.relaycastTarget) {
@@ -347,7 +522,7 @@ export function registerFleetCommands(program, overrides = {}) {
                                 : 'Cloud returned a Relaycast target for a different workspace.');
                         }
                         relaycastClientOptions = {
-                            ...clientOptions,
+                            ...relaycastClientOptions,
                             workspaceKey: target.relaycastApiKey,
                             baseUrl: target.baseUrl,
                         };
@@ -364,7 +539,7 @@ export function registerFleetCommands(program, overrides = {}) {
                         }
                     }
                     catch (error) {
-                        if (sandbox.outcome === 'provisioned') {
+                        if (shouldCleanupSandbox && sandbox.outcome === 'provisioned') {
                             await deps
                                 .deleteCloudFleetSandbox({
                                 cloudWorkspaceId: sandbox.cloudWorkspaceId,
@@ -386,20 +561,22 @@ export function registerFleetCommands(program, overrides = {}) {
                     relaycastClientOptions = legacyWorkspaceClientOptions;
                 }
                 if (sandbox.outcome === 'provisioning_timeout') {
-                    await deps
-                        .deleteCloudFleetSandbox({
-                        cloudWorkspaceId: sandbox.cloudWorkspaceId,
-                        sandboxId: sandbox.sandboxId,
-                        ...(sandbox.providerId === undefined ? {} : { providerId: sandbox.providerId }),
-                    })
-                        .catch((error) => {
-                        deps.warn(`The timed-out sandbox could not be cleaned up automatically: ${error instanceof Error ? error.message : String(error)}`);
-                    });
+                    if (shouldCleanupSandbox) {
+                        await deps
+                            .deleteCloudFleetSandbox({
+                            cloudWorkspaceId: sandbox.cloudWorkspaceId,
+                            sandboxId: sandbox.sandboxId,
+                            ...(sandbox.providerId === undefined ? {} : { providerId: sandbox.providerId }),
+                        })
+                            .catch((error) => {
+                            deps.warn(`The timed-out sandbox could not be cleaned up automatically: ${error instanceof Error ? error.message : String(error)}`);
+                        });
+                    }
                     throw new Error(`Sandbox node '${sandbox.nodeName}' did not become ready within ${sandbox.waitedMs}ms.`);
                 }
                 if (mountSandboxRelayfile &&
                     (sandbox.outcome !== 'provisioned' || sandbox.relayfileMounted !== true)) {
-                    if (sandbox.outcome === 'provisioned') {
+                    if (shouldCleanupSandbox && sandbox.outcome === 'provisioned') {
                         await deps
                             .deleteCloudFleetSandbox({
                             cloudWorkspaceId: sandbox.cloudWorkspaceId,
@@ -413,6 +590,13 @@ export function registerFleetCommands(program, overrides = {}) {
                     throw new Error('Cloud returned a sandbox node without the required Relayfile mount.');
                 }
                 targetNode = sandbox.nodeName;
+                if (liveRepository &&
+                    sandboxRepository &&
+                    !workerCwd &&
+                    sandbox.outcome === 'provisioned' &&
+                    sandbox.relayfileMounted) {
+                    workerCwd = liveRelayfileWorkerCwd(sandbox.relayfileMountPath ?? '/workspace', liveRepository, sandboxRepository.repositoryRelativeCwd);
+                }
                 if (!workerCwd && sandbox.outcome === 'provisioned' && sandbox.relayfileMounted) {
                     workerCwd = sandbox.relayfileMountPath ?? '/workspace';
                 }
@@ -454,6 +638,9 @@ export function registerFleetCommands(program, overrides = {}) {
                     // the invocation and launches nothing, which is indistinguishable from
                     // success here — so wait for the node to confirm unless asked not to.
                     const confirm = options.confirm !== false;
+                    const liveSandboxContext = sandbox?.outcome === 'provisioned' && liveRepository && sandboxRepository
+                        ? `Agent Relay sandbox context: ${liveRepository.repository} is mounted as a live Relayfile working tree at ${liveRelayfileWorkerCwd(sandbox.relayfileMountPath ?? '/workspace', liveRepository, '')}. Its exact source revision is ${liveRepository.revision}; the same attestation is recorded at ${mountedRelayfilePath(sandbox.relayfileMountPath ?? '/workspace', liveRepository.sentinelPath)}. Workspace skills are under ${mountedRelayfilePath(sandbox.relayfileMountPath ?? '/workspace', '/.skills')}. The Relayfile daemon synchronizes this tree; it intentionally has no .git directory.`
+                        : undefined;
                     const invocation = await relay.messaging.placement.spawn({
                         capability: `spawn:${cli}`,
                         node: targetNode,
@@ -463,7 +650,15 @@ export function registerFleetCommands(program, overrides = {}) {
                         input: {
                             name,
                             cli,
-                            task,
+                            task: sandbox &&
+                                checkoutRepository &&
+                                sandboxRepository &&
+                                mountSandboxRelayfile &&
+                                sandbox.outcome === 'provisioned'
+                                ? `${task}\n\nAgent Relay sandbox context: Relayfile records are available at ${sandbox.relayfileMountPath ?? '/workspace'}. The source checkout is separate; use ${workerCwd ?? 'the worker checkout'} for repository files and the mount for Relayfile records.`
+                                : liveSandboxContext
+                                    ? `${task}\n\n${liveSandboxContext}`
+                                    : task,
                             ...(channel ? { channels: [channel] } : {}),
                             ...(model ? { model } : {}),
                             ...(workerCwd ? { worker_cwd: workerCwd } : {}),
@@ -485,19 +680,15 @@ export function registerFleetCommands(program, overrides = {}) {
                         ...(sandbox
                             ? {
                                 sandbox: printableSandbox,
-                                attachCommand: `agent-relay node agent attach ${shellQuote(name)} ` +
-                                    `--node ${shellQuote(targetNode)} --mode drive` +
-                                    ((sandbox.outcome === 'provisioned' || sandbox.outcome === 'reused') &&
-                                        sandbox.relaycastTarget
-                                        ? ` --base-url ${shellQuote(sandbox.relaycastTarget.baseUrl)}`
-                                        : ''),
+                                attachCommand: sandboxAttachCommand(name, attachProjectRoot),
                             }
                             : {}),
                         invocation: spawnInvocationWithMergedPlacement(invocation),
                     });
                 }
                 catch (error) {
-                    if (sandbox?.outcome === 'provisioned' &&
+                    if (shouldCleanupSandbox &&
+                        sandbox?.outcome === 'provisioned' &&
                         !(error instanceof RelayPlacementError && error.state === 'unconfirmed_may_be_running')) {
                         await deps
                             .deleteCloudFleetSandbox({
@@ -530,6 +721,31 @@ export function registerFleetCommands(program, overrides = {}) {
                 throw new Error('--session-ref requires --node or --target-node.');
             }
             const persona = optionalText(options.persona, 'Persona');
+            if (!automaticPlacement) {
+                if (organization || project || workstream || role || objective) {
+                    throw new Error('Workforce metadata requires --auto-place, --node, or --sandbox.');
+                }
+                const callerCwd = deps.cwd();
+                const localCwd = path.resolve(callerCwd, requestedCwd ?? '.');
+                const local = await deps.connectLocalBroker(deps.findProjectRoot(callerCwd));
+                try {
+                    await spawnAgentWithClient(local, {
+                        name,
+                        cli,
+                        task,
+                        channels: [channel ?? 'general'],
+                        ...(model ? { model } : {}),
+                        // A broker can be shared by nested packages. Never inherit its
+                        // startup directory when the caller requested a local checkout.
+                        cwd: localCwd,
+                    });
+                    printJson(deps.sdk, { local: { name, cli, cwd: localCwd } });
+                }
+                finally {
+                    local.disconnect();
+                }
+                return;
+            }
             const workspace = deps.createFleetWorkspaceClient(clientOptions);
             const invocation = await workspace.agents.spawn({
                 name,
@@ -635,6 +851,10 @@ function optionalTextList(value, label) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function sandboxAttachCommand(name, projectRoot) {
+    const attach = `agent-relay node agent attach ${shellQuote(name)} --mode drive`;
+    return projectRoot ? `cd ${shellQuote(projectRoot)} && ${attach}` : attach;
+}
 /**
  * Warn (on stderr, so it never pollutes the JSON on stdout) when the workspace
  * key was inferred from the project's persisted session rather than named