@myagentroam/node 0.10.66 → 0.10.68

package/dist/connector.js

@@ -7,6 +7,7 @@ import { createEnvelope, directNodeCommandSchema } from '@myagentroam/protocol';
 import { loadNodeConfig, computerUseRuntimeExecutable, directTransferUdpPortRange, nodeDataDirectory, nodeDatabasePath } from './config.js';
 import { NodeMetrics, nodeLog } from './operational.js';
 import { assertLocalSqlitePath } from './storage.js';
+import { resolveWorkspaceExecutionDirectory } from './workspace.js';
 import { detectCapabilitiesAsync, unavailableCapabilities } from './capabilities.js';
 import { NodeDatabase } from './database.js';
 import { TerminalManager } from './terminal.js';
@@ -734,7 +735,17 @@ export class NodeConnector {
             discover: (runner, workspaceId) => this.nativeSessionProjectionService.discover(runner, workspaceId),
             workspaceIdForCwd: (cwd) => this.database?.listWorkspaces().find((candidate) => candidate.path === cwd)?.id
         });
+        const resolveExecutionDirectory = async (session) => {
+            const workspace = this.database?.getWorkspace(session.workspaceId);
+            if (workspace === undefined)
+                throw new Error('WORKSPACE_NOT_FOUND');
+            const directory = await resolveWorkspaceExecutionDirectory(workspace.path, session.cwd);
+            if (this.database?.getWorkspace(workspace.id)?.path !== workspace.path)
+                throw new Error('WORKSPACE_NOT_FOUND');
+            return directory;
+        };
         this.continuousRunCoordinator = new ContinuousRunCoordinator({
+            resolveExecutionDirectory,
             runtime: this.runtime,
             steer: (prepared, item, executionId) => {
                 const runner = this.runners.optional(prepared.runner);
@@ -868,6 +879,7 @@ export class NodeConnector {
                         : { runnerTitle: session.runnerTitle.slice(0, 160) })
                 });
             },
