@myagentroam/node 0.12.4 → 0.12.5

package/dist/application/scheduled-execution-service.js

@@ -0,0 +1,60 @@
+/** Prepares and submits scheduled input through existing Session/Runner owners.
+ * The scheduler retains occurrence state, admission, in-flight work and terminal settlement;
+ * this application service owns no timers or alternate execution pipeline.
+ */
+export class ScheduledExecutionService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    authorize = async (task, occurrenceId) => {
+        const session = this.options.runtime.getAgentSession(task.sessionId) ??
+            (await this.options.projection.resolveCurrent(task.sessionId));
+        if (session === undefined ||
+            session.workspaceId !== task.workspaceId ||
+            session.runner !== task.runner)
+            throw new Error('SCHEDULE_SESSION_NOT_FOUND');
+        const configured = this.options.projection.ensureResumedConfiguration(session);
+        const context = await this.options.authorization.authorize({
+            taskId: task.id,
+            revision: task.revision,
+            occurrenceId,
+            sessionId: task.sessionId,
+            workspaceId: task.workspaceId,
+            ownerUserId: task.ownerUserId,
+            runner: task.runner,
+            modelId: configured.modelId
+        });
+        return {
+            ...(context.gitConfiguration === undefined
+                ? {}
+                : { gitConfiguration: context.gitConfiguration }),
+            secretEnvironment: context.secretEnvironment,
+            personalInstructions: context.personalInstructions,
+            usageGrant: context.usageGrant,
+            executionContext: this.options.runners.require(task.runner).prepareExecutionContext(context)
+        };
+    };
+    submit = async (task, occurrenceId, context) => {
+        const result = (await this.options.git.execute('session.message', {
+            sessionId: task.sessionId,
+            workspaceId: task.workspaceId,
+            __requestUserId: task.ownerUserId,
+            secretEnvironment: context.secretEnvironment,
+            ...(context.gitConfiguration === undefined
+                ? {}
+                : { gitConfiguration: context.gitConfiguration })
+        }, async (data) => this.options.messages.submitScheduled({
+            sessionId: task.sessionId,
+            occurrenceId,
+            objective: task.objective,
+            initiatedByUserId: task.ownerUserId,
+            secretEnvironment: data
+                .secretEnvironment,
+            personalInstructions: context.personalInstructions,
+            ...(context.usageGrant === undefined ? {} : { usageGrant: context.usageGrant }),
+            executionContext: context.executionContext
+        })));
+        return { runId: result.run.id };
+    };
+}

package/dist/connector.js

@@ -6,6 +6,7 @@ import { ExecutionLifecycle } from './application/execution-lifecycle.js';
 import { NodeOperationAdmission } from './application/node-operation-admission.js';
 import { normalizeMarAgentUsage } from './runner/mar-agent/conversation-normalizer.js';
 import { NodeLifecycle } from './application/node-lifecycle.js';
+import { ScheduledExecutionService } from './application/scheduled-execution-service.js';
 import { isImageAttachment } from './session/attachments.js';
 import { ModelUsageOutbox } from './service/model-usage-outbox.js';
 import { NodeModelUsageService } from './service/model-usage-service.js';
@@ -24,7 +25,8 @@ import { CommandStateStore } from './runner-command-engine.js';
 import { GoalRuntime } from './service/goal-runtime.js';
 import { GoalContinuationCoordinator } from './service/goal-continuation-coordinator.js';
 import { GoalMcpBridge } from './service/goal-mcp-bridge.js';
-import { AgentNetworkObservations, agentObservationFromRunEvent } from './service/agent-network-observations.js';
+import { AgentNetworkObservations } from './service/agent-network-observations.js';
+import { AgentNetworkRunProjection } from './service/agent-network-run-projection.js';
 import { createNodeAgentNetwork } from './service/agent-network-bindings.js';
 import { agentNetworkExecutionCommand, agentNetworkInvoke } from './service/agent-network-invoke.js';
 import { RunnerUsageReader } from './runner-usage.js';
@@ -54,7 +56,7 @@ import { SessionWatchSlotCoordinator } from './service/session-watch-slot-coordi
 import { SessionContextService } from './session/session-context-service.js';
 import { RunWorkbenchService } from './service/run-workbench-service.js';
 import { SessionQueryService } from './session/session-query-service.js';
-import { marctlSessionDetail, marctlSessionProgress } from './service/session-recent-activity.js';
+import { marctlSessionProgress } from './service/session-recent-activity.js';
 import { WorkspaceQueueWorkbenchService } from './workspace/workspace-queue-workbench-service.js';
 import { ContinuousRunCoordinator } from './service/continuous-run-coordinator.js';
 import { SessionIdentityService } from './session/session-identity-service.js';
