@myagentroam/node 0.10.34 → 0.10.36

package/dist/connector.js

@@ -68,7 +68,9 @@ import { composerResourceInputTags } from './service/composer-message-input.js';
 import { SessionScheduleService } from './service/session-schedule-service.js';
 import { ScheduledSessionCoordinator } from './service/scheduled-session-coordinator.js';
 import { ScheduledSessionStore } from './service/scheduled-session-store.js';
-import { ScheduledRunAuthorizationControl } from './service/scheduled-run-authorization-control.js';
+import { RunAuthorizationControl } from './service/run-authorization-control.js';
+import { PlannedRestartHandoff } from './service/planned-restart-handoff.js';
+import { RestartSessionRestorer } from './service/restart-session-restorer.js';
 import { ScheduledTaskMcpServer } from './service/scheduled-task-mcp-server.js';
 import { MailNotificationControl } from './service/mail-notification-control.js';
 import { MailNotificationMcpServer, resolveMailNotificationCapability } from './service/mail-notification-mcp-server.js';
@@ -169,6 +171,9 @@ export class NodeConnector {
     controlChannel;
     controlMessages;
     scheduledRunAuthorization;
+    restartAuthorization;
+    restartHandoff;
+    inFlightOperations = new Set();
     mailNotificationControl = new MailNotificationControl((envelope) => this.sendEnvelope(envelope));
     scheduledSessions;
     nodeRequests;
@@ -397,6 +402,8 @@ export class NodeConnector {
             this.goalRuntime.get(sessionId)?.status === 'active',
         executionTerminating: (executionId, status, permissionStop) => {
             this.gitOperationService.executionFinished(executionId);
+            if (this.stopped)
+                return;
             const pending = this.continuousRunCoordinator.pending(executionId);
             if (pending?.goal === undefined)
                 return;
@@ -779,7 +786,8 @@ export class NodeConnector {
             goal: (sessionId) => this.goalRuntime.get(sessionId),
             runtime: this.runtime,
             runners: this.runners,
-            resolve: (sessionId) => this.nativeSessionProjectionService.resolve(sessionId),
+            resolve: (sessionId, registeredOnly) => this.nativeSessionProjectionService.resolve(sessionId, registeredOnly),
+            similar: (sessionId, workspaceId) => this.nativeSessionProjectionService.similarSessionDetails(sessionId, workspaceId),
             present: (session) => this.sessionPresentationService.present(session),
             history: (session, input) => this.conversationHistoryService.read(session, input),
             segments: (session, input) => this.conversationSegmentService.read(session, input),
@@ -937,6 +945,7 @@ export class NodeConnector {
         });
         this.workspaceQueueWorkbenchService = new WorkspaceQueueWorkbenchService({
             runtime: this.runtime,
+            resolve: (sessionId, registeredOnly) => this.nativeSessionProjectionService.resolve(sessionId, registeredOnly),
             coordinator: this.continuousRunCoordinator,
             emit: (workspaceId, sessionId) => this.runEventBridge.emitQueue(workspaceId, sessionId),
             prepareInput: (runner, input, collaborationMode) => this.runners.require(runner).prepareMessageInput(input, collaborationMode)
@@ -947,15 +956,18 @@ export class NodeConnector {
                 void this.runAttachmentService.releaseSession(sessionId);
             },
             persist: (session, nativeSessionId) => {
-                if (session.model === null || session.effort === null || session.access === null)
-                    return;
                 this.database?.saveNativeSessionMetadata({
+                    ...(session.parentSessionId == null ? {} : { parentSessionId: session.parentSessionId }),
                     runner: session.runner,
                     externalSessionId: nativeSessionId,
                     workspaceId: session.workspaceId,
-                    model: session.model,
-                    effort: session.effort,
-                    access: session.access
+                    ...(session.model === null ? {} : { model: session.model }),
+                    ...(session.effort === null ? {} : { effort: session.effort }),
+                    ...(session.access === null ? {} : { access: session.access }),
+                    ...(session.customTitle === null ? {} : { customTitle: session.customTitle }),
+                    ...(session.runnerTitle === null
+                        ? {}
+                        : { runnerTitle: session.runnerTitle.slice(0, 160) })
                 });
             },
             migrateCommands: (previousId, nextId) => this.commandStates.promoteSessionIdentity(previousId, nextId),
@@ -1073,7 +1085,7 @@ export class NodeConnector {
                     goalAccessChanged: prepared.changed
                 };
             },
-            goal: async ({ session, objective, initiatedByUserId, secretEnvironment, personalInstructions, marAgentModel, marAgentModels, marAgentCompact, marAgentRuntimeScopeId, usageGrant }) => {
+            goal: async ({ session, objective, initiatedByUserId, suppressNotifications, secretEnvironment, personalInstructions, marAgentModel, marAgentModels, marAgentCompact, marAgentRuntimeScopeId, usageGrant }) => {
                 this.invalidateGoalContinuation(session.id);
                 const prepared = this.prepareGoalSession(session);
                 const goalSession = prepared.session;
@@ -1093,6 +1105,7 @@ export class NodeConnector {
                         objective: goal.objective,
                         deliveryIntent: replacing ? 'REPLACE_CURRENT' : 'SEND',
                         goal: goalRef,
+                        ...(suppressNotifications === true ? { suppressNotifications: true } : {}),
                         ...(usageGrant === undefined ? {} : { usageGrant }),
                         ...(initiatedByUserId === undefined ? {} : { initiatedByUserId }),
                         secretEnvironment,
@@ -1190,6 +1203,31 @@ export class NodeConnector {
             },
             goalPreparationFailed: (session, goal, activated) => this.handleGoalPreparationFailed(session, goal, activated)
         });
+        const inputState = (entry, message) => this.marAgentClient.restartInputState(entry.session.id, message.clientMessageId);
+        const restorer = new RestartSessionRestorer({
+            runtime: this.runtime,
+            goals: this.goalRuntime,
+            commands: this.commandStates,
+            coordinator: this.continuousRunCoordinator,
+            messages: this.sessionMessageService,
+            resolve: (id) => this.externalSessionResumeService.resolveForMessage(id),
+            authorize: (request) => this.restartAuthorization.authorize(request),
+            inputState,
+            withGrant: (context, work) => this.modelUsage.withGrant(context.usageGrant, work),
+            publishGoal: (session, goal) => this.publishGoalState(session, goal),
+            publishQueue: (session) => this.continuousRunCoordinator.publish(session.id)
+        });
+        this.restartHandoff = new PlannedRestartHandoff({
+            directory: () => nodeDataDirectory(this.config, this.configPath),
+            identity: () => ({ nodeId: this.config.nodeId, serverUrl: this.config.serverUrl }),
+            runtime: this.runtime,
+            coordinator: this.continuousRunCoordinator,
+            goals: this.goalRuntime,
+            commandActive: (id, command) => this.commandStates.get(id, command)?.active === true,
+            inputState,
+            restore: (entry, id) => restorer.restore(entry, id),
+            diagnose: (code, sessionId) => nodeLog('node.restart.diagnostic', { code, sessionId })
+        });
         this.sessionCatalogService = new SessionCatalogService({
             database: () => {
                 if (this.database === undefined)
@@ -1216,6 +1254,7 @@ export class NodeConnector {
             refreshActivity: (session) => this.conversationHistoryService.refreshExternalActivity(session),
             externalActivity: (sessionId) => this.sessionState.externalActivity.get(sessionId),
             isWatching: (sessionId) => this.nativeSessionWatchService.isWatching(sessionId),
+            isRecovering: (sessionId) => this.restartHandoff.blocks(sessionId),
             history: (session, input) => this.conversationHistoryService.read(session, input),
             invalidateHistory: (sessionId, workspaceId) => {
                 this.nativeSessionWatchService.invalidate(sessionId);
@@ -1323,10 +1362,11 @@ export class NodeConnector {
             onClose: (code, reason) => {
                 this.promptCompletion?.disconnect();
                 this.usageOutbox?.disconnected();
-                this.directTransferService?.close();
+                this.directTransferService?.close('DIRECT_TRANSFER_CONTROL_UNAVAILABLE');
                 this.runtimeCredentials.disconnected();
                 this.chatgptLogins.close();
                 this.scheduledRunAuthorization.disconnected();
+                this.restartAuthorization.disconnected();
                 this.mailNotificationControl.disconnected();
                 this.mailNotificationMcpServer.revokeAll();
                 this.terminalChannel.disconnect();
@@ -1364,7 +1404,8 @@ export class NodeConnector {
             inspectWorkspace: (envelope) => this.workspaceCoordinator.inspect(envelope),
             handleNodeRequest: (envelope) => this.nodeRequests.handle(envelope),
             handleRuntimeCredentialResponse: (envelope) => this.runtimeCredentials.handle(envelope),
-            handleScheduledRunAuthorizeResponse: (envelope) => this.scheduledRunAuthorization.handle(envelope),
+            handleScheduledRunAuthorizeResponse: (envelope) => this.scheduledRunAuthorization.handle(envelope) ||
+                this.restartAuthorization.handle(envelope),
             handleMailNotificationResponse: (envelope) => this.mailNotificationControl.handle(envelope),
             handleDirectTransfer: (envelope) => this.handleDirectTransfer(envelope),
             handleTerminalDirect: (envelope) => this.handleTerminalDirect(envelope),
@@ -1435,6 +1476,9 @@ export class NodeConnector {
             onConnected: () => {
                 this.runtimeCredentials.connected();
                 this.scheduledRunAuthorization.connected();
+                this.restartAuthorization.connected();
+                if (!this.stopped)
+                    void this.restartHandoff.recover();
                 this.mailNotificationControl.connected();
                 this.recentRunProjectionService.publishSnapshot();
             }
@@ -1444,10 +1488,13 @@ export class NodeConnector {
                 throw new Error('NODE_DATABASE_UNAVAILABLE');
             return this.database;
         };
-        this.scheduledRunAuthorization = new ScheduledRunAuthorizationControl((envelope) => this.controlChannel.sendEnvelope(envelope));
+        this.scheduledRunAuthorization = new RunAuthorizationControl((envelope) => this.controlChannel.sendEnvelope(envelope));
+        this.restartAuthorization = new RunAuthorizationControl((envelope) => this.controlChannel.sendEnvelope(envelope), 'restart');
         this.scheduledSessions = new ScheduledSessionCoordinator({
             store: () => new ScheduledSessionStore(requireDatabase().raw),
-            busy: (task) => this.runtime.activeSessionRun(task.sessionId) !== undefined ||
+            busy: (task) => this.stopped ||
+                this.restartHandoff.blocks(task.sessionId) ||
+                this.runtime.activeSessionRun(task.sessionId) !== undefined ||
                 this.runtime.sessionQueue(task.sessionId).itemIds.length > 0,
             authorize: async (task, occurrenceId) => {
                 const session = this.runtime.getAgentSession(task.sessionId) ??
@@ -1800,6 +1847,8 @@ export class NodeConnector {
             await this.stopping;
         this.stopping = undefined;
         this.stopped = false;
+        this.continuousRunCoordinator.resumeScheduling();
+        this.sessionMessageService.setAccepting(true);
         this.config ??= await loadNodeConfig(this.configPath);
         this.promptCompletion.initializeJournal(nodeDataDirectory(this.config, this.configPath));
         await this.upgradeCoordinator.loadResult(resolve(dirname(nodeDatabasePath(this.config, this.configPath)), 'upgrade-result.json'));
@@ -1816,6 +1865,7 @@ export class NodeConnector {
         });
         this.usageOutbox.recoverInterrupted();
         this.database.closeRunningTerminalSessions();
+        await this.restartHandoff.load();
         this.scheduledSessions.start();
         await this.initializeConversationHosting();
         this.computerUseEnablement.initialize();
@@ -1838,6 +1888,7 @@ export class NodeConnector {
                     const upload = await this.workspaceUploadService.createDirect(workspace, {
                         path: descriptor.resource.path,
                         size: descriptor.size,
+                        sha256: descriptor.sha256,
                         overwrite: descriptor.overwrite === true,
                         ...(descriptor.composerAttachment === undefined
                             ? {}
@@ -1846,7 +1897,7 @@ export class NodeConnector {
                     return {
                         offset: upload.receivedBytes,
                         write: (bytes) => this.workspaceUploadService.writeDirect(upload.uploadId, bytes),
-                        complete: (size) => this.workspaceUploadService.completeDirect(upload.uploadId, size),
+                        complete: (size, signal) => this.workspaceUploadService.completeDirect(upload.uploadId, size, signal),
                         cancel: () => this.workspaceUploadService.cancel(upload.uploadId)
                     };
                 },
@@ -2141,10 +2192,32 @@ export class NodeConnector {
             closeInput: '/goal --clear'
         };
     }
-    stop() {
+    stop(options = {}) {
         if (this.stopping !== undefined)
             return this.stopping;
         this.stopped = true;
+        this.continuousRunCoordinator.suspend();
+        this.scheduledSessions.stop();
+        this.stopping = (async () => {
+            let snapshot;
+            try {
+                // In-flight recovery must rebuild accepted inputs before preparation closes.
+                await this.restartHandoff.wait();
+                this.sessionMessageService.setAccepting(false);
+                await Promise.allSettled([...this.inFlightOperations]);
+                await this.sessionMessageService.drain();
+                if (options.handoff && this.config?.nodeId)
+                    snapshot = this.restartHandoff.capture();
+            }
+            finally {
+                await this.disposeRuntime();
+            }
+            if (snapshot !== undefined)
+                await this.restartHandoff.publish(snapshot);
+        })();
+        return this.stopping;
+    }
+    disposeRuntime() {
         this.recentRunProjectionService.dispose();
         this.upgradeCoordinator.stop();
         this.connectionLifecycle.stop();
@@ -2202,6 +2275,7 @@ export class NodeConnector {
         this.chatgptLogins.close();
         this.scheduledSessions.stop();
         this.scheduledRunAuthorization.close();
+        this.restartAuthorization.close();
         this.mailNotificationControl.close();
         const mailMcpDrain = this.mailNotificationMcpServer.close();
         const webToolDrain = this.webToolService.close();
@@ -2220,21 +2294,24 @@ export class NodeConnector {
             mailMcpDrain,
             webToolDrain
         ]);
-        this.stopping = (async () => {
+        return (async () => {
+            let failed;
             try {
                 await conversationHostingMaintenanceDrain;
             }
             finally {
                 await hostedConversationRuntime?.dispose().catch(() => undefined);
-                await drains;
+                const results = await drains;
                 await this.gitExecutionService?.close();
                 this.usageOutbox?.disconnected();
                 this.usageOutbox = undefined;
                 this.modelUsage.clear();
                 database?.close();
+                failed = results.find((result) => result.status === 'rejected');
             }
+            if (failed !== undefined)
+                throw failed.reason;
         })();
-        return this.stopping;
     }
     /** @internal Thin compatibility delegates; all behavior remains in the extracted services. */
     handleMessage = (raw) => this.controlMessages.handle(raw);
@@ -2375,12 +2452,30 @@ export class NodeConnector {
     startCapabilityRefresh = () => this.connectionLifecycle.startCapabilityRefresh();
     refreshCapabilities = () => this.connectionLifecycle.refreshCapabilities();
     async executeNodeOperation(operation, data) {
+        if (this.stopped)
+            throw new Error('NODE_STOPPED');
+        const input = isPlainRecord(data) ? data : {};
+        const sessionId = typeof input.sessionId === 'string' ? input.sessionId : undefined;
+        if (this.restartHandoff.blocksOperation(operation, input))
+            throw new Error('SESSION_RESTART_PENDING');
         if (this.database === undefined)
             throw new Error('NODE_DATABASE_UNAVAILABLE');
         if (this.upgradeCoordinator.blocks(operation))
             throw new Error('NODE_UPGRADE_PENDING');
         nodeLog('node.operation', { nodeId: this.config?.nodeId, operation });
-        return this.gitOperationService.execute(operation, data, (input) => this.operationRouter.execute(operation, input));
+        const task = this.gitOperationService.execute(operation, data, (input) => this.operationRouter.execute(operation, input));
+        this.inFlightOperations.add(task);
+        try {
+            const result = await task;
+            if ((operation === 'session.command.execute' || operation === 'session.message') &&
+                sessionId !== undefined &&
+                Number.isSafeInteger(input.__requestUserId))
+                this.restartHandoff.rememberUser(sessionId, input.__requestUserId);
+            return result;
+        }
+        finally {
+            this.inFlightOperations.delete(task);
+        }
     }
     gitExecution() {
         this.gitExecutionService ??= new GitExecutionService({

package/dist/database.js

@@ -1,5 +1,6 @@
 import { NODE_SCHEMA_MIGRATION_V17 } from './migrations/v017.js';
 import { NODE_SCHEMA_MIGRATION_V18 } from './migrations/v018.js';
+import { NODE_SCHEMA_MIGRATION_V19 } from './migrations/v019.js';
 import { normalizeSessionPrompt } from './util/personal-instructions.js';
 import { randomUUID } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, rmSync } from 'node:fs';
@@ -19,7 +20,8 @@ export const NODE_SCHEMA_MIGRATIONS = [
     NODE_SCHEMA_MIGRATION_V15,
     NODE_SCHEMA_MIGRATION_V16,
     NODE_SCHEMA_MIGRATION_V17,
-    NODE_SCHEMA_MIGRATION_V18
+    NODE_SCHEMA_MIGRATION_V18,
+    NODE_SCHEMA_MIGRATION_V19
 ];
 const LEGACY_NODE_SCHEMA_V12 = NODE_SCHEMA_VERSION_V13 - 1;
 const OBSOLETE_NODE_SCHEMA_V16 = 16;
@@ -288,8 +290,10 @@ export class NodeDatabase {
         const model = input.model === undefined ? (current?.model ?? null) : input.model;
         const effort = input.effort === undefined ? (current?.effort ?? null) : input.effort;
         const access = input.access === undefined ? (current?.access ?? null) : input.access;
+        const parentSessionId = current?.parentSessionId ?? input.parentSessionId ?? null;
         const metadata = JSON.stringify({
             version: 1,
+            parentSessionId,
             customTitle,
             sessionPrompt,
             runnerTitle,
@@ -328,6 +332,7 @@ export class NodeDatabase {
         }
         return {
             customTitle,
+            parentSessionId,
             sessionPrompt,
             runnerTitle,
             runnerTitlePending,
@@ -341,17 +346,13 @@ export class NodeDatabase {
     listSessionRecords(workspaceId) {
         return this.raw
             .prepare('SELECT id, workspace_id, runner, pin_order, metadata FROM agent_sessions WHERE workspace_id = ? ORDER BY pin_order IS NULL, pin_order, id')
-            .all(workspaceId).map((row) => ({
-            id: stringValue(row, 'id'),
-            workspaceId: stringValue(row, 'workspace_id'),
-            runner: stringValue(row, 'runner'),
-            pinOrder: nullableNumber(row, 'pin_order'),
-            metadata: {
-                ...sessionMetadata(row),
-                pinnedAt: row['pin_order'] === null ? null : 1,
-                pinOrder: nullableNumber(row, 'pin_order')
-            }
-        }));
+            .all(workspaceId).map(sessionRecord);
+    }
+    getSessionRecord(sessionId) {
+        const row = this.raw
+            .prepare('SELECT id, workspace_id, runner, pin_order, metadata FROM agent_sessions WHERE id = ?')
+            .get(sessionId);
+        return row === undefined ? undefined : sessionRecord(row);
     }
     movePinnedSession(sessionId, direction) {
         const current = this.raw
@@ -565,6 +566,19 @@ function mcpInstallation(row) {
         installedAt: numberValue(row, 'installed_at')
     };
 }
+function sessionRecord(row) {
+    return {
+        id: stringValue(row, 'id'),
+        workspaceId: stringValue(row, 'workspace_id'),
+        runner: stringValue(row, 'runner'),
+        pinOrder: nullableNumber(row, 'pin_order'),
+        metadata: {
+            ...sessionMetadata(row),
+            pinnedAt: row['pin_order'] === null ? null : 1,
+            pinOrder: nullableNumber(row, 'pin_order')
+        }
+    };
+}
 function sessionMetadata(row) {
     const raw = JSON.parse(stringValue(row, 'metadata'));
     if (raw['version'] !== 1)
@@ -572,6 +586,7 @@ function sessionMetadata(row) {
     const value = (key) => typeof raw[key] === 'string' ? raw[key] : null;
     return {
         customTitle: value('customTitle'),
+        parentSessionId: value('parentSessionId'),
         sessionPrompt: value('sessionPrompt'),
         runnerTitle: value('runnerTitle'),
         runnerTitlePending: raw['runnerTitlePending'] === true,

package/dist/main.js

@@ -7,6 +7,7 @@ import { getNodeHealth } from './health.js';
 import { browserCachePath, removeServiceDefinition, writeServiceDefinition } from './service.js';
 import { superviseNode } from './supervisor.js';
 import { configureNodeLog } from './rotating-log.js';
+import { nodeLog } from './operational.js';
 const [command = 'status', ...args] = process.argv.slice(2);
 const config = readOption(args, '--config') ?? nodeConfigPath();
 const output = readOption(args, '--output') ?? defaultServicePath();
@@ -17,11 +18,26 @@ if (command === 'run') {
     const { NodeConnector } = await import('./connector.js');
     configureNodeLog(nodeDataDirectory(await loadNodeConfig(config), config));
     const connector = new NodeConnector({ configPath: config });
+    let shuttingDown = false;
     const shutdown = () => {
-        void connector.stop().finally(() => process.exit(0));
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        const deadline = setTimeout(() => {
+            nodeLog('node.restart.diagnostic', { code: 'RESTART_HANDOFF_SHUTDOWN_TIMEOUT' });
+            process.exit(1);
+        }, 25_000);
+        void connector.stop({ handoff: true }).then(() => {
+            clearTimeout(deadline);
+            process.exit(0);
+        }, () => {
+            clearTimeout(deadline);
+            nodeLog('node.restart.diagnostic', { code: 'RESTART_HANDOFF_SHUTDOWN_FAILED' });
+            process.exit(1);
+        });
     };
     for (const signal of ['SIGINT', 'SIGTERM']) {
-        process.once(signal, shutdown);
+        process.on(signal, shutdown);
     }
     await connector.start();
 }

package/dist/migrations/v019.js

@@ -0,0 +1,9 @@
+import { NODE_SCHEMA_MIGRATION_V18 } from './v018.js';
+export const NODE_SCHEMA_MIGRATION_V19 = {
+    version: 19,
+    sql: `UPDATE agent_sessions
+    SET metadata = json_set(metadata, '$.parentSessionId', NULL)
+    WHERE json_type(metadata, '$.parentSessionId') IS NULL;`,
+    preflight: (database) => NODE_SCHEMA_MIGRATION_V18.assert(database),
+    assert: (database) => NODE_SCHEMA_MIGRATION_V18.assert(database)
+};

package/dist/runner/mar-agent/conversation-normalizer.js

@@ -579,6 +579,34 @@ function genericToolItem(id, toolName, status, input, outputSummary = null, erro
             truncated: truncated || source.length > 10_000 || output.length > 10_000
         }, status);
     }
+    if (toolName === 'code_exec_wait') {
+        const inputRecord = record(input);
+        const action = typeof inputRecord?.action === 'string' ? inputRecord.action : 'poll';
+        const inputSummary = compactRunnerValue(input, 10_000);
+        const result = output === undefined ? null : compactRunnerValue(output, 10_000);
+        const resultSummary = [outputSummary, result?.text]
+            .filter((value, index, values) => typeof value === 'string' && value.length > 0 && values.indexOf(value) === index)
+            .join('\n');
+        const details = [
+            `Action: ${compactRunnerText(action, 128)}`,
+            `Input: ${inputSummary.text || '{}'}`,
+            resultSummary.length === 0 ? '' : `Result: ${compactRunnerText(resultSummary, 10_000)}`,
+            errorCode === null ? '' : `Error: ${compactRunnerText(errorCode, 80)}`
+        ]
+            .filter(Boolean)
+            .join('\n');
+        return commandItem({
+            itemId: id,
+            command: toolName,
+            cwd: null,
+            outputPreview: details,
+            exitCode: null,
+            truncated: truncated ||
+                inputSummary.truncated ||
+                result?.truncated === true ||
+                resultSummary.length > 10_000
+        }, status);
+    }
     const subagent = marAgentSubagentProjection(toolName, input, output, subagentTitle, knownSubagentDetails);
     const toolCategory = isImageGenerationTool(toolName) ? 'IMAGE_GENERATION' : undefined;
     const inputSummary = compactRunnerValue(input, 10_000);

package/dist/runner/mar-agent/marctl-skill.js

@@ -18,18 +18,20 @@ export function marctlHostSkill(environment = {}) {
 const marctlInstructions = [
     '## MAR Workspace CLI',
     'Use exec to run marctl. Reuse loaded guidance while it remains in context. Consult local marctl help sessions for unclear options and marctl --version when version matters; neither needs a network request. Capabilities and permissions still apply.',
-    'Use sessions current --json only when the current identity or scope is unknown. For a known target ID, use sessions show <session-id> --json only when fresh state is needed, without current/list first. Use sessions list --limit 10 --json to discover an unknown target; list has no name-search option. Stop once found and follow nextCursor only if needed. Do not scan the Workspace to prove capacity: check assigned work, recorded worker IDs and overlapping write scopes.',
+    'Use sessions current --json only when the current identity or scope is unknown. For a known target ID, use sessions show <session-id> --json only when fresh state is needed, without current/list first. Use sessions list --limit 10 --json to discover an unknown target; narrow with --query <title> or --parent <session-id>. These query Node-known Sessions without scanning Runners. Use sessions graph <session-id> --json only for a creation tree (bounded to 100 nodes with truncated); start automatically records the current Session as parent, not task ownership. Stop once found and follow nextCursor only if needed. Do not scan the Workspace to prove capacity: check assigned work, recorded worker IDs and overlapping write scopes.',
     'MAR binds sessions to the current Node and Workspace. No --node or --workspace override exists. Use returned native Session IDs, not titles, for later operations. A Workspace terminal may have no current Session. Missing scope, an old Node, expired authorization or an unavailable Runner is an explicit error, not permission to bypass the API.',
     '## Create and coordinate independent Sessions',
+    'Change an existing Session with sessions config <session-id> --model <id> --effort high --json; either option can be set alone. Use show for current settings; active execution is not restarted.',
     'Prefer -m / --message for short text; use --message-file for longer UTF-8 text or an existing file (- reads stdin). These options are mutually exclusive. Example: marctl sessions start --runner codex --title "fixer#42 Handle empty totals" -m "Implement issue #42 and report test evidence" --json. Other Runner names are mar-agent, claude-code and opencode. An omitted model uses the target Runner configuration, not the Coordinator model.',
     'For start/send, repeat --image <local-path> to attach PNG, JPEG, GIF or WebP images, with or without text. Images are read on this CLI host, not by remote path. Limits: 5 images, 5 MiB each, 10 MiB total. Actual Runner/model image capabilities apply; goal set accepts text only.',
-    'Create workers only as tasks need them, named fixer#<task-id> <description> or reviewer#<task-or-change-id> <description>. These are conventions, not product roles or a fixed pool. Put role, scope, acceptance criteria and delivery requirements in the first message. Session Prompt is edited in the Web UI only; marctl has no editing command, and sends to existing Sessions use normal prompt injection.',
-    'Reuse recorded Session/Run IDs and receipts. Refresh volatile Run, queue and Goal state with sessions show only when the next action depends on it. For results use sessions history <session-id> --limit 10 --json; follow nextCursor only for missing evidence. Select needed JSON fields and relevant assistant results instead of dumping full Session lists or tool transcripts. Hidden reasoning, credentials and raw model requests are not collaboration artifacts.',
-    'Send with sessions send <session-id> -m "Review the updated patch" --json. Default send does not interrupt and can resume a paused queue; --delivery queue preserves a paused queue. Otherwise eligible queued input can start when idle. --delivery replace-current cancels the current Run and prioritizes the new input after release; it is not live steering. There are no queue-item edit/delete/reorder commands; show includes queue state. start/send return clientMessageId and the accepted/queued result. A queued result may refer to the currently active Run: associate queueItemId/clientMessageId with history before deciding that input finished.',
+    'Create workers only as tasks need them, named fixer#<task-id> <description> or reviewer#<task-or-change-id> <description>. These are conventions, not product roles or a fixed pool. Put role, scope, acceptance criteria and delivery requirements in the first message. Follow the repository workflow for development and review. Session Prompt is edited in the Web UI only; marctl has no editing command, and sends to existing Sessions use normal prompt injection.',
+    'Reuse recorded Session/Run IDs and receipts. Refresh volatile Run, queue and Goal state with sessions show only when the next action depends on it. Select needed JSON fields instead of dumping full Session lists or tool transcripts. Hidden reasoning, credentials and raw model requests are not collaboration artifacts.',
+    'Read results with sessions history <session-id> --limit 10 --json (default: latest 10 SEGMENTs, not messages; --limit 1..100). Extract needed assistant_message payload.text from segments[].items[]; keep segment runId and user_message.payload.clientMessageId for queued-input correlation. Reuse the returned page; follow --cursor <nextCursor> only for missing evidence.',
+    'Send urgent corrections with sessions send <session-id> --forced -m "Use the corrected acceptance criteria" --json. Always choose exactly one of --forced or --queue, even when idle; missing or conflicting modes are rejected locally. --forced inserts: send immediately when idle; if busy, interrupt the current execution and prioritize the new input after release, not live steering. Use --queue to wait for an eligible FIFO turn without interrupting or resuming a paused queue; eligible input can start immediately when idle. For non-urgent follow-ups, use sessions send <session-id> --queue -m "Include test evidence" --json. There are no queue-item edit/delete/reorder commands; show includes queue state. start/send return clientMessageId and the accepted/queued result. A queued result may refer to the currently active Run: associate queueItemId/clientMessageId with history before deciding that input finished.',
     'Wait with sessions wait <session-id> --run <run-id> --timeout 5m --json through the existing Watch. Prefer --timeout 5m when blocked on task completion; use 30s for a short deadline. Continue useful independent work before waiting. If exec returns a running process or cell, reuse its process/cell handle rather than starting another wait or polling show/list. Timeout or cancelled waiting does not stop the task. Use sessions stop <session-id> --run <run-id> --json only to stop that active Run; ownership rules still apply.',
     'Goal get/set/clear use the existing Session Goal semantics; see marctl help sessions. A Coordinator can work from ordinary messages or its existing schedule without a Goal. Worker completion never automatically wakes it. Actively wait/read results, or finish and reconcile on the next user message or scheduled input.',
     '## Verify, recover and respect authorization',
-    'An accepted message or SUCCEEDED Run is not proof of business completion. Inspect artifacts and test evidence. If review finds a defect, send a focused correction to the recorded Fixer Session, then request another review with the recorded Reviewer ID.',
+    'An accepted message or SUCCEEDED Run is not proof of business completion. Inspect artifacts and test evidence.',
     'Network loss can leave a mutation outcome unknown. Preserve the reported clientMessageId and inspect current state/history before retrying; do not blindly resend or create another Session. Server/Node restart does not guarantee recovery of in-memory Runs or queues.',
     'MAR injects user credentials for 24 hours from issue, without automatic renewal. Never print, copy into task files or persist authorization environment values. CLI calls use the real initiating user, including scheduled provenance; worker roles do not elevate access or inherit an auto-approval mode.',
     'Sessions share Workspace files and the Git index. Agree on non-overlapping changes and respect repository locking rules. There is no automatic worktree isolation, workflow engine, reliable callback or completion receipt store.',

package/dist/runner/mar-agent-runner.js

@@ -369,6 +369,38 @@ export class MarAgentRunner extends AbstractRunner {
             await catalog.close().catch(() => undefined);
         }
     }
+    async restartInputState(sessionId, clientMessageId) {
+        const catalog = await openMarAgentSessionCatalog({ homeDirectory: this.homeDirectory });
+        try {
+            let cursor;
+            const states = new Map();
+            do {
+                const page = await catalog.history(sessionId, {
+                    ...(cursor === undefined ? {} : { cursor }),
+                    limit: 1000
+                });
+                for (const entry of page.entries) {
+                    if (entry.kind !== 'event' || entry.event.turnId === undefined)
+                        continue;
+                    const event = entry.event;
+                    if (event.type === 'execution.completed')
+                        states.set(event.turnId, event.permissionStop === undefined ? 'completed' : 'paused');
+                    else if (event.type === 'execution.failed')
+                        states.set(event.turnId, 'completed');
+                    else if (event.type === 'execution.cancelled')
+                        states.set(event.turnId, 'interrupted');
+                }
+                const user = page.entries.find((entry) => entry.kind === 'user' && entry.clientMessageId === clientMessageId);
+                if (user?.kind === 'user')
+                    return states.get(user.turnId) ?? 'interrupted';
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            return 'missing';
+        }
+        finally {
+            await catalog.close();
+        }
+    }
     async readOfficialConversation(session, input) {
         if (session.externalSessionId === null)
             return undefined;

package/dist/runtime-state.js

@@ -84,6 +84,7 @@ export class NodeRuntimeState {
             // A first user prompt is only a process-local temporary title. A
             // Runner/native title can replace it on the next discovery refresh.
             titleSource: customTitle === null ? 'AUTO' : 'CUSTOM',
+            parentSessionId: input.parentSessionId ?? null,
             lastActivityAt: input.lastActivityAt ?? now,
             createdAt: input.createdAt ?? now
         };
@@ -163,9 +164,9 @@ export class NodeRuntimeState {
     }
     updateAgentSessionConfiguration(input) {
         return this.replaceSession(input.sessionId, {
-            model: input.model,
-            effort: input.effort,
-            access: input.access
+            ...(input.model === undefined ? {} : { model: input.model }),
+            ...(input.effort === undefined ? {} : { effort: input.effort }),
+            ...(input.access === undefined ? {} : { access: input.access })
         });
     }
     updateAgentSessionAccess(sessionId, access) {
@@ -338,6 +339,7 @@ export class NodeRuntimeState {
             version: 0,
             clientMessageId: input.clientMessageId,
             ...(input.source === undefined ? {} : { source: input.source }),
+            ...(input.suppressNotifications === true ? { suppressNotifications: true } : {}),
             ...(input.initiatedByUserId === undefined
                 ? {}
                 : { initiatedByUserId: input.initiatedByUserId }),
@@ -416,6 +418,7 @@ export class NodeRuntimeState {
             runner: session.runner,
             clientMessageId: input.clientMessageId,
             content: input.content,
+            ...(input.suppressNotifications === true ? { suppressNotifications: true } : {}),
             attachments: input.attachments ?? [],
             ...(input.initiatedByUserId === undefined
                 ? {}
@@ -449,11 +452,14 @@ export class NodeRuntimeState {
         if (itemId === undefined)
             return undefined;
         const item = this.requireQueueItem(itemId);
-        const run = active.initiatedByUserId === undefined && item.initiatedByUserId !== undefined
-            ? { ...active, initiatedByUserId: item.initiatedByUserId }
-            : active;
-        if (run !== active)
-            this.runs.set(run.id, run);
+        const run = {
+            ...active,
+            ...(active.initiatedByUserId === undefined && item.initiatedByUserId !== undefined
+                ? { initiatedByUserId: item.initiatedByUserId }
+                : {}),
+            suppressNotifications: item.suppressNotifications === true
+        };
+        this.runs.set(run.id, run);
         this.queuedItems.set(sessionId, queue.slice(1));
         this.bumpQueueVersion(sessionId);
         this.queueItems.delete(itemId);
@@ -482,6 +488,7 @@ export class NodeRuntimeState {
             clientMessageId: item.clientMessageId,
             content: content ?? item.content,
             recentUserMessage: item.content,
+            ...(item.suppressNotifications === true ? { suppressNotifications: true } : {}),
             ...(item.attachments.length === 0 ? {} : { attachments: item.attachments }),
             ...(item.initiatedByUserId === undefined ? {} : { initiatedByUserId: item.initiatedByUserId })
         });
@@ -607,8 +614,6 @@ export class NodeRuntimeState {
             return { kind: 'run', run: this.requireRun(submission.id) };
         const item = this.requireQueueItem(submission.id);
         const run = this.activeSessionRun(sessionId);
-        if (run === undefined)
-            throw new Error('RUN_NOT_FOUND');
         return { kind: 'queue', item, run };
     }
     messagePreparationFailure(sessionId, clientMessageId) {