+            validateCommands: (previousId, nextId) => this.commandStates.validateSessionIdentityPromotion(previousId, nextId),
             migrateCommands: (previousId, nextId) => this.commandStates.promoteSessionIdentity(previousId, nextId),
             migrateGoal: (previousId, nextId) => {
                 this.runAttachmentService.migrateSession(previousId, nextId);
@@ -905,6 +917,7 @@ export class NodeConnector {
             interceptedSessionId: (clientMessageId) => this.fakeRunner === undefined ? undefined : `fake:${clientMessageId}`
         });
         this.externalSessionResumeService = new ExternalSessionResumeService({
+            resolveExecutionDirectory,
             runtime: this.runtime,
             runners: this.runners,
             state: this.sessionState,
@@ -939,6 +952,7 @@ export class NodeConnector {
             clearGoal: (session) => this.goalCoordinator.clear(session)
         });
         this.sessionMessageService = new SessionMessageService({
+            resolveExecutionDirectory,
             runtime: this.runtime,
             uploads: this.workspaceUploadService,
             attachments: this.runAttachmentService,
@@ -986,6 +1000,7 @@ export class NodeConnector {
             diagnose: (code, sessionId) => nodeLog('node.restart.diagnostic', { code, sessionId })
         });
         this.sessionCatalogService = new SessionCatalogService({
+            resolveExecutionDirectory,
             database: () => {
                 if (this.database === undefined)
                     throw new Error('NODE_DATABASE_UNAVAILABLE');

package/dist/main.js

@@ -8,6 +8,8 @@ import { browserCachePath, removeServiceDefinition, writeServiceDefinition } fro
 import { superviseNode } from './supervisor.js';
 import { configureNodeLog } from './rotating-log.js';
 import { nodeLog } from './operational.js';
+import { acquireNodeProcessLock, NodeProcessOwnerConflictError, NODE_OWNER_CONFLICT_EXIT_CODE } from './node-process-lock.js';
+import { safeErrorCode } from './util/safe-error.js';
 const [command = 'status', ...args] = process.argv.slice(2);
 const config = readOption(args, '--config') ?? nodeConfigPath();
 const output = readOption(args, '--output') ?? defaultServicePath();
@@ -15,11 +17,22 @@ const browserPath = readOption(args, '--browser-cache');
 if (browserPath !== undefined)
     process.env['PLAYWRIGHT_BROWSERS_PATH'] = browserPath;
 if (command === 'run') {
+    const nodeConfig = await loadNodeConfig(config);
+    let releaseOwner;
+    try {
+        releaseOwner = await acquireNodeProcessLock(nodeDataDirectory(nodeConfig, config));
+    }
+    catch (error) {
+        if (!(error instanceof NodeProcessOwnerConflictError))
+            throw error;
+        console.error(`${error.code}: ${error.message}`);
+        process.exit(NODE_OWNER_CONFLICT_EXIT_CODE);
+    }
     const { NodeConnector } = await import('./connector.js');
-    configureNodeLog(nodeDataDirectory(await loadNodeConfig(config), config));
-    const connector = new NodeConnector({ configPath: config });
+    configureNodeLog(nodeDataDirectory(nodeConfig, config));
+    const connector = new NodeConnector({ configPath: config, config: nodeConfig });
     let shuttingDown = false;
-    const shutdown = () => {
+    const shutdown = (handoff = true, exitCode = 0) => {
         if (shuttingDown)
             return;
         shuttingDown = true;
@@ -27,9 +40,10 @@ if (command === 'run') {
             nodeLog('node.restart.diagnostic', { code: 'RESTART_HANDOFF_SHUTDOWN_TIMEOUT' });
             process.exit(1);
         }, 25_000);
-        void connector.stop({ handoff: true }).then(() => {
+        void connector.stop({ handoff }).then(() => {
             clearTimeout(deadline);
-            process.exit(0);
+            releaseOwner();
+            process.exit(exitCode);
         }, () => {
             clearTimeout(deadline);
             nodeLog('node.restart.diagnostic', { code: 'RESTART_HANDOFF_SHUTDOWN_FAILED' });
@@ -37,9 +51,15 @@ if (command === 'run') {
         });
     };
     for (const signal of ['SIGINT', 'SIGTERM']) {
-        process.on(signal, shutdown);
+        process.on(signal, () => shutdown());
+    }
+    try {
+        await connector.start();
+    }
+    catch (error) {
+        nodeLog('node.start.failed', { code: safeErrorCode(error, 'NODE_START_FAILED') });
+        shutdown(false, 1);
     }
-    await connector.start();
 }
 else if (command === 'supervise') {
     if (process.argv[1] === undefined)

package/dist/node-process-lock.js

@@ -0,0 +1,43 @@
+import { mkdir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { assertLocalSqlitePath, isUnsupportedSqlitePath } from './storage.js';
+export const NODE_OWNER_CONFLICT_EXIT_CODE = 76;
+export class NodeProcessOwnerConflictError extends Error {
+    code = 'NODE_DATA_DIRECTORY_IN_USE';
+    constructor() {
+        super('Another Node process is using this data directory. Stop that instance before starting another.');
+    }
+}
+/** The independent transaction owns the directory, not the business database. */
+export async function acquireNodeProcessLock(dataDirectory) {
+    if (isUnsupportedSqlitePath(dataDirectory))
+        throw new Error('SQLITE_NETWORK_FILESYSTEM_UNSUPPORTED');
+    await mkdir(dataDirectory, { recursive: true, mode: 0o700 });
+    const path = join(await realpath(dataDirectory), 'node-owner.sqlite');
+    await assertLocalSqlitePath(path);
+    let database;
+    try {
+        database = new DatabaseSync(path, { timeout: 0 });
+        database.exec('PRAGMA journal_mode = DELETE; BEGIN EXCLUSIVE;');
+    }
+    catch (error) {
+        try {
+            database?.close();
+        }
+        catch {
+            /* Preserve the acquisition error. */
+        }
+        if (error instanceof Error && 'errcode' in error && error.errcode === 5)
+            throw new NodeProcessOwnerConflictError();
+        throw error;
+    }
+    const owner = database;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        owner.close();
+        released = true;
+    };
+}

package/dist/runner-command-engine.js

@@ -54,14 +54,19 @@ export class CommandStateStore {
     removeSession(sessionId) {
         this.states.delete(sessionId);
     }
+    validateSessionIdentityPromotion(sessionId, nativeSessionId) {
+        if (sessionId === nativeSessionId)
+            return;
+        if (this.states.has(sessionId) && this.states.has(nativeSessionId))
+            throw new Error('SESSION_ID_CONFLICT');
+    }
     promoteSessionIdentity(sessionId, nativeSessionId) {
+        this.validateSessionIdentityPromotion(sessionId, nativeSessionId);
         if (sessionId === nativeSessionId)
             return;
         const values = this.states.get(sessionId);
         if (values === undefined)
             return;
-        if (this.states.has(nativeSessionId))
-            throw new Error('SESSION_ID_CONFLICT');
         this.states.delete(sessionId);
         this.states.set(nativeSessionId, values);
     }

package/dist/runtime-state.js

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+import { nodeLog } from './operational.js';
+import { safeErrorCode } from './util/safe-error.js';
 import { permissionStopSchema } from '@myagentroam/protocol';
 /** User inputs arrive with a durable Session identity, unlike execution-local output IDs. */
 export function runConversationItemId(runId, itemId, kind) {
@@ -206,22 +208,25 @@ export class NodeRuntimeState {
             throw new Error('SESSION_EXTERNAL_ID_INVALID');
         this.promoteSessionIdentity(id, externalSessionId);
     }
+    validateSessionIdentityPromotion(id, nativeSessionId) {
+        if (nativeSessionId.length === 0)
+            throw new Error('SESSION_EXTERNAL_ID_INVALID');
+        const current = this.requireSession(id);
+        if (id !== nativeSessionId && this.sessions.has(nativeSessionId))
+            throw new Error('SESSION_ID_CONFLICT');
+        return current;
+    }
     /**
      * Atomically replaces the bootstrap Session key with the Runner-native ID.
      * No caller may migrate the individual runtime maps independently.
      */
-    promoteSessionIdentity(id, nativeSessionId) {
-        if (nativeSessionId.length === 0)
-            throw new Error('SESSION_EXTERNAL_ID_INVALID');
-        const current = this.requireSession(id);
+    promoteSessionIdentity(id, nativeSessionId, options = {}) {
+        const current = this.validateSessionIdentityPromotion(id, nativeSessionId);
         if (id === nativeSessionId)
             return this.replaceSession(id, {
                 externalSessionId: nativeSessionId,
                 nativeControl: 'MAR_MANAGED'
             });
-        const collision = this.sessions.get(nativeSessionId);
-        if (collision !== undefined && collision.id !== current.id)
-            throw new Error('SESSION_ID_CONFLICT');
         const next = {
             ...current,
             id: nativeSessionId,
@@ -286,12 +291,27 @@ export class NodeRuntimeState {
                     ...reference,
                     sessionId: nativeSessionId
                 });
-        for (const run of runs) {
-            const promoted = this.requireRun(run.id);
-            this.emitRunChanged(promoted, next);
-        }
+        if (options.deferRunChanges !== true)
+            this.publishSessionIdentity(nativeSessionId);
         return next;
     }
+    /** Identity observers run only after the owning identity commit is complete. */
+    publishSessionIdentity(sessionId) {
+        const session = this.requireSession(sessionId);
+        for (const run of this.listRunsForSession(sessionId)) {
+            try {
+                this.emitRunChanged(run, session);
+            }
+            catch (error) {
+                nodeLog('session.identity.publish.failed', {
+                    sessionId,
+                    runId: run.id,
+                    phase: 'run.observer',
+                    errorCode: safeErrorCode(error, 'SESSION_IDENTITY_PUBLICATION_FAILED')
+                });
+            }
+        }
+    }
     setChannelToken(id, channelToken) {
         if (channelToken.length < 16)
             throw new Error('SESSION_CHANNEL_TOKEN_INVALID');
@@ -528,6 +548,7 @@ export class NodeRuntimeState {
     }
     startRunFromQueueItem(itemId, content) {
         const item = this.requireQueueItem(itemId);
+        this.assertSessionHistoryMutable(item.sessionId);
         if (this.activeSessionRun(item.sessionId) !== undefined)
             throw new Error('RUN_ALREADY_ACTIVE');
         const queue = this.queuedItems.get(item.sessionId) ?? [];
@@ -1081,12 +1102,12 @@ export class NodeRuntimeState {
             if (runIds.has(approval.runId) || executionIds.has(approval.runId))
                 this.approvals.delete(approvalId);
     }
-    beginSessionHistoryMutation(sessionId) {
+    beginSessionHistoryMutation(sessionId, options) {
         if (this.sessionHistoryMutations.has(sessionId))
             throw new Error('SESSION_ACTIVE');
         if (this.activeSessionRun(sessionId) !== undefined)
             throw new Error('SESSION_ACTIVE');
-        if (this.sessionQueue(sessionId).itemIds.length > 0)
+        if (options?.allowQueued !== true && this.sessionQueue(sessionId).itemIds.length > 0)
             throw new Error('SESSION_QUEUE_NOT_EMPTY');
         this.sessionHistoryMutations.add(sessionId);
         let released = false;

package/dist/service/continuous-run-coordinator.js

@@ -110,6 +110,25 @@ export class ContinuousRunCoordinator {
             this.options.emitRun(run.id, 'run.rejected', { code }, 'FAILED');
     }
     settle(input) {
+        const pending = this.preparedInputs.get(input.submissionId);
+        if (this.options.resolveExecutionDirectory &&
+            pending &&
+            this.options.runtime.getQueueItem(input.submissionId)) {
+            const version = this.options.runtime.sessionQueue(pending.sessionId).version;
+            return this.directoryForInput(input.submissionId, pending).then((cwd) => {
+                if (cwd === undefined)
+                    return 'QUEUED';
+                if (!this.inputCurrent(input.submissionId, pending) ||
+                    this.options.runtime.sessionQueue(pending.sessionId).version !== version) {
+                    this.schedule(pending.sessionId);
+                    return 'QUEUED';
+                }
+                return this.settleReady(input);
+            });
+        }
+        return this.settleReady(input);
+    }
+    settleReady(input) {
         const item = this.options.runtime.getQueueItem(input.submissionId);
         const active = item && this.options.runtime.activeSessionRun(item.sessionId);
         const turn = active && this.options.runtime.conversationTurnForRun(active.id);
@@ -192,8 +211,7 @@ export class ContinuousRunCoordinator {
         if (active === undefined && item !== undefined) {
             if (input.queueBefore.paused && intent === 'SEND')
                 this.options.runtime.prioritizeQueueItem(item.id);
-            this.startIdleQueue(sessionId);
-            return 'STARTED';
+            return this.startIdleQueue(sessionId).then((started) => started === item.id ? 'STARTED' : 'QUEUED');
         }
         if (executionEnded && item !== undefined) {
             if (input.queueBefore.paused && intent === 'SEND') {
@@ -208,6 +226,20 @@ export class ContinuousRunCoordinator {
         return 'QUEUED';
     }
     executeQueueItem(itemId) {
+        const pending = this.preparedInputs.get(itemId);
+        if (this.options.resolveExecutionDirectory && pending) {
+            const version = this.options.runtime.sessionQueue(pending.sessionId).version;
+            return this.directoryForInput(itemId, pending, true).then((cwd) => {
+                if (cwd === undefined || !this.inputCurrent(itemId, pending))
+                    throw new Error('QUEUE_ITEM_INVALID');
+                if (this.options.runtime.sessionQueue(pending.sessionId).version !== version)
+                    throw new Error('QUEUE_VERSION_CONFLICT');
+                return this.executeQueueItemReady(itemId);
+            });
+        }
+        return this.executeQueueItemReady(itemId);
+    }
+    executeQueueItemReady(itemId) {
         const item = this.requirePreparedItem(itemId);
         const active = this.options.runtime.activeSessionRun(item.sessionId);
         if (active) {
@@ -301,7 +333,7 @@ export class ContinuousRunCoordinator {
         this.steerInFlight.set(itemId, { sessionId: item.sessionId, task });
         return task;
     }
-    executeQueueItemFallback(itemId) {
+    async executeQueueItemFallback(itemId) {
         const item = this.requirePreparedItem(itemId);
         const active = this.options.runtime.activeSessionRun(item.sessionId);
         if (active !== undefined && this.canSteer(active))
@@ -319,7 +351,7 @@ export class ContinuousRunCoordinator {
             }
             return { run: active, delivery: 'ACCEPTED' };
         }
-        this.startIdleQueue(item.sessionId);
+        await this.startIdleQueue(item.sessionId, true);
         const started = this.options.runtime.activeSessionRun(item.sessionId);
         if (started === undefined)
             throw new Error('RUN_NOT_FOUND');
@@ -408,9 +440,29 @@ export class ContinuousRunCoordinator {
         this.options.markInterrupted(executionId);
         this.options.control('run.interrupt', { runId: executionId });
     }
-    resume(sessionId) {
+    async resume(sessionId) {
+        const session = this.options.runtime.getAgentSession(sessionId);
+        if (!session)
+            throw new Error('SESSION_NOT_FOUND');
+        const version = this.options.runtime.sessionQueue(sessionId).version;
+        if (this.options.resolveExecutionDirectory) {
+            try {
+                await this.options.resolveExecutionDirectory(session);
+            }
+            catch (error) {
+                if (this.options.runtime.getAgentSession(sessionId)?.id === session.id &&
+                    this.options.runtime.sessionQueue(sessionId).version === version)
+                    this.pauseForDirectory(sessionId, error);
+                throw error;
+            }
+            if (this.options.runtime.getAgentSession(sessionId)?.id !== session.id ||
+                this.options.runtime.sessionQueue(sessionId).version !== version)
+                return;
+        }
         this.options.runtime.resumeSessionQueue(sessionId);
-        this.startIdleQueue(sessionId);
+        if (this.suspended || this.options.stopped())
+            return;
+        await this.startIdleQueue(sessionId, true);
     }
     schedule(sessionId, delayMs = 0) {
         if (this.suspended)
@@ -420,7 +472,10 @@ export class ContinuousRunCoordinator {
         const timer = setTimeout(() => {
             this.scheduledSessions.delete(sessionId);
             if (!this.options.stopped())
-                void this.dispatch(sessionId);
+                void this.dispatch(sessionId).catch((error) => nodeLog('queue.dispatch.failed', {
+                    sessionId,
+                    code: safeErrorCode(error, 'QUEUE_DISPATCH_FAILED')
+                }));
         }, delayMs);
         this.scheduledSessions.set(sessionId, timer);
         timer.unref();
@@ -438,14 +493,26 @@ export class ContinuousRunCoordinator {
         if ([...this.steerInFlight.values()].some((entry) => entry.sessionId === sessionId))
             return;
         const active = this.options.runtime.activeSessionRun(sessionId);
-        if (active === undefined)
+        if (active === undefined) {
+            await this.startIdleQueue(sessionId);
             return;
+        }
         let executionId = this.options.runtime.currentExecutionId(active.id);
         if (executionId !== undefined && this.dispatchedExecutions.has(executionId))
             return;
         let pending = executionId === undefined
             ? this.preparedInputs.get(active.id)
             : this.preparedInputs.get(executionId);
+        let executionCwd = pending?.cwd;
+        if (pending && this.options.resolveExecutionDirectory) {
+            const key = executionId ?? active.id;
+            executionCwd = await this.directoryForInput(key, pending);
+            if (executionCwd === undefined ||
+                !this.inputCurrent(key, pending) ||
+                this.options.runtime.activeSessionRun(sessionId)?.id !== active.id ||
+                this.options.runtime.currentExecutionId(active.id) !== executionId)
+                return;
+        }
         if (executionId === undefined && pending === undefined) {
             const itemId = this.nextQueueItem(sessionId);
             if (itemId === undefined)
@@ -456,6 +523,20 @@ export class ContinuousRunCoordinator {
             const item = this.options.runtime.getQueueItem(itemId);
             if (item === undefined)
                 return;
+            if (this.options.resolveExecutionDirectory) {
+                const version = this.options.runtime.sessionQueue(sessionId).version;
+                executionCwd = await this.directoryForInput(itemId, pending);
+                if (executionCwd === undefined)
+                    return;
+                if (!this.inputCurrent(itemId, pending) ||
+                    this.options.runtime.activeSessionRun(sessionId)?.id !== active.id ||
+                    this.options.runtime.currentExecutionId(active.id) !== undefined ||
+                    this.options.runtime.sessionQueue(sessionId).version !== version ||
+                    this.nextQueueItem(sessionId) !== itemId) {
+                    this.schedule(sessionId);
+                    return;
+                }
+            }
             if (!this.goalCurrent(pending)) {
                 this.deleteQueueItem(item.id);
                 this.schedule(sessionId);
@@ -501,7 +582,11 @@ export class ContinuousRunCoordinator {
         let dispatched = false;
         try {
             // Capabilities belong to this Execution, never the Run or a claimed QueueItem.
-            const executionInput = { ...pending, runId: executionId };
+            const executionInput = {
+                ...pending,
+                cwd: executionCwd ?? pending.cwd,
+                runId: executionId
+            };
             const goalMcp = pending.goal === undefined ? undefined : await this.options.goalMcp?.(executionInput);
             const scheduleMcp = await this.options.scheduleMcp?.(executionInput);
             const notificationMcp = await this.options.notificationMcp?.(executionInput);
@@ -524,7 +609,7 @@ export class ContinuousRunCoordinator {
                     ? {}
                     : { clientMessageId: pending.clientMessageId }),
                 ...(pending.attachments.length === 0 ? {} : { attachments: pending.attachments }),
-                cwd: pending.cwd,
+                cwd: executionCwd ?? pending.cwd,
                 ...(pending.externalSessionId === null
                     ? {}
                     : { externalSessionId: pending.externalSessionId }),
@@ -638,7 +723,7 @@ export class ContinuousRunCoordinator {
             clearTimeout(timer);
         this.scheduledSessions.clear();
     }
-    startIdleQueue(sessionId) {
+    async startIdleQueue(sessionId, throwOnError = false) {
         if (this.options.runtime.activeSessionRun(sessionId) !== undefined) {
             this.schedule(sessionId);
             return;
@@ -654,8 +739,20 @@ export class ContinuousRunCoordinator {
             throw new Error('QUEUE_ITEM_INVALID');
         if (!this.goalCurrent(pending)) {
             this.deleteQueueItem(item.id);
-            this.startIdleQueue(sessionId);
-            return;
+            return this.startIdleQueue(sessionId, throwOnError);
+        }
+        if (this.options.resolveExecutionDirectory) {
+            const version = this.options.runtime.sessionQueue(sessionId).version;
+            const cwd = await this.directoryForInput(itemId, pending, throwOnError);
+            if (cwd === undefined)
+                return;
+            if (!this.inputCurrent(itemId, pending) ||
+                this.options.runtime.activeSessionRun(sessionId) !== undefined ||
+                this.options.runtime.sessionQueue(sessionId).version !== version ||
+                this.nextQueueItem(sessionId) !== itemId) {
+                this.schedule(sessionId);
+                return;
+            }
         }
         this.prioritizeNextQueueItem(sessionId, itemId);
         const { run, turn } = this.options.runtime.startRunFromQueueItem(itemId, withNonImageAttachmentPrompt(item.content, pending.attachmentPaths, pending.attachmentFiles));
@@ -665,6 +762,61 @@ export class ContinuousRunCoordinator {
         this.options.emitQueue(run.workspaceId, sessionId);
         this.options.emitConversation(turn);
         this.schedule(sessionId);
+        return itemId;
+    }
+    inputCurrent(id, pending) {
+        const session = this.options.runtime.getAgentSession(pending.sessionId);
+        return (!this.suspended &&
+            !this.options.stopped() &&
+            this.preparedInputs.get(id) === pending &&
+            session?.id === pending.sessionId &&
+            session.workspaceId === pending.workspaceId);
+    }
+    async directoryForInput(id, pending, throwOnError = false) {
+        const session = this.options.runtime.getAgentSession(pending.sessionId);
+        if (!session || !this.inputCurrent(id, pending))
+            return undefined;
+        const version = this.options.runtime.sessionQueue(session.id).version;
+        try {
+            return await this.options.resolveExecutionDirectory(session);
+        }
+        catch (error) {
+            if (!this.inputCurrent(id, pending)) {
+                if (this.options.runtime.getAgentSession(session.id) !== undefined &&
+                    this.preparedInputs.get(id) !== pending)
+                    this.schedule(session.id);
+                return undefined;
+            }
+            if (this.options.runtime.getQueueItem(id)) {
+                if (this.options.runtime.sessionQueue(session.id).version === version)
+                    this.pauseForDirectory(session.id, error);
+                else
+                    this.schedule(session.id);
+            }
+            else {
+                this.options.emitRun(pending.runId, 'run.rejected', { code: safeErrorCode(error, 'QUEUE_DISPATCH_FAILED') }, 'FAILED');
+            }
+            if (throwOnError)
+                throw error;
+            return undefined;
+        }
+    }
+    pauseForDirectory(sessionId, error) {
+        if (!this.options.runtime.sessionQueue(sessionId).paused)
+            this.options.runtime.pauseSessionQueue(sessionId);
+        nodeLog('queue.execution_directory.invalid', {
+            sessionId,
+            code: safeErrorCode(error, 'QUEUE_DISPATCH_FAILED')
+        });
+        const active = this.options.runtime.activeSessionRun(sessionId);
+        if (active && this.options.runtime.currentExecutionId(active.id) === undefined)
+            this.finishTerminalCommandRun(active);
+        try {
+            this.publish(sessionId);
+        }
+        catch {
+            nodeLog('queue.execution_directory.publish_failed', { sessionId });
+        }
     }
     nextQueueItem(sessionId) {
         const queue = this.options.runtime.sessionQueue(sessionId);

package/dist/service/external-session-resume-service.js

@@ -35,10 +35,16 @@ export class ExternalSessionResumeService {
             this.setFailure(external.id, 'RUNNER_UNAVAILABLE');
             return undefined;
         }
+        const releaseMutation = this.options.runtime.beginSessionHistoryMutation(external.id, {
+            allowQueued: true
+        });
         this.transitions.add(external.id);
         let result;
         try {
-            result = await runner.resumeExternal(external, {
+            const cwd = this.options.resolveExecutionDirectory
+                ? await this.options.resolveExecutionDirectory(external)
+                : external.cwd;
+            result = await runner.resumeExternal({ ...external, cwd }, {
                 available: this.options.available(external.runner),
                 projectionFor: this.options.projectionFor,
                 managedAliasFor: this.options.managedAliasFor,
@@ -62,7 +68,7 @@ export class ExternalSessionResumeService {
                             ? {}
                             : { externalSessionId: session.externalSessionId }),
                         nativeControl: 'MAR_MANAGED',
-                        cwd: session.cwd,
+                        cwd,
                         createdAt: session.createdAt,
                         lastActivityAt: session.lastActivityAt,
                         model: configuration.model,
@@ -80,6 +86,7 @@ export class ExternalSessionResumeService {
         }
         finally {
             this.transitions.delete(external.id);
+            releaseMutation();
         }
         if (result.activity !== undefined)
             this.options.state.externalActivity.set(external.id, result.activity);

package/dist/service/restart-session-restorer.js

@@ -131,7 +131,7 @@ ${RESTART_NOTICE}`,
                 }));
             }
             if (!entry.paused)
-                coordinator.resume(session.id);
+                await coordinator.resume(session.id);
             this.options.publishQueue(session);
         }
         catch (error) {

package/dist/service/session-catalog-service.js

@@ -240,11 +240,14 @@ export class SessionCatalogService {
             .listAgentSessions()
             .flatMap((candidate) => [candidate.customTitle ?? candidate.runnerTitle].filter(isString)));
         const runner = this.options.runners.require(source.runner);
-        const nativeId = await runner.forkNative(source, input.boundary, title);
+        const cwd = this.options.resolveExecutionDirectory
+            ? await this.options.resolveExecutionDirectory(source)
+            : source.cwd;
+        const nativeId = await runner.forkNative({ ...source, cwd }, input.boundary, title);
         const session = this.options.runtime.createAgentSession({
             workspaceId: source.workspaceId,
             runner: source.runner,
-            cwd: source.cwd,
+            cwd,
             nativeControl: 'MAR_MANAGED',
             ...(nativeId === null ? {} : { externalSessionId: nativeId }),
             ...(source.model === null ? {} : { model: source.model }),
@@ -375,9 +378,7 @@ export class SessionCatalogService {
     async removeResolved(session, requireCleanupSafety = false) {
         if (session.externalSessionId === null)
             throw new Error('NATIVE_TRANSCRIPT_UNAVAILABLE');
-        const releaseMutation = requireCleanupSafety
-            ? this.options.runtime.beginSessionHistoryMutation(session.id)
-            : undefined;
+        const releaseMutation = this.options.runtime.beginSessionHistoryMutation(session.id, requireCleanupSafety ? undefined : { allowQueued: true });
         try {
             if (this.options.isRecovering?.(session.id))
                 throw new Error('SESSION_RESTART_PENDING');
@@ -431,7 +432,7 @@ export class SessionCatalogService {
             return deleted ? 'deleted' : 'skipped';
         }
         finally {
-            releaseMutation?.();
+            releaseMutation();
         }
     }
 }

package/dist/service/session-identity-service.js

@@ -1,5 +1,6 @@
 import { nodeLog } from '../operational.js';
 import { isTerminalRunStatus } from '../util/node-operation-parsers.js';
+import { safeErrorCode } from '../util/safe-error.js';
 export class SessionIdentityService {
     options;
     bootstrapIds = new Set();
@@ -12,12 +13,21 @@ export class SessionIdentityService {
         this.bootstrapIds.add(sessionId);
     }
     promote(sessionId, nativeSessionId) {
-        if (this.failedBootstrapIds.has(sessionId))
-            throw new Error('SESSION_START_FAILED');
-        const current = this.options.runtime.getAgentSession(sessionId);
-        this.options.runtime.promoteSessionIdentity(sessionId, nativeSessionId);
-        if (current !== undefined)
+        try {
+            if (this.failedBootstrapIds.has(sessionId))
+                throw new Error('SESSION_START_FAILED');
+            const current = this.options.runtime.validateSessionIdentityPromotion(sessionId, nativeSessionId);
+            this.options.validateCommands(sessionId, nativeSessionId);
             this.options.persist(current, nativeSessionId);
+        }
+        catch (error) {
+            this.reject(sessionId, error instanceof Error ? error : new Error('SESSION_START_FAILED'));
+            throw error;
+        }
+        // No I/O or publication may interrupt the synchronous ownership migration.
+        const session = this.options.runtime.promoteSessionIdentity(sessionId, nativeSessionId, {
+            deferRunChanges: true
+        });
         this.options.migrateGoal(sessionId, nativeSessionId);
         this.options.migrateCommands(sessionId, nativeSessionId);
         this.options.migrateQueue(sessionId, nativeSessionId);
@@ -29,16 +39,27 @@ export class SessionIdentityService {
             this.waiters.delete(sessionId);
             waiter.resolve(nativeSessionId);
         }
-        const session = this.options.runtime.getAgentSession(nativeSessionId);
-        if (session === undefined)
-            return;
-        this.options.emitSession(session);
+        if (sessionId !== nativeSessionId)
+            this.options.runtime.publishSessionIdentity(nativeSessionId);
+        this.publish(nativeSessionId, 'session', () => this.options.emitSession(session));
         for (const run of this.options.runtime.listRunsForSession(nativeSessionId))
-            this.options.emitRun(run);
-        this.options.emitQueue(nativeSessionId);
+            this.publish(nativeSessionId, 'run', () => this.options.emitRun(run));
+        this.publish(nativeSessionId, 'queue', () => this.options.emitQueue(nativeSessionId));
         for (const turn of this.options.runtime.listConversationTurns({ sessionId: nativeSessionId })
             .turns)
-            this.options.emitTurn(turn);
+            this.publish(nativeSessionId, 'turn', () => this.options.emitTurn(turn));
+    }
+    publish(sessionId, phase, emit) {
+        try {
+            emit();
+        }
+        catch (error) {
+            nodeLog('session.identity.publish.failed', {
+                sessionId,
+                phase,
+                errorCode: safeErrorCode(error, 'SESSION_IDENTITY_PUBLICATION_FAILED')
+            });
+        }
     }
     wait(bootstrapSessionId) {
         const existing = this.waiters.get(bootstrapSessionId);
@@ -64,7 +85,7 @@ export class SessionIdentityService {
         });
         return promise;
     }
-    reject(sessionId, code) {
+    reject(sessionId, reason) {
         const bootstrap = this.bootstrapIds.has(sessionId);
         if (bootstrap) {
             this.failedBootstrapIds.add(sessionId);
@@ -74,7 +95,7 @@ export class SessionIdentityService {
         if (waiter !== undefined) {
             clearTimeout(waiter.timer);
             this.waiters.delete(sessionId);
-            waiter.reject(new Error(code));
+            waiter.reject(typeof reason === 'string' ? new Error(reason) : reason);
         }
         if (!bootstrap)
             return;

package/dist/service/session-lifecycle-service.js

@@ -3,6 +3,7 @@ import { isPlainRecord } from '../util/node-operation-parsers.js';
 import { parseSecretEnvironment } from '../util/secret-environment.js';
 import { ScheduledSessionStore } from './scheduled-session-store.js';
 import { normalizeSessionPrompt } from '../util/personal-instructions.js';
+import { resolveWorkspaceExecutionDirectory } from '../workspace.js';
 export class SessionLifecycleService {
     options;
     starts = new Map();
@@ -83,7 +84,7 @@ export class SessionLifecycleService {
         this.options.invalidateWorkspaceSessions(workspaceId);
         return { moved: true };
     }
-    create(input) {
+    async create(input) {
         const runner = this.options.runners.product(input.runner);
         if (typeof input.workspaceId !== 'string' ||
             runner === undefined ||
@@ -100,6 +101,9 @@ export class SessionLifecycleService {
         const workspace = database.getWorkspace(input.workspaceId);
         if (workspace === undefined)
             throw new Error('WORKSPACE_NOT_FOUND');
+        const cwd = await resolveWorkspaceExecutionDirectory(workspace.path, input.cwd);
+        if (database.getWorkspace(workspace.id)?.path !== workspace.path)
+            throw new Error('WORKSPACE_NOT_FOUND');
         let parentSessionId;
         if (input.parentSessionId !== undefined) {
             if (typeof input.parentSessionId !== 'string' ||
@@ -133,7 +137,7 @@ export class SessionLifecycleService {
             ...(parentSessionId === undefined ? {} : { parentSessionId }),
             workspaceId: input.workspaceId,
             runner: runner.name,
-            cwd: input.cwd,
+            cwd,
             ...(typeof input.externalSessionId === 'string'
                 ? { externalSessionId: input.externalSessionId }
                 : {}),

package/dist/service/session-message-service.js

@@ -208,7 +208,18 @@ export class SessionMessageService {
                 let reservation;
                 let nativeAccepted = false;
                 try {
-                    const currentSession = this.options.runtime.getAgentSession(session.id) ?? session;
+                    let currentSession = this.options.runtime.getAgentSession(session.id) ?? session;
+                    const cwd = this.options.resolveExecutionDirectory
+                        ? await this.options.resolveExecutionDirectory(currentSession)
+                        : currentSession.cwd;
+                    if (this.options.resolveExecutionDirectory) {
+                        const latest = this.options.runtime.getAgentSession(currentSession.id);
+                        if (!latest ||
+                            latest.workspaceId !== currentSession.workspaceId ||
+                            latest.cwd !== currentSession.cwd)
+                            throw new Error('SESSION_NOT_FOUND');
+                        currentSession = latest;
+                    }
                     if (attachmentIds.length > 0)
                         reservation = await this.options.uploads.reserve(session.workspaceId, attachmentIds);
                     const attachments = reservation === undefined
@@ -228,11 +239,11 @@ export class SessionMessageService {
                             this.options.attachments.resourcePath(attachmentPaths[index])
                     }));
                     const runnerFiles = attachmentFiles.map((file, index) => {
-                        const path = relative(currentSession.cwd, attachmentPaths[index]).replaceAll('\\', '/');
+                        const path = relative(cwd, attachmentPaths[index]).replaceAll('\\', '/');
                         return path === file.path ? file : { ...file, path, workspacePath: file.path };
                     });
                     const displayInput = withNonImageAttachmentPrompt(publicContent, attachmentPaths, attachmentFiles);
-                    const resourceInput = prepareComposerResourceInput(runnerContent, currentSession.cwd, workspacePath);
+                    const resourceInput = prepareComposerResourceInput(runnerContent, cwd, workspacePath);
                     const runnerInput = withNonImageAttachmentPrompt(resourceInput, attachmentPaths, runnerFiles);
                     const planActive = this.options.commands
                         .list(session.id)
@@ -270,7 +281,7 @@ export class SessionMessageService {
                         attachments: runnerImageAttachments,
                         attachmentPaths,
                         attachmentFiles: runnerFiles,
-                        cwd: currentSession.cwd,
+                        cwd,
                         workspacePath,
                         externalSessionId: currentSession.externalSessionId,
                         model: currentSession.model,

package/dist/service/workspace-queue-workbench-service.js

@@ -1,6 +1,8 @@
 import { steerComposerMessage } from '@myagentroam/protocol';
 import { isPlainRecord, withNonImageAttachmentPrompt } from '../util/node-operation-parsers.js';
 import { assertQueueItemOwner, assertSessionControlOwner } from './run-ownership-policy.js';
+import { nodeLog } from '../operational.js';
+import { safeErrorCode } from '../util/safe-error.js';
 export class WorkspaceQueueWorkbenchService {
     options;
     constructor(options) {
@@ -30,8 +32,13 @@ export class WorkspaceQueueWorkbenchService {
             throw new Error('SESSION_NOT_FOUND');
         if (!this.options.runtime.sessionQueue(session.id).paused)
             return;
-        this.options.coordinator.resume(session.id);
-        this.options.emit(session.workspaceId, session.id);
+        void this.options.coordinator
+            .resume(session.id)
+            .then(() => this.options.emit(session.workspaceId, session.id))
+            .catch((error) => nodeLog('queue.resume.failed', {
+            sessionId,
+            code: safeErrorCode(error, 'QUEUE_RESUME_FAILED')
+        }));
     }
     present(workspaceId, sessionId) {
         const session = this.options.runtime.getAgentSession(sessionId);
@@ -75,11 +82,11 @@ export class WorkspaceQueueWorkbenchService {
             queue: this.snapshot(session.id)
         };
     }
-    pauseOrResume(mode, input) {
+    async pauseOrResume(mode, input) {
         const session = this.requireSession(input);
         assertSessionControlOwner(this.options.runtime, session.id, input.__requestUserId);
         if (mode === 'resume')
-            this.options.coordinator.resume(session.id);
+            await this.options.coordinator.resume(session.id);
         else
             this.options.runtime.pauseSessionQueue(session.id);
         this.options.emit(session.workspaceId, session.id);

package/dist/supervisor.js

@@ -5,6 +5,7 @@ import { loadNodeConfig, nodeDatabasePath } from './config.js';
 import { nodeLog, platformCliInvocation } from './operational.js';
 import { nodeUpgradeRequestPath } from './service/node-upgrade-coordinator.js';
 import { safeErrorCode } from './util/safe-error.js';
+import { NODE_OWNER_CONFLICT_EXIT_CODE } from './node-process-lock.js';
 const UPGRADE_EXIT_CODE = 75;
 const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
 export async function superviseNode(configPath, bootstrapEntrypoint) {
@@ -19,6 +20,10 @@ export async function superviseNode(configPath, bootstrapEntrypoint) {
             return;
         }
         const code = childResult.code;
+        if (code === NODE_OWNER_CONFLICT_EXIT_CODE) {
+            process.exitCode = code;
+            return;
+        }
         if (code !== UPGRADE_EXIT_CODE) {
             if (code === 0)
                 return;

package/dist/workspace.js

@@ -999,9 +999,52 @@ export async function searchWorkspaceFiles(workspaceRoot, query, cursor, limit =
 async function resolveRegisteredWorkspaceRoot(workspaceRoot) {
     const root = await realpath(workspaceRoot);
     if (normalizeWorkspacePath(root) !== normalizeWorkspacePath(workspaceRoot))
-        throw new Error('WORKSPACE_NOT_ALLOWED');
+        throw Object.assign(new Error('WORKSPACE_NOT_ALLOWED'), { code: 'WORKSPACE_NOT_ALLOWED' });
     return root;
 }
+export class SessionExecutionDirectoryError extends Error {
+    publicMessage;
+    code = 'SESSION_EXECUTION_DIRECTORY_INVALID';
+    publicParameters;
+    constructor(reason, publicMessage, options) {
+        super(publicMessage, options);
+        this.publicMessage = publicMessage;
+        this.publicParameters = { reason };
+    }
+}
+/** Bind ordinary Session execution to one registered Workspace, not all allowed roots. */
+export async function resolveWorkspaceExecutionDirectory(workspaceRoot, cwd) {
+    if (!isAbsolute(cwd) || (process.platform === 'win32' && win32.parse(cwd).root.length <= 1))
+        throw new SessionExecutionDirectoryError('ABSOLUTE_PATH_REQUIRED', 'The execution directory must be an absolute path on this Node.');
+    try {
+        const root = await resolveRegisteredWorkspaceRoot(workspaceRoot);
+        const directory = await realpath(cwd);
+        if (!isWithinAllowedRoot(directory, [root]))
+            throw new SessionExecutionDirectoryError('OUTSIDE_WORKSPACE', 'The execution directory is outside the authorized Workspace.');
+        if (!(await stat(directory)).isDirectory())
+            throw new SessionExecutionDirectoryError('NOT_DIRECTORY', 'The execution directory is not a directory.');
+        return directory;
+    }
+    catch (error) {
+        if (error instanceof SessionExecutionDirectoryError)
+            throw error;
+        const code = error !== null && typeof error === 'object' && 'code' in error ? error.code : undefined;
+        const [reason, message] = code === 'WORKSPACE_NOT_ALLOWED'
+            ? [
+                'WORKSPACE_ROOT_CHANGED',
+                'The registered Workspace root no longer identifies the same directory.'
+            ]
+            : code === 'ENOENT' || code === 'ENOTDIR'
+                ? ['NOT_FOUND', 'The execution directory or Workspace root is unavailable.']
+                : code === 'EACCES' || code === 'EPERM'
+                    ? [
+                        'ACCESS_DENIED',
+                        'The Node account cannot access the execution directory or Workspace root.'
+                    ]
+                    : ['IO_ERROR', 'The execution directory could not be verified.'];
+        throw new SessionExecutionDirectoryError(reason, message, { cause: error });
+    }
+}
 async function resolveWorkspaceEntry(workspaceRoot, requestedPath, directory) {
     const root = await resolveRegisteredWorkspaceRoot(workspaceRoot);
     return resolveWorkspaceEntryFromCanonicalRoot(root, requestedPath, directory);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.10.66",
+  "version": "0.10.68",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -37,10 +37,10 @@
     "playwright": "1.62.1",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.10.66",
+    "@myagentroam/agent": "0.10.68",
     "@myagentroam/code-navigation": "0.10.1",
     "@myagentroam/marctl": "0.10.12",
-    "@myagentroam/protocol": "0.10.66"
+    "@myagentroam/protocol": "0.10.68"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"