@@ -154,6 +156,12 @@ const CONVERSATION_HOSTING_MAINTENANCE_OPERATIONS = [
 export function nextReconnectDelay(attempt) {
     return Math.min(RETRY_MAX_MS, RETRY_MIN_MS * 2 ** Math.min(Math.max(attempt, 0), 16));
 }
+/** Application composition and resource-lifetime root, not a domain workflow owner.
+ * Field initializers create local state/ports; the constructor creates domain owners, connects
+ * runtime event feedback, registers operations, then connects lifecycle. Callbacks for genuine
+ * Session/Workspace feedback are dormant until composition completes; start() activates resources.
+ * Session queries, Agent observations and execution preparation stay with their respective owners.
+ */
 export class NodeConnector {
     usageOutbox;
     modelUsage = new NodeModelUsageService(() => this.usageOutbox, () => this.config?.nodeId);
@@ -184,31 +192,7 @@ export class NodeConnector {
             throw new Error('NODE_CONFIG_UNAVAILABLE');
         return nodeDataDirectory(this.config, this.configPath);
     });
-    lifecycle = new NodeLifecycle(() => this.startResources(), () => {
-        this.continuousRunCoordinator.suspend();
-        this.goalCoordinator.freeze();
-        this.scheduledSessions.stop();
-    }, {
-        waitForRecovery: () => this.restartHandoff.wait(),
-        drainInput: async () => {
-            this.sessionMessageService.setAccepting(false);
-            await this.operationAdmission.drain();
-            await this.sessionMessageService.drain();
-        },
-        closeResume: () => this.externalSessionResumeService.close(),
-        capture: () => {
-            if (!this.config?.nodeId)
-                return;
-            return this.restartHandoff.capture();
-        },
-        dispose: () => this.disposeRuntime(),
-        publish: (snapshot) => this.restartHandoff.publish(snapshot),
-        diagnose: (stage, error) => nodeLog('node.shutdown.failed', {
-            stage,
-            errorCode: safeErrorCode(error, 'NODE_SHUTDOWN_FAILED'),
-            ...(stage === 'capture' ? plannedRestartCaptureDiagnostic(error) : undefined)
-        })
-    });
+    lifecycle;
     get stopped() {
         return this.lifecycle.stopped;
     }
@@ -323,24 +307,12 @@ export class NodeConnector {
     runnerUsageReader;
     terminalManager;
     upgradeCoordinator;
-    workspaceResources = composeWorkspaceResources({
-        discover: (workspaceId, onRunnerDiscovered) => this.discoverWorkspaceSessions(workspaceId, onRunnerDiscovered),
-        listPage: (workspaceId) => this.executeNodeOperation('session.list', { workspaceId, limit: 30 }),
-        invalidateSessions: (workspaceId) => void this.workspaceWorkbenchService?.invalidateTopic(workspaceId, 'sessions'),
-        invalidateFiles: (workspaceId) => {
-            this.workspaceWorkbenchService?.invalidateWorkspaceFiles(workspaceId);
-            this.workspaceCoordinator.invalidate(workspaceId);
-        },
-        releaseWatch: (workspaceId) => this.workspaceWorkbenchService?.releaseWorkspace(workspaceId),
-        removeWatch: (watch) => this.workspaceWorkbenchService?.cancelFilePrewarm(watch),
-        temporaryRoot: () => this.attachmentTemporaryRoot(),
-        attachmentResource: (id, path) => this.runAttachmentService.fileResource(id, path)
-    });
-    workspaceWatchService = this.workspaceResources.watch;
-    workspaceSessionService = this.workspaceResources.sessions;
-    workspaceFileService = this.workspaceResources.files;
-    workspaceUploadService = this.workspaceResources.uploads;
-    invalidateWorkspaceFiles = this.workspaceResources.invalidateFiles;
+    workspaceResources;
+    workspaceWatchService;
+    workspaceSessionService;
+    workspaceFileService;
+    workspaceUploadService;
+    invalidateWorkspaceFiles;
     directTransferService;
     attachmentTemporaryRoot() {
         if (this.config === undefined)
@@ -354,109 +326,13 @@ export class NodeConnector {
     recentRunProjectionService = new RecentRunProjectionService((message) => this.send('recent-runs', message));
     /** Runtime/session state is intentionally not persisted to Node SQLite. */
     runtime = new NodeRuntimeState(() => this.config?.nodeId ?? 'runtime-node', (workspaceId) => this.database?.getWorkspace(workspaceId), Date.now, (run, session, userMessage) => this.recentRunProjectionService.record(run, session, userMessage));
-    goalCoordinator = new GoalContinuationCoordinator({
-        goals: this.goalRuntime,
-        runners: () => this.runners,
-        runtime: this.runtime,
-        commands: this.commandStates,
-        queue: () => this.continuousRunCoordinator,
-        submit: (input) => this.sessionMessageService.submitGoal(input),
-        emitRun: (...args) => this.runEventBridge.emitRun(...args),
-        present: (session) => this.sessionPresentationService.present(session),
-        emitSession: (session) => this.emitSessionWorkbenchEvent({ session: this.sessionPresentationService.present(session) }),
-        database: () => this.database
-    });
+    goalCoordinator;
     metrics = new NodeMetrics();
     agentNetworkObservations = new AgentNetworkObservations();
-    transientAgentObservers = new Map();
-    runEventService = new RunEventService({
-        runtime: this.runtime,
-        metrics: this.metrics,
-        isBootstrapSession: (sessionId) => this.sessionIdentityService.bootstrapIds.has(sessionId),
-        presentSession: (session) => this.sessionPresentationService.present(session),
-        rejectBootstrap: (sessionId, code) => this.sessionIdentityService.reject(sessionId, code),
-        emitWorkbench: (category, payload) => this.publishWorkbenchEvent(category, payload),
-        cleanupAttachments: (runId) => this.runAttachmentService.cleanup(runId),
-        refreshAttachments: (sessionId) => this.runAttachmentService.refreshSession(sessionId),
-        expireImages: (runId) => this.runAttachmentService.expire(runId),
-        scheduleContextRefresh: (sessionId) => this.sessionContextService.schedule(sessionId),
-        refreshWorkspaceSessions: (workspaceId) => this.workspaceWorkbenchService.ensureTopicSnapshot(workspaceId, 'sessions'),
-        onTerminalRun: (run, status) => this.executionLifecycle.terminal(run, status),
-        observeAgentEvent: ({ run, executionId, eventType, payload, terminalStatus }) => {
-            const child = this.runtime.getAgentSession(run.sessionId);
-            if (!child)
-                return;
-            const parent = child.parentSessionId == null
-                ? undefined
-                : this.runtime.getAgentSession(child.parentSessionId);
-            let observation = agentObservationFromRunEvent({ eventType, payload, terminalStatus });
-            if (eventType === 'approval.request') {
-                const approvals = marctlSessionDetail(this.runtime, child, 0).pendingApprovals;
-                if (approvals.length)
-                    observation = {
-                        kind: 'message',
-                        value: JSON.stringify({
-                            pendingApprovals: approvals
-                        })
-                    };
-            }
-            if (observation)
-                this.agentNetworkObservations.publishChild({
-                    ...(parent?.workspaceId === child.workspaceId ? { parentId: parent.id } : {}),
-                    childId: child.id,
-                    runId: run.id,
-                    executionId,
-                    ...observation
-                });
-            if (terminalStatus !== undefined &&
-                this.transientAgentObservers.get(run.sessionId) === run.id) {
-                this.transientAgentObservers.delete(run.sessionId);
-                this.agentNetworkObservations.get(run.sessionId)?.close();
-            }
-        },
-        dispatchQueue: (sessionId, delayMs) => this.executionLifecycle.dispatchQueue(sessionId, delayMs),
-        executionStarted: (executionId) => this.continuousRunCoordinator.executionStarted(executionId),
-        acceptExecutionTerminal: (input) => this.continuousRunCoordinator.acceptExecutionTerminal(input),
-        publishGoalUpdate: ({ session, goal }) => this.goalCoordinator.publishGoalState(session, goal),
-        publishQueueChange: (sessionId) => this.continuousRunCoordinator.publish(sessionId),
-        releaseExecution: (executionId) => this.executionLifecycle.release(executionId)
-    });
+    agentNetworkProjection;
+    runEventService;
     sessionWatchSlots = new SessionWatchSlotCoordinator();
-    nativeSessionWatchService = new NativeSessionWatchService({
-        resolve: async (sessionId) => this.runtime.getAgentSession(sessionId) ??
-            this.nativeSessionProjectionService.resolveCurrent(sessionId),
-        managedActive: (session) => hasManagedActiveRun(this.runtime, session),
-        suspended: (sessionId) => this.externalSessionResumeService.transitioning(sessionId),
-        refreshActivity: (session) => this.conversationHistoryService.refreshExternalActivity(session),
-        present: (session) => this.sessionPresentationService.present(session),
-        readPage: (session, limit) => this.conversationHistoryService.read(session, { limit }),
-        readHistoryPage: (session, limit) => this.conversationHistoryService.readHistoryPage(session, { limit }),
-        projectInitialPage: (session, page, _unit, limit) => {
-            const context = this.sessionContextService.snapshot(session.id);
-            this.sessionContextService.schedule(session);
-            return {
-                kind: 'session-watch-snapshot',
-                sequence: this.workbenchEventService.snapshotSequence(),
-                session: this.sessionPresentationService.present(session),
-                runs: this.runtime.listRunsForSession(session.id, { includeTerminal: true }),
-                progress: marctlSessionProgress(this.runtime, session.id),
-                performance: this.runtime.sessionPerformance(session.id),
-                queue: this.workspaceQueueWorkbenchService.snapshot(session.id),
-                context,
-                conversation: this.conversationSegmentService.projectInitial(session, page, limit)
-            };
-        },
-        emitSession: (session) => this.emitSessionWorkbenchEvent({ session }),
-        emitPage: (session, page) => this.emitWorkbenchEvent('conversation', {
-            sessionId: session.id,
-            snapshot: this.conversationSegmentService.projectInitial(session, page, 3)
-        }),
-        nodeId: () => this.config?.nodeId ?? 'runtime-node',
-        nodeGeneration: () => this.nodeGeneration,
-        emitWatchEvent: (payload) => this.send('watch.event', payload),
-        sessionWatchSlots: this.sessionWatchSlots,
-        log: nodeLog
-    });
+    nativeSessionWatchService;
     constructor(options = {}) {
         this.config = options.config;
         this.configPath = options.configPath;
@@ -1076,6 +952,100 @@ export class NodeConnector {
             goal: (input) => this.goalCoordinator.start(input),
             clearGoal: (session) => this.goalCoordinator.clear(session)
         });
+        this.nativeSessionWatchService = new NativeSessionWatchService({
+            resolve: async (sessionId) => this.runtime.getAgentSession(sessionId) ??
+                this.nativeSessionProjectionService.resolveCurrent(sessionId),
+            managedActive: (session) => hasManagedActiveRun(this.runtime, session),
+            suspended: (sessionId) => this.externalSessionResumeService.transitioning(sessionId),
+            refreshActivity: (session) => this.conversationHistoryService.refreshExternalActivity(session),
+            present: (session) => this.sessionPresentationService.present(session),
+            readPage: (session, limit) => this.conversationHistoryService.read(session, { limit }),
+            readHistoryPage: (session, limit) => this.conversationHistoryService.readHistoryPage(session, { limit }),
+            projectInitialPage: (session, page, _unit, limit) => {
+                const context = this.sessionContextService.snapshot(session.id);
+                this.sessionContextService.schedule(session);
+                return {
+                    kind: 'session-watch-snapshot',
+                    sequence: this.workbenchEventService.snapshotSequence(),
+                    session: this.sessionPresentationService.present(session),
+                    runs: this.runtime.listRunsForSession(session.id, { includeTerminal: true }),
+                    progress: marctlSessionProgress(this.runtime, session.id),
+                    performance: this.runtime.sessionPerformance(session.id),
+                    queue: this.workspaceQueueWorkbenchService.snapshot(session.id),
+                    context,
+                    conversation: this.conversationSegmentService.projectInitial(session, page, limit)
+                };
+            },
+            emitSession: (session) => this.emitSessionWorkbenchEvent({ session }),
+            emitPage: (session, page) => this.emitWorkbenchEvent('conversation', {
+                sessionId: session.id,
+                snapshot: this.conversationSegmentService.projectInitial(session, page, 3)
+            }),
+            nodeId: () => this.config?.nodeId ?? 'runtime-node',
+            nodeGeneration: () => this.nodeGeneration,
+            emitWatchEvent: (payload) => this.send('watch.event', payload),
+            sessionWatchSlots: this.sessionWatchSlots,
+            log: nodeLog
+        });
+        // Create the Session query owner, then connect its Workspace cache/observation ports below.
+        this.sessionCatalogService = new SessionCatalogService({
+            resolveExecutionDirectory,
+            database: () => {
+                if (this.database === undefined)
+                    throw new Error('NODE_DATABASE_UNAVAILABLE');
+                return this.database;
+            },
+            nodeId: () => this.config?.nodeId ?? 'recorded-session',
+            runtime: this.runtime,
+            runners: this.runners,
+            runnerAvailable: (runner) => this.runners.require(runner).available(this.capabilities),
+            projection: this.nativeSessionProjectionService,
+            cachedNative: () => this.nativeSessionProjectionService.cachedNative(),
+            cachedWorkspace: (workspaceId) => this.workspaceSessionService.cached(workspaceId),
+            discoveryPending: (workspaceId) => this.workspaceSessionService.discoveryPending(workspaceId),
+            discoverWorkspace: (workspaceId, cleanup) => this.nativeSessionProjectionService.discoverWorkspace(workspaceId, undefined, cleanup),
+            present: (session) => this.sessionPresentationService.present(session),
+            nativeIds: (session) => this.nativeSessionProjectionService.nativeIds(session),
+            forget: (session, nativeIds) => {
+                this.nativeSessionProjectionService.forget(session, nativeIds);
+                this.promptCompletion.invalidateSession(session.workspaceId, session.id);
+                void this.runAttachmentService.releaseSession(session.id);
+            },
+            refreshActivity: (session) => this.conversationHistoryService.refreshExternalActivity(session),
+            externalActivity: (sessionId) => this.externalSessionResumeService.activity(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);
+                this.promptCompletion.invalidateSession(workspaceId, sessionId);
+            },
+            invalidateWorkspaceSessions: (workspaceId) => {
+                this.workspaceSessionService.invalidateCache(workspaceId);
+                void this.workspaceWorkbenchService?.invalidateTopic(workspaceId, 'sessions');
+            },
+            emitSession: (session) => this.emitSessionWorkbenchEvent({
+                session: this.sessionPresentationService.present(session)
+            })
+        });
+        this.workspaceResources = composeWorkspaceResources({
+            discover: (workspaceId, onRunnerDiscovered) => this.discoverWorkspaceSessions(workspaceId, onRunnerDiscovered),
+            listPage: (workspaceId, group) => this.sessionCatalogService.listWorkspacePage(workspaceId, group),
+            invalidateSessions: (workspaceId) => void this.workspaceWorkbenchService?.invalidateTopic(workspaceId, 'sessions'),
+            invalidateFiles: (workspaceId) => {
+                this.workspaceWorkbenchService?.invalidateWorkspaceFiles(workspaceId);
+                this.workspaceCoordinator.invalidate(workspaceId);
+            },
+            releaseWatch: (workspaceId) => this.workspaceWorkbenchService?.releaseWorkspace(workspaceId),
+            removeWatch: (watch) => this.workspaceWorkbenchService?.cancelFilePrewarm(watch),
+            temporaryRoot: () => this.attachmentTemporaryRoot(),
+            attachmentResource: (id, path) => this.runAttachmentService.fileResource(id, path)
+        });
+        this.workspaceWatchService = this.workspaceResources.watch;
+        this.workspaceSessionService = this.workspaceResources.sessions;
+        this.workspaceFileService = this.workspaceResources.files;
+        this.workspaceUploadService = this.workspaceResources.uploads;
+        this.invalidateWorkspaceFiles = this.workspaceResources.invalidateFiles;
         this.sessionMessageService = new SessionMessageService({
             resolveExecutionDirectory,
             runtime: this.runtime,
@@ -1098,6 +1068,21 @@ export class NodeConnector {
             prepareGoalInsertion: (sessionId, submissionId, goal) => this.goalCoordinator.prepareInsertion(sessionId, submissionId, goal),
             goalPreparationFailed: (session, goal, activated) => this.goalCoordinator.handleGoalPreparationFailed(session, goal, activated)
         });
+        this.goalCoordinator = new GoalContinuationCoordinator({
+            goals: this.goalRuntime,
+            runners: () => this.runners,
+            runtime: this.runtime,
+            commands: this.commandStates,
+            queue: () => this.continuousRunCoordinator,
+            submit: (input) => this.sessionMessageService.submitGoal(input),
+            emitRun: (...args) => this.runEventBridge.emitRun(...args),
+            present: (session) => this.sessionPresentationService.present(session),
+            emitSession: (session) => this.emitSessionWorkbenchEvent({
+                session: this.sessionPresentationService.present(session)
+            }),
+            database: () => this.database
+        });
+        this.agentNetworkProjection = new AgentNetworkRunProjection(this.runtime, this.agentNetworkObservations);
         this.agentNetworkService = createNodeAgentNetwork({
             runtime: this.runtime,
             database: () => this.database,
@@ -1110,27 +1095,9 @@ export class NodeConnector {
             goals: this.goalRuntime,
             runs: this.runWorkbenchService,
             observations: this.agentNetworkObservations,
-            ensureObservations: (actor) => {
-                const existing = this.agentNetworkObservations.get(actor.observationId ?? actor.sessionId);
-                if (existing)
-                    return existing;
-                const run = actor.runId === undefined ? undefined : this.runtime.getRun(actor.runId);
-                if (!run ||
-                    run.sessionId !== actor.sessionId ||
-                    this.runtime.activeSessionRun(actor.sessionId)?.id !== run.id)
-                    throw new Error('AGENT_ACTOR_NOT_ACTIVE');
-                const observer = this.agentNetworkObservations.attach(actor.sessionId);
-                this.transientAgentObservers.set(actor.sessionId, run.id);
-                return observer;
-            },
+            ensureObservations: this.agentNetworkProjection.ensureObservations,
             withGrant: (actor, work) => this.modelUsage.withGrant(actor.usageGrant, work)
         });
-        this.operationRouter.register('agent.network', agentNetworkExecutionCommand({
-            runtime: this.runtime,
-            coordinator: this.continuousRunCoordinator,
-            service: this.agentNetworkService,
-            observations: this.agentNetworkObservations
-        }));
         const inputState = (entry, message) => this.marAgentClient.restartInputState(entry.session.id, message.clientMessageId);
         const restorer = new RestartSessionRestorer({
             runtime: this.runtime,
@@ -1187,46 +1154,7 @@ export class NodeConnector {
             restore: (entry, id) => restorer.restore(entry, id),
             diagnose: (code, sessionId, errorCode) => nodeLog('node.restart.diagnostic', { code, sessionId, errorCode })
         });
-        this.sessionCatalogService = new SessionCatalogService({
-            resolveExecutionDirectory,
-            database: () => {
-                if (this.database === undefined)
-                    throw new Error('NODE_DATABASE_UNAVAILABLE');
-                return this.database;
-            },
-            nodeId: () => this.config?.nodeId ?? 'recorded-session',
-            runtime: this.runtime,
-            runners: this.runners,
-            runnerAvailable: (runner) => this.runners.require(runner).available(this.capabilities),
-            projection: this.nativeSessionProjectionService,
-            cachedNative: () => this.nativeSessionProjectionService.cachedNative(),
-            cachedWorkspace: (workspaceId) => this.workspaceCoordinator.cachedSessions(workspaceId),
-            discoveryPending: (workspaceId) => this.workspaceSessionService.discoveryPending(workspaceId),
-            discoverWorkspace: (workspaceId, cleanup) => this.nativeSessionProjectionService.discoverWorkspace(workspaceId, undefined, cleanup),
-            present: (session) => this.sessionPresentationService.present(session),
-            nativeIds: (session) => this.nativeSessionProjectionService.nativeIds(session),
-            forget: (session, nativeIds) => {
-                this.nativeSessionProjectionService.forget(session, nativeIds);
-                this.promptCompletion.invalidateSession(session.workspaceId, session.id);
-                void this.runAttachmentService.releaseSession(session.id);
-            },
-            refreshActivity: (session) => this.conversationHistoryService.refreshExternalActivity(session),
-            externalActivity: (sessionId) => this.externalSessionResumeService.activity(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);
-                this.promptCompletion.invalidateSession(workspaceId, sessionId);
-            },
-            invalidateWorkspaceSessions: (workspaceId) => {
-                this.workspaceSessionService.invalidateCache(workspaceId);
-                void this.workspaceWorkbenchService?.invalidateTopic(workspaceId, 'sessions');
-            },
-            emitSession: (session) => this.emitSessionWorkbenchEvent({
-                session: this.sessionPresentationService.present(session)
-            })
-        });
+        // Connect Runner control feedback after Session owners and Workspace resources exist.
         this.codexClient.bindControl({
             start: (envelope) => this.codexRunController.start(envelope),
             cancel: (runId, intent) => {
@@ -1428,11 +1356,7 @@ export class NodeConnector {
             terminals: this.terminalManager,
             resources: this.workspaceResources,
             changes: this.workspaceChangeService,
-            listSessions: (workspaceId, sessionGroup) => this.executeNodeOperation('session.list', {
-                workspaceId,
-                limit: 30,
-                ...(sessionGroup === undefined ? {} : { sessionGroup })
-            }),
+            listSessions: (workspaceId, sessionGroup) => this.workspaceSessionService.listPage(workspaceId, sessionGroup),
             sessionNavigation: async (workspaceId, query) => this.sessionCatalogService.navigation({ workspaceId, ...query }),
             invalidatePrompt: (id) => this.promptCompletion?.invalidateWorkspace(id),
             nodeId: () => this.config?.nodeId ?? 'runtime-node',
@@ -1445,6 +1369,28 @@ export class NodeConnector {
         this.workspaceService = workspaceApplication.workspace;
         this.workspaceWorkbenchService = workspaceApplication.workbench;
         this.publishWorkspaceSession = workspaceApplication.publishSession;
+        // Connect normalized event projection and terminal feedback; no execution starts here.
+        this.runEventService = new RunEventService({
+            runtime: this.runtime,
+            metrics: this.metrics,
+            isBootstrapSession: (sessionId) => this.sessionIdentityService.bootstrapIds.has(sessionId),
+            presentSession: (session) => this.sessionPresentationService.present(session),
+            rejectBootstrap: (sessionId, code) => this.sessionIdentityService.reject(sessionId, code),
+            emitWorkbench: (category, payload) => this.publishWorkbenchEvent(category, payload),
+            cleanupAttachments: (runId) => this.runAttachmentService.cleanup(runId),
+            refreshAttachments: (sessionId) => this.runAttachmentService.refreshSession(sessionId),
+            expireImages: (runId) => this.runAttachmentService.expire(runId),
+            scheduleContextRefresh: (sessionId) => this.sessionContextService.schedule(sessionId),
+            refreshWorkspaceSessions: (workspaceId) => this.workspaceWorkbenchService.ensureTopicSnapshot(workspaceId, 'sessions'),
+            onTerminalRun: (run, status) => this.executionLifecycle.terminal(run, status),
+            observeAgentEvent: this.agentNetworkProjection.accept,
+            dispatchQueue: (sessionId, delayMs) => this.executionLifecycle.dispatchQueue(sessionId, delayMs),
+            executionStarted: (executionId) => this.continuousRunCoordinator.executionStarted(executionId),
+            acceptExecutionTerminal: (input) => this.continuousRunCoordinator.acceptExecutionTerminal(input),
+            publishGoalUpdate: ({ session, goal }) => this.goalCoordinator.publishGoalState(session, goal),
+            publishQueueChange: (sessionId) => this.continuousRunCoordinator.publish(sessionId),
+            releaseExecution: (executionId) => this.executionLifecycle.release(executionId)
+        });
         this.runEventBridge = new NodeRunEventBridge({
             bindModelUsage: (runId) => {
                 const run = this.runtime.getRun(runId);
@@ -1497,62 +1443,22 @@ export class NodeConnector {
             return this.database;
         };
         this.scheduledRunAuthorization = new RunAuthorizationControl((envelope) => this.controlChannel.sendEnvelope(envelope));
+        const scheduledExecution = new ScheduledExecutionService({
+            runtime: this.runtime,
+            projection: this.nativeSessionProjectionService,
+            authorization: this.scheduledRunAuthorization,
+            runners: this.runners,
+            git: this.gitOperationService,
+            messages: this.sessionMessageService
+        });
         this.scheduledSessions = new ScheduledSessionCoordinator({
             store: () => new ScheduledSessionStore(requireDatabase().raw),
             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) ??
-                    (await this.nativeSessionProjectionService.resolveCurrent(task.sessionId));
-                if (session === undefined ||
-                    session.workspaceId !== task.workspaceId ||
-                    session.runner !== task.runner)
-                    throw new Error('SCHEDULE_SESSION_NOT_FOUND');
-                const configuredSession = this.nativeSessionProjectionService.ensureResumedConfiguration(session);
-                const context = await this.scheduledRunAuthorization.authorize({
-                    taskId: task.id,
-                    revision: task.revision,
-                    occurrenceId,
-                    sessionId: task.sessionId,
-                    workspaceId: task.workspaceId,
-                    ownerUserId: task.ownerUserId,
-                    runner: task.runner,
-                    modelId: configuredSession.modelId
-                });
-                return {
-                    ...(context.gitConfiguration === undefined
-                        ? {}
-                        : { gitConfiguration: context.gitConfiguration }),
-                    secretEnvironment: context.secretEnvironment,
-                    personalInstructions: context.personalInstructions,
-                    usageGrant: context.usageGrant,
-                    executionContext: this.runners.require(task.runner).prepareExecutionContext(context)
-                };
-            },
-            submit: async (task, occurrenceId, context) => {
-                const result = (await this.gitOperationService.execute('session.message', {
-                    sessionId: task.sessionId,
-                    workspaceId: task.workspaceId,
-                    __requestUserId: task.ownerUserId,
-                    secretEnvironment: context.secretEnvironment,
-                    ...(context.gitConfiguration === undefined
-                        ? {}
-                        : { gitConfiguration: context.gitConfiguration })
-                }, async (data) => this.sessionMessageService.submitScheduled({
-                    sessionId: task.sessionId,
-                    occurrenceId,
-                    objective: task.objective,
-                    initiatedByUserId: task.ownerUserId,
-                    secretEnvironment: data
-                        .secretEnvironment,
-                    personalInstructions: context.personalInstructions,
-                    ...(context.usageGrant === undefined ? {} : { usageGrant: context.usageGrant }),
-                    executionContext: context.executionContext
-                })));
-                return { runId: result.run.id };
-            },
+            authorize: scheduledExecution.authorize,
+            submit: scheduledExecution.submit,
             sessionTitle: (sessionId) => {
                 const session = this.runtime.getAgentSession(sessionId);
                 return session?.customTitle ?? session?.runnerTitle ?? sessionId;
@@ -1562,6 +1468,8 @@ export class NodeConnector {
                 {}),
             emitNotification: (payload) => this.emitWorkbenchEvent('conversation', payload)
         });
+        this.executionLifecycle = new ExecutionLifecycle(() => this.database !== undefined, this.scheduledSessions, this.continuousRunCoordinator, this.goalCoordinator, this.modelUsage, this.goalMcpBridge, this.scheduleMcpBridge, this.notificationMcpBridge, this.runEventBridge, this.upgradeCoordinator);
+        // Register public operations only after domain workflows are connected.
         this.runnerService = new RunnerService(requireDatabase, () => this.capabilities, this.runners, this.runnerUsageReader);
         this.workbenchManifestService = new WorkbenchManifestService({
             capabilities: () => this.capabilities,
@@ -1616,6 +1524,12 @@ export class NodeConnector {
             readPage: (input, actor, signal) => completionWorkspace.readPage(input, actor, signal),
             references: (workspaceId, _actor, signal) => completionWorkspace.references(workspaceId, signal)
         });
+        this.operationRouter.register('agent.network', agentNetworkExecutionCommand({
+            runtime: this.runtime,
+            coordinator: this.continuousRunCoordinator,
+            service: this.agentNetworkService,
+            observations: this.agentNetworkObservations
+        }));
         this.operationRouter.registerAll(this.promptCompletion.operations());
         for (const operation of CONVERSATION_TEMPLATE_OPERATIONS)
             this.operationRouter.register(operation, (data) => {
@@ -1704,8 +1618,35 @@ export class NodeConnector {
             manifest: await this.workbenchManifestService.read(),
             binaryTerminal: true
         }));
-        this.executionLifecycle = new ExecutionLifecycle(() => this.database !== undefined, this.scheduledSessions, this.continuousRunCoordinator, this.goalCoordinator, this.modelUsage, this.goalMcpBridge, this.scheduleMcpBridge, this.notificationMcpBridge, this.runEventBridge, this.upgradeCoordinator);
         this.operationAdmission = new NodeOperationAdmission(() => this.stopped, () => this.database !== undefined, () => this.config?.nodeId, this.restartHandoff, this.upgradeCoordinator, this.gitOperationService, this.operationRouter);
+        // Lifecycle is connected last; start() is the only resource activation boundary.
+        this.lifecycle = new NodeLifecycle(() => this.startResources(), () => {
+            this.continuousRunCoordinator.suspend();
+            this.goalCoordinator.freeze();
+            this.scheduledSessions.stop();
+            void this.workspaceSessionService.stop();
+        }, {
+            waitForRecovery: () => this.restartHandoff.wait(),
+            drainInput: async () => {
+                this.sessionMessageService.setAccepting(false);
+                await this.operationAdmission.drain();
+                await this.sessionMessageService.drain();
+                await this.workspaceSessionService.stop();
+            },
+            closeResume: () => this.externalSessionResumeService.close(),
+            capture: () => {
+                if (!this.config?.nodeId)
+                    return;
+                return this.restartHandoff.capture();
+            },
+            dispose: () => this.disposeRuntime(),
+            publish: (snapshot) => this.restartHandoff.publish(snapshot),
+            diagnose: (stage, error) => nodeLog('node.shutdown.failed', {
+                stage,
+                errorCode: safeErrorCode(error, 'NODE_SHUTDOWN_FAILED'),
+                ...(stage === 'capture' ? plannedRestartCaptureDiagnostic(error) : undefined)
+            })
+        });
     }
     projectComputerUseCapability(capabilities) {
         return {
@@ -1717,6 +1658,7 @@ export class NodeConnector {
         return this.lifecycle.start();
     }
     async startResources() {
+        this.workspaceSessionService.resume();
         this.continuousRunCoordinator.resumeScheduling();
         this.sessionMessageService.setAccepting(true);
         this.config ??= await loadNodeConfig(this.configPath);
@@ -1820,6 +1762,8 @@ export class NodeConnector {
         return this.lifecycle.stop(options.handoff === true);
     }
     disposeRuntime() {
+        // Earlier shutdown stages may fail; disposal must still join internal reads before DB release.
+        const workspaceSessionDrain = this.workspaceSessionService.stop();
         this.recentRunProjectionService.dispose();
         this.upgradeCoordinator.stop();
         this.connectionLifecycle.stop();
@@ -1831,6 +1775,7 @@ export class NodeConnector {
         this.gitOperationService.clear();
         this.goalCoordinator.dispose();
         this.runEventService.clear();
+        this.agentNetworkProjection.dispose();
         this.sessionContextService.dispose();
         this.runAttachmentService.dispose();
         this.modelResourcePublicationService.dispose();
@@ -1863,6 +1808,7 @@ export class NodeConnector {
         this.controlChannel.stop();
         const database = this.database;
         const drains = Promise.allSettled([
+            workspaceSessionDrain,
             scheduledDrain,
             marAgentDrain,
             runnerDrain,

package/dist/marctl/package.json

@@ -1 +1 @@
-{"type":"module","version":"0.12.4"}
+{"type":"module","version":"0.12.5"}

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

@@ -129,7 +129,8 @@ const collaborationPrompt = [
     "Use native agent_* tools to collaborate within the Agent Network when another Session's context or ongoing work materially helps. Prefer focused requests and avoid unnecessary cross-Session coordination. Peer Sessions retain their own work and lifecycle; do not treat them as task-owned children or stop them merely for task cleanup.",
     'Prefer reusing known Session IDs rather than rediscovering them. Updates are most useful when requested or when the recipient needs to decide or change course; prefer combining related updates.',
     'An accepted message normally needs no separate acknowledgment. Requests for receipt-only replies and immediate agent_view calls solely to confirm receipt are usually unnecessary.',
-    'For delegated work, prefer a concise final handoff over routine progress reports or duplicate completion messages. Early contact is most useful for requested updates, blockers, scope conflicts, or information needed for a decision.'
+    'The parent automatically collects the latest unread public reply and terminal state from each observed direct child before its next natural model request. Usually reply in the child Session itself rather than sending duplicate progress or completion reports with agent_send.',
+    'Contact the parent proactively when timely action or a decision is needed, such as a blocker, scope conflict or major risk, or when explicitly asked to report. Routine child updates usually need no reply; prefer combining related guidance.'
 ].join('\n\n');
 const managementPrompt = [
     '# Workspace management',

package/dist/service/agent-network-run-projection.js

@@ -0,0 +1,60 @@
+import { agentObservationFromRunEvent } from './agent-network-observations.js';
+import { marctlSessionDetail } from './session-recent-activity.js';
+/** Projects normalized Run events and owns transient observers from attachment through terminal cleanup.
+ * Run-keyed handles survive Session identity promotion without borrowing a replacement's lifetime.
+ * Runner-owned context observers remain with the Runner; this owner only borrows their delivery port.
+ */
+export class AgentNetworkRunProjection {
+    runtime;
+    observations;
+    transient = new Map();
+    constructor(runtime, observations) {
+        this.runtime = runtime;
+        this.observations = observations;
+    }
+    ensureObservations = (actor) => {
+        const existing = this.observations.get(actor.observationId ?? actor.sessionId);
+        if (existing)
+            return existing;
+        const run = actor.runId === undefined ? undefined : this.runtime.getRun(actor.runId);
+        if (!run ||
+            run.sessionId !== actor.sessionId ||
+            this.runtime.activeSessionRun(actor.sessionId)?.id !== run.id)
+            throw new Error('AGENT_ACTOR_NOT_ACTIVE');
+        const observer = this.observations.attach(actor.sessionId);
+        this.transient.set(run.id, observer);
+        return observer;
+    };
+    accept = ({ run, executionId, eventType, payload, terminalStatus }) => {
+        const child = this.runtime.getAgentSession(run.sessionId);
+        if (!child)
+            return;
+        const parent = child.parentSessionId == null
+            ? undefined
+            : this.runtime.getAgentSession(child.parentSessionId);
+        let observation = agentObservationFromRunEvent({ eventType, payload, terminalStatus });
+        if (eventType === 'approval.request') {
+            const approvals = marctlSessionDetail(this.runtime, child, 0).pendingApprovals;
+            if (approvals.length)
+                observation = { kind: 'message', value: JSON.stringify({ pendingApprovals: approvals }) };
+        }
+        if (observation)
+            this.observations.publishChild({
+                ...(parent?.workspaceId === child.workspaceId ? { parentId: parent.id } : {}),
+                childId: child.id,
+                runId: run.id,
+                executionId,
+                ...observation
+            });
+        if (terminalStatus !== undefined) {
+            const observer = this.transient.get(run.id);
+            this.transient.delete(run.id);
+            observer?.close();
+        }
+    };
+    dispose() {
+        for (const observer of this.transient.values())
+            observer.close();
+        this.transient.clear();
+    }
+}

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

@@ -7,12 +7,23 @@ import { sessionPage } from './pagination.js';
 import { latestSessionActivityAt } from './session-presentation-service.js';
 import { marctlSessionSummary, sessionActivityStatus } from '../service/session-recent-activity.js';
 import { WorkspaceSessionCleanupBudget, WorkspaceSessionCleanupDeadline } from '../service/workspace-session-cleanup-budget.js';
+/** Owns catalog queries and Session catalog mutations; borrows the Workspace native cache.
+ * Public operations and internal observation share query rules, not transport/admission routing.
+ */
 export class SessionCatalogService {
     options;
     rewindQueue = Promise.resolve();
     constructor(options) {
         this.options = options;
     }
+    /** Internal observation uses the same catalog query without public operation dispatch. */
+    listWorkspacePage(workspaceId, sessionGroup) {
+        return this.list({
+            workspaceId,
+            limit: 30,
+            ...(sessionGroup === undefined ? {} : { sessionGroup })
+        });
+    }
     operations() {
         return {
             'session.list': (data) => this.list(record(data)),

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

@@ -1,8 +1,12 @@
 import { nodeLog } from '../operational.js';
 const WATCH_INTERVAL_MS = 30_000;
 const CACHE_TTL_MS = 15_000;
+/** Owns native discovery caches, periodic observation and the lifetime of internal page reads. */
 export class WorkspaceSessionService {
     options;
+    accepting = true;
+    pageReads = new Set();
+    discoveryReads = new Set();
     cacheGenerations = new Map();
     initialReads = new Map();
     incompleteDiscoveries = new Set();
@@ -15,10 +19,36 @@ export class WorkspaceSessionService {
     constructor(options) {
         this.options = options;
     }
+    async listPage(workspaceId, sessionGroup) {
+        if (!this.accepting)
+            throw new Error('NODE_STOPPED');
+        const read = this.options.listPage(workspaceId, sessionGroup);
+        this.pageReads.add(read);
+        try {
+            return await read;
+        }
+        finally {
+            this.pageReads.delete(read);
+        }
+    }
+    resume() {
+        this.accepting = true;
+    }
+    async stop() {
+        this.accepting = false;
+        for (const id of this.sessionWatchTimers.keys())
+            this.stopWatch(id);
+        await Promise.allSettled([...this.pageReads, ...this.sessionWatchReads.values()]);
+        // A first page can return a partial batch while native discovery still owns I/O.
+        // Retired cache generations also remain owned until their reads actually settle.
+        await Promise.allSettled([...this.discoveryReads]);
+    }
     cachedSnapshot(workspaceId) {
         return this.sessionCache.get(workspaceId)?.sessions ?? [];
     }
     ensureWatch(workspaceId) {
+        if (!this.accepting)
+            return;
         if (this.sessionWatchTimers.has(workspaceId) || this.sessionWatchReads.has(workspaceId))
             return;
         void this.runWatchCycle(workspaceId);
@@ -66,7 +96,8 @@ export class WorkspaceSessionService {
                     sessions,
                     expiresAt: this.staleDiscoveries.has(workspaceId) ? 0 : Date.now() + CACHE_TTL_MS
                 });
-                if (notify &&
+                if (this.accepting &&
+                    notify &&
                     previous !== undefined &&
                     sessionSignature(previous) !== sessionSignature(sessions))
                     this.options.invalidate(workspaceId);
@@ -109,6 +140,7 @@ export class WorkspaceSessionService {
                 throw error;
             })
                 .finally(() => {
+                this.discoveryReads.delete(read);
                 acceptingBatches = false;
                 if (this.sessionCacheReads.get(workspaceId) === read) {
                     this.sessionCacheReads.delete(workspaceId);
@@ -118,7 +150,9 @@ export class WorkspaceSessionService {
                 }
                 if (this.initialReads.get(workspaceId) === initial)
                     this.initialReads.delete(workspaceId);
-                if (notifyCompletion && this.cacheGenerations.get(workspaceId) === generation)
+                if (this.accepting &&
+                    notifyCompletion &&
+                    this.cacheGenerations.get(workspaceId) === generation)
                     this.options.invalidate(workspaceId);
                 if (!this.sessionCacheReads.has(workspaceId) &&
                     !this.sessionCache.has(workspaceId) &&
@@ -126,6 +160,7 @@ export class WorkspaceSessionService {
                     this.cacheGenerations.delete(workspaceId);
             });
             discovery = read;
+            this.discoveryReads.add(read);
             this.sessionCacheReads.set(workspaceId, discovery);
             // Later Runner failures cannot become unhandled after the first batch was returned.
             void discovery.catch(() => undefined);
@@ -176,7 +211,9 @@ export class WorkspaceSessionService {
     }
     async runWatchCycle(workspaceId) {
         await this.refreshWatch(workspaceId);
-        if (!this.options.active(workspaceId) || this.sessionWatchTimers.has(workspaceId))
+        if (!this.accepting ||
+            !this.options.active(workspaceId) ||
+            this.sessionWatchTimers.has(workspaceId))
             return;
         const timer = setTimeout(() => {
             this.sessionWatchTimers.delete(workspaceId);
@@ -186,11 +223,11 @@ export class WorkspaceSessionService {
         this.sessionWatchTimers.set(workspaceId, timer);
     }
     async performRefresh(workspaceId) {
-        if (!this.options.active(workspaceId))
+        if (!this.accepting || !this.options.active(workspaceId))
             return this.stopWatch(workspaceId);
         try {
-            const signature = JSON.stringify(await this.options.listPage(workspaceId));
-            if (!this.options.active(workspaceId))
+            const signature = JSON.stringify(await this.listPage(workspaceId));
+            if (!this.accepting || !this.options.active(workspaceId))
                 return this.stopWatch(workspaceId);
             const previous = this.sessionWatchSignatures.get(workspaceId);
             this.sessionWatchSignatures.set(workspaceId, signature);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -42,14 +42,14 @@
     "turndown-plugin-gfm": "^1.0.2",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.12.4",
-    "@myagentroam/protocol": "0.12.4"
+    "@myagentroam/agent": "0.12.5",
+    "@myagentroam/protocol": "0.12.5"
   },
   "devDependencies": {
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
-    "@myagentroam/marctl": "0.12.4",
-    "@myagentroam/code-navigation": "0.11.1"
+    "@myagentroam/code-navigation": "0.11.1",
+    "@myagentroam/marctl": "0.12.5"
   },
   "exports": {
     "./config": {