agent-relay 5.0.0 → 6.0.0

package/dist/src/cli/commands/on/start.js

@@ -10,6 +10,7 @@ import { launchOnMount } from '@relayfile/local-mount';
 import { mintToken } from './token.js';
 import { seedAclRules } from './workspace.js';
 import { seedWorkspace } from '../../../../packages/sdk/src/provisioner/seeder.js';
+import { createLocalJwks, exportPrivateKeyPem, RELAYAUTH_JWKS_URL_ENV, RELAYAUTH_JWT_KID_ENV, RELAYAUTH_JWT_PRIVATE_KEY_PEM_ENV, } from '../../../../packages/sdk/src/provisioner/local-jwks.js';
 import { ensureAuthenticated, readStoredAuth } from '@agent-relay/cloud';
 const DEFAULT_SEED_EXCLUDES = ['.relay', '.git', 'node_modules'];
 const DEFAULT_RELAYCAST_BASE_URL = 'https://api.relaycast.dev';
@@ -279,13 +280,13 @@ async function createRelaycastWorkspace(fetchFn, baseUrl, workspaceName) {
 async function requestLocalWorkspaceSession(options) {
     const fetchFn = options.fetchFn ?? fetch;
     const relayDir = options.relayDir;
-    const signingSecret = toString(options.signingSecret);
+    const tokenSigningKey = options.tokenSigningKey;
     const requestedWorkspaceId = normalizeWorkspaceId(options.requestedWorkspaceId);
     if (!relayDir) {
         throw new Error('relayDir is required for local workspace sessions');
     }
-    if (!signingSecret) {
-        throw new Error('signingSecret is required for local workspace sessions');
+    if (!tokenSigningKey) {
+        throw new Error('tokenSigningKey is required for local workspace sessions');
     }
     const workspaceId = requestedWorkspaceId ?? generateWorkspaceId();
     const existing = readWorkspaceRegistry(relayDir)[workspaceId];
@@ -315,7 +316,8 @@ async function requestLocalWorkspaceSession(options) {
         created: !requestedWorkspaceId,
         workspaceId,
         token: mintToken({
-            secret: signingSecret,
+            privateKey: tokenSigningKey.privateKey,
+            kid: tokenSigningKey.kid,
             agentName: options.agentName,
             workspace: workspaceId,
             scopes: options.scopes,
@@ -330,7 +332,7 @@ export async function requestWorkspaceSession(options) {
     const requestedWorkspaceId = normalizeWorkspaceId(options.requestedWorkspaceId);
     if ((isLocalBaseUrl(options.authBase) || options.preferLocalSession) &&
         options.relayDir &&
-        options.signingSecret) {
+        options.tokenSigningKey) {
         return requestLocalWorkspaceSession({ ...options, fetchFn, requestedWorkspaceId });
     }
     if (requestedWorkspaceId) {
@@ -418,10 +420,6 @@ function loadConfigFromFile(configPath, projectDir) {
     const fallbackWorkspace = path.basename(projectDir);
     const workspace = toString(payload.workspace, toString(root.workspace, fallbackWorkspace));
     const signing_secret = toString(payload.signing_secret, toString(root.signing_secret, process.env.SIGNING_KEY ?? ''));
-    if (!signing_secret) {
-        throw new Error(`relay config at ${configPath} is missing signing_secret and SIGNING_KEY env var is not set. ` +
-            'Set signing_secret in your config or export SIGNING_KEY.');
-    }
     const agents = normalizeAgents(payload.agents ?? root.agents);
     return { workspace, signing_secret, agents };
 }
@@ -730,10 +728,11 @@ function pickDeniedCount(syncOutput) {
     const match = syncOutput.match(/skipping denied file/gi);
     return match ? match.length : 0;
 }
-function generateTokenFromScript(config, agent, log, error) {
+function generateTokenFromScript(config, agent, tokenSigningKey, log, error) {
     try {
         return mintToken({
-            secret: config.signing_secret,
+            privateKey: tokenSigningKey.privateKey,
+            kid: tokenSigningKey.kid,
             agentName: agent.name,
             workspace: config.workspace,
             scopes: agent.scopes,
@@ -789,7 +788,7 @@ function getSandboxFlags(cli) {
             return [];
     }
 }
-async function ensureProvisioned(config, agent, relayfileRoot, projectDir, tokenPath, log, error, deps) {
+async function ensureProvisioned(config, agent, tokenSigningKey, relayfileRoot, projectDir, tokenPath, log, error, deps) {
     try {
         return readFileSync(tokenPath, 'utf8').trim();
     }
@@ -797,7 +796,7 @@ async function ensureProvisioned(config, agent, relayfileRoot, projectDir, token
         // Token file does not exist yet — continue to provision
     }
     if (typeof deps?.provision === 'function') {
-        await deps.provision(config, { ...agent });
+        await deps.provision(config, { ...agent }, tokenSigningKey);
         try {
             return readFileSync(tokenPath, 'utf8').trim();
         }
@@ -806,14 +805,14 @@ async function ensureProvisioned(config, agent, relayfileRoot, projectDir, token
         }
     }
     if (typeof deps?.provisionAgentToken === 'function') {
-        const generated = await deps.provisionAgentToken({ config, agent, tokenPath });
+        const generated = await deps.provisionAgentToken({ config, agent, tokenPath, tokenSigningKey });
         if (typeof generated === 'string' && generated.trim()) {
             const generatedToken = generated.trim();
             writeFileSync(tokenPath, `${generatedToken}\n`, { encoding: 'utf8', mode: 0o600 });
             return generatedToken;
         }
     }
-    const generatedToken = generateTokenFromScript(config, agent, log, error);
+    const generatedToken = generateTokenFromScript(config, agent, tokenSigningKey, log, error);
     if (generatedToken) {
         ensureDirectory(path.dirname(tokenPath));
         writeFileSync(tokenPath, `${generatedToken}\n`, { encoding: 'utf8', mode: 0o600 });
@@ -821,7 +820,7 @@ async function ensureProvisioned(config, agent, relayfileRoot, projectDir, token
     }
     throw new Error(`missing token for ${agent.name}: ${tokenPath}. Run provisioning before launching relay.`);
 }
-async function ensureServices(authBase, fileBase, deps, log, error) {
+async function ensureServices(authBase, fileBase, jwksUrl, deps, log, error) {
     const needsLocalAuth = isLocalBaseUrl(authBase);
     const needsLocalFile = isLocalBaseUrl(fileBase);
     if (!needsLocalAuth && !needsLocalFile) {
@@ -832,14 +831,14 @@ async function ensureServices(authBase, fileBase, deps, log, error) {
     if (authHealthy && fileHealthy)
         return;
     if (typeof deps?.ensureServicesRunning === 'function') {
-        await deps.ensureServicesRunning(authBase, fileBase);
+        await deps.ensureServicesRunning(authBase, fileBase, jwksUrl);
         const postAuthHealthy = !needsLocalAuth || (await waitForHttpHealthy(authBase));
         const postFileHealthy = !needsLocalFile || (await waitForHttpHealthy(fileBase));
         if (postAuthHealthy && postFileHealthy)
             return;
     }
     if (typeof deps?.startServices === 'function') {
-        await deps.startServices({ authBase, fileBase });
+        await deps.startServices({ authBase, fileBase, jwksUrl });
         const postAuthHealthy = !needsLocalAuth || (await waitForHttpHealthy(authBase));
         const postFileHealthy = !needsLocalFile || (await waitForHttpHealthy(fileBase));
         if (postAuthHealthy && postFileHealthy)
@@ -887,297 +886,311 @@ export async function goOnTheRelay(cli, options, extraArgs, deps = {}) {
     if (!isCommandAvailable('node') || !isCommandAvailable('npx')) {
         throw new Error('node and npx must be available in PATH to run relay.');
     }
-    ensureStateDirs(relayDir);
-    const defaultAgentName = toString(options.agent, path.basename(cli));
-    const config = resolveConfig(projectDir, relayDir, defaultAgentName);
-    const agent = findAgentConfig(config, defaultAgentName);
-    const authBase = normalizeBaseUrl(options.cloud && options.url ? options.url : options.portAuth);
-    const fileBase = normalizeBaseUrl(options.portFile);
-    // Default: solo local (symlink mount). --shared or --cloud: use relayfile.
-    const useSymlinkMount = !options.shared && !options.cloud;
-    await ensureServices(authBase, fileBase, deps, log, error);
-    const workspaceSession = await requestWorkspaceSession({
-        authBase,
-        fallbackRelayfileUrl: fileBase,
-        requestedWorkspaceId: options.workspace,
-        workspaceName: config.workspace,
-        agentName: agent.name,
-        scopes: agent.scopes,
-        signingSecret: config.signing_secret,
-        relayDir,
-        relaycastBaseUrl: process.env.RELAYCAST_BASE_URL,
-        fetchFn: deps.fetch,
-        preferLocalSession: useSymlinkMount,
-    });
-    // Compile dotfile permissions for this agent
-    const hasDots = hasDotfiles(projectDir);
-    const dotfileAcl = hasDots ? compileDotfiles(projectDir, agent.name, workspaceSession.workspaceId) : null;
-    const compiledPath = path.join(relayDir, 'compiled-acl.json');
-    const compiled = extractPermissionPatternsFromCompiled(compiledPath, agent.name);
-    const fallback = collectPermissionPatternsFromDotfiles(projectDir);
-    const readonlyPatterns = compiled.readonlyPatterns.length > 0 ? compiled.readonlyPatterns : fallback.readonlyPatterns;
-    const ignoredPatterns = compiled.ignoredPatterns.length > 0 ? compiled.ignoredPatterns : fallback.ignoredPatterns;
-    const permsDoc = buildPermissionDoc(agent.name, readonlyPatterns, ignoredPatterns);
-    const seedExcludes = [...DEFAULT_SEED_EXCLUDES];
-    if (dotfileAcl) {
-        for (const [dir, rules] of Object.entries(dotfileAcl.acl)) {
-            if (rules.some((r) => r.startsWith('deny:agent:'))) {
-                seedExcludes.push(dir.replace(/^\//, ''));
-            }
-        }
-    }
-    const mountDirName = `workspace-${sanitizePathComponent(workspaceSession.workspaceId)}-${sanitizePathComponent(agent.name)}`;
-    // Symlink mounts live under ~/.agent-relay/mounts/ (outside the project tree).
-    // @relayfile/local-mount refuses any mountDir that overlaps projectDir as a
-    // safety check against destroying the project on cleanup, and putting mounts
-    // in $HOME keeps them durable across reboots (unlike $TMPDIR) and scoped to
-    // the user, consistent with ~/.agent-workforce/. The FUSE path keeps the
-    // historical in-project location under .relay/ — it's managed by the
-    // relayfile-mount Go binary, not @relayfile/local-mount, so the overlap
-    // guard doesn't apply.
-    const mountDir = useSymlinkMount
-        ? path.join(os.homedir(), '.agent-relay', 'mounts', mountDirName)
-        : path.join(relayDir, mountDirName);
-    const sandboxFlags = getSandboxFlags(cli);
-    const buildAgentEnv = () => ({
-        RELAY_AGENT_TOKEN: workspaceSession.token,
-        RELAYFILE_TOKEN: workspaceSession.token,
-        RELAYFILE_BASE_URL: workspaceSession.relayfileUrl,
-        RELAYFILE_WORKSPACE: workspaceSession.workspaceId,
-        RELAY_WORKSPACE_ID: workspaceSession.workspaceId,
-        RELAY_DEFAULT_WORKSPACE: workspaceSession.workspaceId,
-        RELAY_WORKSPACE: mountDir,
-        RELAY_AGENT_NAME: agent.name,
-        ...(workspaceSession.relaycastApiKey
-            ? {
-                RELAY_API_KEY: workspaceSession.relaycastApiKey,
-                RELAY_WORKSPACES_JSON: JSON.stringify([
-                    {
-                        workspace_id: workspaceSession.workspaceId,
-                        api_key: workspaceSession.relaycastApiKey,
-                    },
-                ]),
-            }
-            : {}),
-    });
-    if (useSymlinkMount) {
-        log(`Preparing local workspace at ${mountDir}...`);
-        const agentArgs = [...sandboxFlags, ...extraArgs];
-        // Extend ignoredPatterns with `_PERMISSIONS.md` so @relayfile/local-mount's
-        // syncBack() does not copy the permissions doc we write in onBeforeLaunch
-        // into the user's project directory (the library only hides its own
-        // _MOUNT_README.md / .relayfile-local-mount marker from sync-back).
-        const launchIgnoredPatterns = [...ignoredPatterns, '_PERMISSIONS.md'];
-        // Ensure `.relay` is excluded from the mount — @relayfile/local-mount no
-        // longer has it in the default excludeDirs list, and seedExcludes already
-        // includes it for symlink + cloud paths.
-        const launchResult = await launchOnMount({
-            cli,
-            projectDir,
-            mountDir,
-            args: agentArgs,
-            ignoredPatterns: launchIgnoredPatterns,
-            readonlyPatterns,
-            excludeDirs: seedExcludes,
-            env: { ...process.env, ...buildAgentEnv() },
+    const localJwks = await createLocalJwks();
+    try {
+        const privateKeyPem = exportPrivateKeyPem(localJwks.privateKey);
+        ensureStateDirs(relayDir);
+        const defaultAgentName = toString(options.agent, path.basename(cli));
+        const config = resolveConfig(projectDir, relayDir, defaultAgentName);
+        const agent = findAgentConfig(config, defaultAgentName);
+        const authBase = normalizeBaseUrl(options.cloud && options.url ? options.url : options.portAuth);
+        const fileBase = normalizeBaseUrl(options.portFile);
+        // Default: solo local (symlink mount). --shared or --cloud: use relayfile.
+        const useSymlinkMount = !options.shared && !options.cloud;
+        await ensureServices(authBase, fileBase, localJwks.jwksUrl, deps, log, error);
+        const workspaceSession = await requestWorkspaceSession({
+            authBase,
+            fallbackRelayfileUrl: fileBase,
+            requestedWorkspaceId: options.workspace,
+            workspaceName: config.workspace,
             agentName: agent.name,
-            onBeforeLaunch: (realMountDir) => {
-                // Write the richer agent-relay permissions doc. This coexists with the
-                // generic _MOUNT_README.md that @relayfile/local-mount writes itself.
-                writeFileSync(path.join(realMountDir, '_PERMISSIONS.md'), permsDoc, 'utf8');
-                const mountedFiles = countFilesForSync(realMountDir);
-                log(`On the relay as ${agent.name}`);
-                log(`  Workspace: ${workspaceSession.workspaceId}`);
-                log(`  Join: ${workspaceSession.joinCommand}`);
-                log(`  Mounted files: ${mountedFiles}`);
-                log(`  Permissions denied (initial sync): 0`);
-                if (sandboxFlags.length > 0) {
-                    log(`  Sandbox: relay-enforced (${sandboxFlags.join(' ')})`);
-                    log(`  ⚠ Agent CLI sandbox bypassed — relay file permissions are the only safety layer`);
-                }
-            },
-            onAfterSync: (synced) => {
-                log(`  ✓ ${synced} file(s) synced back`);
-                log(`Cleaned relay mount for ${agent.name}`);
-            },
+            scopes: agent.scopes,
+            tokenSigningKey: localJwks,
+            relayDir,
+            relaycastBaseUrl: process.env.RELAYCAST_BASE_URL,
+            fetchFn: deps.fetch,
+            preferLocalSession: useSymlinkMount,
         });
-        log('Off the relay.');
-        exit(launchResult.exitCode);
-        return;
-    }
-    // Cloud / --shared path: use the relayfile-mount FUSE binary.
-    const mountBin = process.env.RELAYFILE_ROOT
-        ? path.join(process.env.RELAYFILE_ROOT, 'bin', 'relayfile-mount')
-        : await ensureRelayfileMountBinary();
-    if (!existsSync(mountBin)) {
-        throw new Error(`missing relayfile mount binary: ${mountBin}`);
-    }
-    if (workspaceSession.created) {
-        await seedWorkspace(workspaceSession.relayfileUrl, workspaceSession.token, workspaceSession.workspaceId, projectDir, seedExcludes);
-        if (dotfileAcl && Object.keys(dotfileAcl.acl).length > 0) {
-            await seedAclRules(workspaceSession.relayfileUrl, workspaceSession.token, workspaceSession.workspaceId, dotfileAcl.acl);
-            writeFileSync(compiledPath, JSON.stringify({
-                workspace: workspaceSession.workspaceId,
-                acl: dotfileAcl.acl,
-                summary: dotfileAcl.summary,
-                agents: [{ name: agent.name, summary: dotfileAcl.summary }],
-            }, null, 2) + '\n', { encoding: 'utf8' });
+        // Compile dotfile permissions for this agent
+        const hasDots = hasDotfiles(projectDir);
+        const dotfileAcl = hasDots ? compileDotfiles(projectDir, agent.name, workspaceSession.workspaceId) : null;
+        const compiledPath = path.join(relayDir, 'compiled-acl.json');
+        const compiled = extractPermissionPatternsFromCompiled(compiledPath, agent.name);
+        const fallback = collectPermissionPatternsFromDotfiles(projectDir);
+        const readonlyPatterns = compiled.readonlyPatterns.length > 0 ? compiled.readonlyPatterns : fallback.readonlyPatterns;
+        const ignoredPatterns = compiled.ignoredPatterns.length > 0 ? compiled.ignoredPatterns : fallback.ignoredPatterns;
+        const permsDoc = buildPermissionDoc(agent.name, readonlyPatterns, ignoredPatterns);
+        const seedExcludes = [...DEFAULT_SEED_EXCLUDES];
+        if (dotfileAcl) {
+            for (const [dir, rules] of Object.entries(dotfileAcl.acl)) {
+                if (rules.some((r) => r.startsWith('deny:agent:'))) {
+                    seedExcludes.push(dir.replace(/^\//, ''));
+                }
+            }
         }
-    }
-    mkdirSync(mountDir, { recursive: true });
-    const mountLogPath = path.join(relayDir, 'logs', `${agent.name}-mount.log`);
-    writeFileSync(mountLogPath, '', 'utf8');
-    const mountBaseArgs = [
-        '--base-url',
-        workspaceSession.relayfileUrl,
-        '--workspace',
-        workspaceSession.workspaceId,
-        '--local-dir',
-        mountDir,
-    ];
-    const onceArgs = [...mountBaseArgs, '--once'];
-    const mountEnv = { ...process.env, RELAYFILE_TOKEN: workspaceSession.token };
-    log(`Mounting workspace at ${mountDir}...`);
-    let initialSyncOutput = '';
-    try {
-        initialSyncOutput = await runCommandCapture(mountBin, onceArgs, mountEnv);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`initial workspace sync failed for ${agent.name}: ${message}`);
-    }
-    const deniedCount = pickDeniedCount(initialSyncOutput);
-    writeFileSync(path.join(mountDir, '_PERMISSIONS.md'), permsDoc, 'utf8');
-    const projectDeny = path.join(projectDir, '.agentdeny');
-    if (existsSync(projectDeny)) {
-        cpSync(projectDeny, path.join(mountDir, '.agentdeny'), { force: true });
-    }
-    const mountedFiles = countFilesForSync(mountDir);
-    log(`On the relay as ${agent.name}`);
-    log(`  Workspace: ${workspaceSession.workspaceId}`);
-    log(`  Join: ${workspaceSession.joinCommand}`);
-    log(`  Mounted files: ${mountedFiles}`);
-    log(`  Permissions denied (initial sync): ${deniedCount}`);
-    if (sandboxFlags.length > 0) {
-        log(`  Sandbox: relay-enforced (${sandboxFlags.join(' ')})`);
-        log(`  ⚠ Agent CLI sandbox bypassed — relay file permissions are the only safety layer`);
-    }
-    const cleanupState = {
-        mountDir,
-        mountLogPath,
-        projectDir,
-        relayDir,
-        workspace: workspaceSession.workspaceId,
-        readonlyPatterns,
-        ignoredPatterns,
-    };
-    let mountProc;
-    let agentProc;
-    let cleanupDone = false;
-    const finalizeCleanup = async () => {
-        if (cleanupDone)
-            return;
-        cleanupDone = true;
-        cleanupState.mountProc = mountProc;
-        await cleanupRun(cleanupState, agent.name, log);
-    };
-    try {
-        const mountedProc = spawn(mountBin, mountBaseArgs, {
-            stdio: ['pipe', 'pipe', 'pipe'],
-            env: mountEnv,
-        });
-        mountProc = mountedProc;
-        mountedProc.stdout.on('data', (chunk) => {
-            appendFileSync(mountLogPath, chunk);
-        });
-        mountedProc.stderr.on('data', (chunk) => {
-            appendFileSync(mountLogPath, chunk);
+        const mountDirName = `workspace-${sanitizePathComponent(workspaceSession.workspaceId)}-${sanitizePathComponent(agent.name)}`;
+        // Symlink mounts live under ~/.agent-relay/mounts/ (outside the project tree).
+        // @relayfile/local-mount refuses any mountDir that overlaps projectDir as a
+        // safety check against destroying the project on cleanup, and putting mounts
+        // in $HOME keeps them durable across reboots (unlike $TMPDIR) and scoped to
+        // the user, consistent with ~/.agent-workforce/. The FUSE path keeps the
+        // historical in-project location under .relay/ — it's managed by the
+        // relayfile-mount Go binary, not @relayfile/local-mount, so the overlap
+        // guard doesn't apply.
+        const mountDir = useSymlinkMount
+            ? path.join(os.homedir(), '.agent-relay', 'mounts', mountDirName)
+            : path.join(relayDir, mountDirName);
+        const sandboxFlags = getSandboxFlags(cli);
+        const buildAgentEnv = () => ({
+            RELAY_AGENT_TOKEN: workspaceSession.token,
+            RELAYFILE_TOKEN: workspaceSession.token,
+            RELAYFILE_BASE_URL: workspaceSession.relayfileUrl,
+            RELAYFILE_WORKSPACE: workspaceSession.workspaceId,
+            [RELAYAUTH_JWKS_URL_ENV]: localJwks.jwksUrl,
+            [RELAYAUTH_JWT_PRIVATE_KEY_PEM_ENV]: privateKeyPem,
+            [RELAYAUTH_JWT_KID_ENV]: localJwks.kid,
+            RELAY_WORKSPACE_ID: workspaceSession.workspaceId,
+            RELAY_DEFAULT_WORKSPACE: workspaceSession.workspaceId,
+            RELAY_WORKSPACE: mountDir,
+            RELAY_AGENT_NAME: agent.name,
+            ...(workspaceSession.relaycastApiKey
+                ? {
+                    RELAY_API_KEY: workspaceSession.relaycastApiKey,
+                    RELAY_WORKSPACES_JSON: JSON.stringify([
+                        {
+                            workspace_id: workspaceSession.workspaceId,
+                            api_key: workspaceSession.relaycastApiKey,
+                        },
+                    ]),
+                }
+                : {}),
         });
-        await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => resolve(), 600);
-            mountedProc.on('error', (spawnError) => {
-                clearTimeout(timer);
-                reject(spawnError);
-            });
-            mountedProc.on('spawn', () => {
-                clearTimeout(timer);
-                resolve();
+        if (useSymlinkMount) {
+            log(`Preparing local workspace at ${mountDir}...`);
+            const agentArgs = [...sandboxFlags, ...extraArgs];
+            // Extend ignoredPatterns with `_PERMISSIONS.md` so @relayfile/local-mount's
+            // syncBack() does not copy the permissions doc we write in onBeforeLaunch
+            // into the user's project directory (the library only hides its own
+            // _MOUNT_README.md / .relayfile-local-mount marker from sync-back).
+            const launchIgnoredPatterns = [...ignoredPatterns, '_PERMISSIONS.md'];
+            // Ensure `.relay` is excluded from the mount — @relayfile/local-mount no
+            // longer has it in the default excludeDirs list, and seedExcludes already
+            // includes it for symlink + cloud paths.
+            const launchResult = await launchOnMount({
+                cli,
+                projectDir,
+                mountDir,
+                args: agentArgs,
+                ignoredPatterns: launchIgnoredPatterns,
+                readonlyPatterns,
+                excludeDirs: seedExcludes,
+                env: { ...process.env, ...buildAgentEnv() },
+                agentName: agent.name,
+                onBeforeLaunch: (realMountDir) => {
+                    // Write the richer agent-relay permissions doc. This coexists with the
+                    // generic _MOUNT_README.md that @relayfile/local-mount writes itself.
+                    writeFileSync(path.join(realMountDir, '_PERMISSIONS.md'), permsDoc, 'utf8');
+                    const mountedFiles = countFilesForSync(realMountDir);
+                    log(`On the relay as ${agent.name}`);
+                    log(`  Workspace: ${workspaceSession.workspaceId}`);
+                    log(`  Join: ${workspaceSession.joinCommand}`);
+                    log(`  Mounted files: ${mountedFiles}`);
+                    log(`  Permissions denied (initial sync): 0`);
+                    if (sandboxFlags.length > 0) {
+                        log(`  Sandbox: relay-enforced (${sandboxFlags.join(' ')})`);
+                        log(`  ⚠ Agent CLI sandbox bypassed — relay file permissions are the only safety layer`);
+                    }
+                },
+                onAfterSync: (synced) => {
+                    log(`  ✓ ${synced} file(s) synced back`);
+                    log(`Cleaned relay mount for ${agent.name}`);
+                },
             });
-        });
-        if (!ensureProcessRunning(mountedProc)) {
-            throw new Error(`mount process for ${agent.name} exited before continuing`);
+            log('Off the relay.');
+            exit(launchResult.exitCode);
+            return;
         }
-        cleanupState.mountProc = mountProc;
-        let agentExitCode = 0;
-        await new Promise((resolve, reject) => {
-            const envVars = {
-                ...process.env,
-                ...buildAgentEnv(),
-            };
-            agentProc = spawn(cli, [...sandboxFlags, ...extraArgs], {
-                cwd: mountDir,
-                stdio: 'inherit',
-                env: envVars,
+        // Cloud / --shared path: use the relayfile-mount FUSE binary.
+        const mountBin = process.env.RELAYFILE_ROOT
+            ? path.join(process.env.RELAYFILE_ROOT, 'bin', 'relayfile-mount')
+            : await ensureRelayfileMountBinary();
+        if (!existsSync(mountBin)) {
+            throw new Error(`missing relayfile mount binary: ${mountBin}`);
+        }
+        if (workspaceSession.created) {
+            await seedWorkspace(workspaceSession.relayfileUrl, workspaceSession.token, workspaceSession.workspaceId, projectDir, seedExcludes);
+            if (dotfileAcl && Object.keys(dotfileAcl.acl).length > 0) {
+                await seedAclRules(workspaceSession.relayfileUrl, workspaceSession.token, workspaceSession.workspaceId, dotfileAcl.acl);
+                writeFileSync(compiledPath, JSON.stringify({
+                    workspace: workspaceSession.workspaceId,
+                    acl: dotfileAcl.acl,
+                    summary: dotfileAcl.summary,
+                    agents: [{ name: agent.name, summary: dotfileAcl.summary }],
+                }, null, 2) + '\n', { encoding: 'utf8' });
+            }
+        }
+        mkdirSync(mountDir, { recursive: true });
+        const mountLogPath = path.join(relayDir, 'logs', `${agent.name}-mount.log`);
+        writeFileSync(mountLogPath, '', 'utf8');
+        const mountBaseArgs = [
+            '--base-url',
+            workspaceSession.relayfileUrl,
+            '--workspace',
+            workspaceSession.workspaceId,
+            '--local-dir',
+            mountDir,
+        ];
+        const onceArgs = [...mountBaseArgs, '--once'];
+        const mountEnv = {
+            ...process.env,
+            RELAYFILE_TOKEN: workspaceSession.token,
+            [RELAYAUTH_JWKS_URL_ENV]: localJwks.jwksUrl,
+        };
+        log(`Mounting workspace at ${mountDir}...`);
+        let initialSyncOutput = '';
+        try {
+            initialSyncOutput = await runCommandCapture(mountBin, onceArgs, mountEnv);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`initial workspace sync failed for ${agent.name}: ${message}`);
+        }
+        const deniedCount = pickDeniedCount(initialSyncOutput);
+        writeFileSync(path.join(mountDir, '_PERMISSIONS.md'), permsDoc, 'utf8');
+        const projectDeny = path.join(projectDir, '.agentdeny');
+        if (existsSync(projectDeny)) {
+            cpSync(projectDeny, path.join(mountDir, '.agentdeny'), { force: true });
+        }
+        const mountedFiles = countFilesForSync(mountDir);
+        log(`On the relay as ${agent.name}`);
+        log(`  Workspace: ${workspaceSession.workspaceId}`);
+        log(`  Join: ${workspaceSession.joinCommand}`);
+        log(`  Mounted files: ${mountedFiles}`);
+        log(`  Permissions denied (initial sync): ${deniedCount}`);
+        if (sandboxFlags.length > 0) {
+            log(`  Sandbox: relay-enforced (${sandboxFlags.join(' ')})`);
+            log(`  ⚠ Agent CLI sandbox bypassed — relay file permissions are the only safety layer`);
+        }
+        const cleanupState = {
+            mountDir,
+            mountLogPath,
+            projectDir,
+            relayDir,
+            workspace: workspaceSession.workspaceId,
+            readonlyPatterns,
+            ignoredPatterns,
+        };
+        let mountProc;
+        let agentProc;
+        let cleanupDone = false;
+        const finalizeCleanup = async () => {
+            if (cleanupDone)
+                return;
+            cleanupDone = true;
+            cleanupState.mountProc = mountProc;
+            await cleanupRun(cleanupState, agent.name, log);
+        };
+        try {
+            const mountedProc = spawn(mountBin, mountBaseArgs, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: mountEnv,
             });
-            let cleanupInProgress;
-            const cleanupHook = () => {
-                if (agentProc && !agentProc.killed) {
-                    agentProc.kill('SIGTERM');
-                }
-                // Wait for the agent process to exit so agentExitCode is set by the close handler,
-                // then ensure cleanup completes before resolving — avoids data loss from premature exit
-                cleanupInProgress = new Promise((r) => {
-                    if (!agentProc || agentProc.exitCode !== null) {
-                        r();
-                        return;
-                    }
-                    const t = setTimeout(r, 2000);
-                    agentProc.once('close', () => {
-                        clearTimeout(t);
-                        r();
-                    });
-                })
-                    .then(() => finalizeCleanup())
-                    .then(() => resolve());
-            };
-            process.once('SIGINT', cleanupHook);
-            process.once('SIGTERM', cleanupHook);
-            agentProc.on('error', (err) => {
-                process.removeListener('SIGINT', cleanupHook);
-                process.removeListener('SIGTERM', cleanupHook);
-                reject(err);
+            mountProc = mountedProc;
+            mountedProc.stdout.on('data', (chunk) => {
+                appendFileSync(mountLogPath, chunk);
             });
-            agentProc.on('close', (code, signal) => {
-                process.removeListener('SIGINT', cleanupHook);
-                process.removeListener('SIGTERM', cleanupHook);
-                if (typeof code === 'number') {
-                    agentExitCode = code;
-                }
-                else if (signal === 'SIGINT') {
-                    agentExitCode = 130;
-                }
-                else if (signal === 'SIGTERM') {
-                    agentExitCode = 143;
-                }
-                else {
-                    agentExitCode = 1;
-                }
-                // If cleanup was triggered by a signal, wait for it to finish
-                if (cleanupInProgress) {
-                    cleanupInProgress.then(() => resolve());
-                }
-                else {
+            mountedProc.stderr.on('data', (chunk) => {
+                appendFileSync(mountLogPath, chunk);
+            });
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => resolve(), 600);
+                mountedProc.on('error', (spawnError) => {
+                    clearTimeout(timer);
+                    reject(spawnError);
+                });
+                mountedProc.on('spawn', () => {
+                    clearTimeout(timer);
                     resolve();
-                }
+                });
             });
-            // Finalization happens in outer finally.
-        });
-        await finalizeCleanup();
-        log('Off the relay.');
-        exit(agentExitCode);
+            if (!ensureProcessRunning(mountedProc)) {
+                throw new Error(`mount process for ${agent.name} exited before continuing`);
+            }
+            cleanupState.mountProc = mountProc;
+            let agentExitCode = 0;
+            await new Promise((resolve, reject) => {
+                const envVars = {
+                    ...process.env,
+                    ...buildAgentEnv(),
+                };
+                agentProc = spawn(cli, [...sandboxFlags, ...extraArgs], {
+                    cwd: mountDir,
+                    stdio: 'inherit',
+                    env: envVars,
+                });
+                let cleanupInProgress;
+                const cleanupHook = () => {
+                    if (agentProc && !agentProc.killed) {
+                        agentProc.kill('SIGTERM');
+                    }
+                    // Wait for the agent process to exit so agentExitCode is set by the close handler,
+                    // then ensure cleanup completes before resolving — avoids data loss from premature exit
+                    cleanupInProgress = new Promise((r) => {
+                        if (!agentProc || agentProc.exitCode !== null) {
+                            r();
+                            return;
+                        }
+                        const t = setTimeout(r, 2000);
+                        agentProc.once('close', () => {
+                            clearTimeout(t);
+                            r();
+                        });
+                    })
+                        .then(() => finalizeCleanup())
+                        .then(() => resolve());
+                };
+                process.once('SIGINT', cleanupHook);
+                process.once('SIGTERM', cleanupHook);
+                agentProc.on('error', (err) => {
+                    process.removeListener('SIGINT', cleanupHook);
+                    process.removeListener('SIGTERM', cleanupHook);
+                    reject(err);
+                });
+                agentProc.on('close', (code, signal) => {
+                    process.removeListener('SIGINT', cleanupHook);
+                    process.removeListener('SIGTERM', cleanupHook);
+                    if (typeof code === 'number') {
+                        agentExitCode = code;
+                    }
+                    else if (signal === 'SIGINT') {
+                        agentExitCode = 130;
+                    }
+                    else if (signal === 'SIGTERM') {
+                        agentExitCode = 143;
+                    }
+                    else {
+                        agentExitCode = 1;
+                    }
+                    // If cleanup was triggered by a signal, wait for it to finish
+                    if (cleanupInProgress) {
+                        cleanupInProgress.then(() => resolve());
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+                // Finalization happens in outer finally.
+            });
+            await finalizeCleanup();
+            log('Off the relay.');
+            exit(agentExitCode);
+        }
+        finally {
+            await finalizeCleanup();
+        }
     }
     finally {
-        await finalizeCleanup();
+        await localJwks.shutdown();
     }
 }
 //# sourceMappingURL=start.js.map