@myagentroam/node 0.11.46 → 0.11.48

package/dist/connector.js

@@ -651,25 +651,29 @@ export class NodeConnector {
                 }),
                 resources: async (signal) => {
                     signal.throwIfAborted();
-                    const currentSessionId = this.runtime.getAgentSessionById(sessionId)?.id;
-                    if (!currentSessionId)
+                    const currentSession = this.runtime.getAgentSessionById(sessionId);
+                    if (!currentSession)
                         return [];
+                    const currentSessionId = currentSession.id;
                     const run = this.runtime.activeSessionRun(currentSessionId);
                     if (!run || !run.initiatedByUserId)
                         return [];
-                    const result = await this.agentNetworkService.list({
-                        sessionId: currentSessionId,
-                        runId: run.id,
-                        requestUserId: run.initiatedByUserId
-                    }, { scope: 'children', limit: 100 });
+                    const result = await this.sessionCatalogService.operations()['session.list']({
+                        workspaceId: currentSession.workspaceId,
+                        registeredOnly: true,
+                        view: 'marctl',
+                        parentSessionId: currentSessionId,
+                        limit: 100
+                    });
                     signal.throwIfAborted();
                     const data = result;
-                    if (!data.sessions?.length && !data.truncated)
+                    const truncated = data.nextCursor != null;
+                    if (!data.sessions?.length && !truncated)
                         return [];
                     return [
                         `Child Sessions (use agent_list for details): ${JSON.stringify({
                             sessions: data.sessions ?? [],
-                            truncated: data.truncated === true
+                            truncated
                         }).replace(/[<>&]/g, (c) => c === '<' ? '\\u003c' : c === '>' ? '\\u003e' : '\\u0026')}`
                     ];
                 }
@@ -1093,31 +1097,7 @@ export class NodeConnector {
             goals: this.goalRuntime,
             runs: this.runWorkbenchService,
             observations: this.agentNetworkObservations,
-            listSessions: async (input) => this.sessionCatalogService.operations()['session.list'](input),
             history: async (input) => this.sessionQueryService.operations()['session.turns.list'](input),
-            profiles: async (environment, models) => {
-                const summaries = Array.isArray(models)
-                    ? models.flatMap((model, index) => {
-                        if (!isPlainRecord(model))
-                            return [];
-                        const { apiKey: _apiKey, credential: _credential, imageGeneration: _images, access: _access, ...summary } = model;
-                        return [
-                            {
-                                ...summary,
-                                sortOrder: typeof summary.sortOrder === 'number' ? summary.sortOrder : index
-                            }
-                        ];
-                    })
-                    : undefined;
-                const result = await this.runnerService.operations()['runner.profiles.list']({
-                    secretEnvironment: environment,
-                    marAgentModels: summaries,
-                    waitForRefresh: true
-                });
-                if (!isPlainRecord(result) || !Array.isArray(result.profiles))
-                    throw new Error('RUNNER_PROFILE_INVALID');
-                return result.profiles;
-            },
             ensureObservations: (actor) => {
                 const existing = this.agentNetworkObservations.get(actor.observationId ?? actor.sessionId);
                 if (existing)

package/dist/marctl-guidance.js

@@ -20,10 +20,10 @@ export const marctlInstructions = [
     '## MAR Workspace CLI',
     'Run marctl from the shell. Commands use the authenticated Node and Workspace; marctl help agents, nodes, ssh or scp shows options.',
     'Use agents start --title <title> -m <text> [--runner <runner>] [--model-id <id>] [--effort <effort>] [--goal <objective>]. An Agent must supply a nonblank title; a manual terminal may omit it. The default Runner is the current Session Runner; a terminal without a current Session must specify --runner or an explicit --parent. Start returns without waiting.',
-    'Use agents send <id> -m <text> [--steer|--queue], agents wait [<id>] [--wait-for message|completion] [--timeout <duration>], agents stop <id> --execution <execution-id>, agents list [--scope children|descendants|workspace|profile], and agents view <id> [--history]. Wait defaults to direct-child completion for 30 seconds; --timeout 0ms takes a snapshot. Stop clears the target Session Goal.',
+    'Use agents send <id> -m <text> [--steer|--queue], agents wait [<id>] [--wait-for message|completion] [--timeout <duration>], agents stop <id> --execution <execution-id>, agents list [--scope tree|active], and agents view <id> [--history]. Wait defaults to direct-child completion for 30 seconds; --timeout 0ms takes a snapshot. Stop clears the target Session Goal.',
     'Prefer agents send <id> --steer -m <text> for timely communication or course correction. Use --queue only for deliberately deferred input: it is consumed after current work and earlier queued inputs finish, and with an active Goal it is not consumed until that Goal exits. Acceptance is not a guarantee of immediate processing.',
     'Start and send accept repeated --image <local-path> for PNG, JPEG, GIF or WebP; limits are five images, 5 MiB each and 10 MiB total. Send can update a Goal alone with --goal <objective> or --clear-goal; omitted Goal leaves it unchanged. Decide a direct child approval with send <id> --approval <approval-id> --decision approve|reject.',
-    'List accepts --agent <id> for a relation root, --query, --parent, --limit and --cursor. Use --scope profile [--runner <runner>] for Runner models; configured profiles do not guarantee account availability.',
+    'List accepts only --scope tree|active, optional --query <title-fragment> and --limit <1..100> (default 100). With a current Session it defaults to the containing collaboration tree, including idle Sessions; without one it defaults to active Workspace Sessions (running or sleeping), and explicit tree is rejected. Returns currentAgentId (null without a Session), flat sessions with id, parentSessionId, title, runner and status, and truncated; no cursor or pagination. Reuse known IDs directly.',
     'Only direct-child updates are collected automatically. Sending to a non-child never subscribes; an explicit wait observes it only for that call.',
     'Use agents config, rename, prompt and schedule for management. marctl nodes, ssh and scp use authorized Nodes.',
     marctlSafety

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

@@ -38,6 +38,7 @@ const goal = {
         }
     ]
 };
+const deliveryGuidance = 'Default to STEER. Use QUEUE only when the user or recipient explicitly requests deferred delivery. Do not queue merely to avoid interrupting the recipient or because the message is a report.';
 const tools = [
     {
         action: 'start',
@@ -49,7 +50,7 @@ const tools = [
             runner,
             modelId: {
                 ...text,
-                description: 'Model ID from the target Runner Profile models[].id, not a display name. For MAR Agent this is an internal configuration ID, not an upstream model ID; omit to use the Runner default.'
+                description: 'Model configuration ID; omit to use the target Runner default.'
             },
             effort: text,
             title: text,
@@ -60,7 +61,7 @@ const tools = [
     },
     {
         action: 'send',
-        description: 'Send input, decide an approval or update a Goal; goal:null leaves it unchanged, goal:{clear:true} clears it. Messages default to REPLACE_CURRENT (steer); use QUEUE only when deferred delivery is explicitly requested. QUEUE is consumed only after current work and earlier queued inputs finish; an active Goal must exit first.',
+        description: `Send input, decide an approval or update a Goal; goal:null leaves it unchanged, goal:{clear:true} clears it. ${deliveryGuidance} QUEUE is consumed only after current work and earlier queued inputs finish; an active Goal must exit first.`,
         properties: {
             agentId: text,
             content: { type: 'string' },
@@ -73,10 +74,10 @@ const tools = [
                 required: ['approvalId', 'decision'],
                 properties: { approvalId: text, decision: { type: 'string', enum: ['approve', 'reject'] } }
             },
-            deliveryIntent: {
+            delivery: {
                 type: 'string',
-                enum: ['SEND', 'QUEUE', 'REPLACE_CURRENT'],
-                description: 'Message delivery defaults to REPLACE_CURRENT (steer); explicit SEND remains supported.'
+                enum: ['STEER', 'QUEUE'],
+                description: deliveryGuidance
             },
             clientMessageId: text
         },
@@ -101,20 +102,19 @@ const tools = [
     },
     {
         action: 'list',
-        description: 'List direct children by default, discover Workspace Sessions, inspect descendants or query a Runner profile.',
+        description: "List the current Session's collaboration tree by default, or active Workspace Sessions. Active includes running and sleeping. Reuse known Session IDs directly. Returns currentAgentId, flat sessions (id, parentSessionId, title, runner, status) and truncated; no pagination.",
         properties: {
-            scope: { type: 'string', enum: ['workspace', 'children', 'descendants', 'profile'] },
-            agentId: {
-                ...text,
-                description: 'Root for children or descendants; defaults to the current Session.'
+            scope: {
+                type: 'string',
+                enum: ['tree', 'active'],
+                description: 'Defaults to tree: the containing tree, including ancestors, peers and descendants.'
             },
-            runner: {
-                ...runner,
-                description: 'Runner for profile scope; defaults to the current Runner, not a model name.'
+            query: {
+                type: 'string',
+                maxLength: 160,
+                description: 'Optional case-insensitive title fragment within the scope.'
             },
-            query: { type: 'string', description: 'Search Sessions; not a model selector.' },
-            limit: { type: 'integer', minimum: 1, maximum: 100 },
-            cursor: text
+            limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Defaults to 100.' }
         }
     },
     {
@@ -140,7 +140,8 @@ const delegationPrompt = [
 const collaborationPrompt = [
     '# Workspace collaboration',
     "Use native agent_* tools to collaborate within the Agent Network when another Session's context or ongoing work materially helps. Keep requests focused 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. Explicitly wait when you need progress or completion.",
-    "Reuse known Session IDs rather than rediscovering them. Send updates for meaningful progress, blockers, or changes that affect the recipient's work; combine related updates and avoid acknowledgment-only exchanges."
+    'Reuse known Session IDs rather than rediscovering them. Send updates only when requested or when the recipient needs to decide or change course; combine related updates and avoid acknowledgment-only exchanges.',
+    'For delegated work, do not provide routine progress updates or acknowledgments unless requested. Contact the parent before completion only when requested or for blockers, scope conflicts, or information that requires the parent to decide or change course. Return a concise final handoff; do not also send a duplicate completion message.'
 ].join('\n\n');
 const managementPrompt = [
     '# Workspace management',
@@ -154,13 +155,27 @@ export function agentNetworkExtension(invoke, currentExecution) {
             context.hooks.intercept('prompt.sections', (input, _call, next) => {
                 const available = new Set(input.facts?.tools);
                 const enabled = input.facts?.mode !== 'compact';
+                const delegate = enabled && available.has('agent_start');
+                const models = delegate
+                    ? (context.models
+                        ?.list()
+                        .filter((model) => model.conversationModel && model.subagentModel)
+                        .map((model) => ({
+                        id: model.id,
+                        name: model.name,
+                        supportedEfforts: model.reasoningEfforts,
+                        defaultEffort: model.defaultReasoningEffort
+                    })) ?? [])
+                    : [];
                 return next({
                     ...input,
                     sections: [
                         ...input.sections,
                         {
                             id: 'mar.node.agent-network:delegation',
-                            text: enabled && available.has('agent_start') ? delegationPrompt : null
+                            text: delegate
+                                ? `${delegationPrompt}\n\nAvailable subagent models:\n${JSON.stringify({ runner: 'mar-agent', models })}`
+                                : null
                         },
                         {
                             id: 'mar.node.agent-network:collaboration',
@@ -190,7 +205,10 @@ export function agentNetworkExtension(invoke, currentExecution) {
                         'effort',
                         'waitFor',
                         'waitMs',
-                        'scope'
+                        'scope',
+                        'query',
+                        'limit',
+                        'cursor'
                     ],
                     inputSchema: {
                         type: 'object',
@@ -203,14 +221,35 @@ export function agentNetworkExtension(invoke, currentExecution) {
                         if (!executionId)
                             throw new Error('AGENT_ACTOR_NOT_ACTIVE');
                         const args = input;
-                        const operationInput = tool.action === 'send' &&
-                            args.deliveryIntent === undefined &&
-                            ((typeof args.content === 'string' && !!args.content.trim()) ||
+                        let operationInput = args;
+                        if (tool.action === 'send') {
+                            const { delivery, ...sendInput } = args;
+                            const hasMessage = (typeof args.content === 'string' && !!args.content.trim()) ||
                                 (Array.isArray(args.attachments) && args.attachments.length > 0) ||
-                                (Array.isArray(args.attachmentIds) && args.attachmentIds.length > 0))
-                            ? { ...args, deliveryIntent: 'REPLACE_CURRENT' }
-                            : args;
-                        const result = await invoke(executionId, tool.action, operationInput, call);
+                                (Array.isArray(args.attachmentIds) && args.attachmentIds.length > 0);
+                            operationInput =
+                                delivery !== undefined || hasMessage
+                                    ? {
+                                        ...sendInput,
+                                        deliveryIntent: delivery === 'QUEUE' ? 'QUEUE' : 'REPLACE_CURRENT'
+                                    }
+                                    : sendInput;
+                        }
+                        const onResolved = call.publishEventData
+                            ? async (sessions) => {
+                                const rows = sessions.map((session) => ({
+                                    agentId: session.id,
+                                    title: session.customTitle ?? session.runnerTitle ?? undefined
+                                }));
+                                const result = tool.action === 'wait'
+                                    ? { agents: rows }
+                                    : tool.action === 'view'
+                                        ? { session: rows[0] }
+                                        : (rows[0] ?? {});
+                                await call.publishEventData(agentOperationEvent(tool.action, {}, result).eventData);
+                            }
+                            : undefined;
+                        const result = await invoke(executionId, tool.action, operationInput, call, onResolved);
                         const modelResult = tool.action === 'wait' ? agentNetworkWaitModelOutput(result) : result;
                         return {
                             data: result,

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

@@ -103,7 +103,7 @@ export function agentOperationEvent(action, input, result) {
         receipt.modelCount = value.models.length;
     }
     if (action === 'view' && isPlainRecord(value.session)) {
-        for (const key of ['status', 'model', 'effort']) {
+        for (const key of ['status', 'modelId', 'effort']) {
             const field = text(value.session[key]);
             if (field)
                 receipt[key] = field;

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

@@ -6,7 +6,7 @@ export function normalizeMarAgentUsage(usage) {
 }
 import { boundedConversationItemId, compactRunnerText, compactRunnerValue } from '../normalization.js';
 import { runnerErrorProjection } from '../runner-error.js';
-import { toolPresentationSchema } from '@myagentroam/protocol';
+import { toolPresentationSchema, agentOperationPresentationSchema } from '@myagentroam/protocol';
 import { publicOutputSnapshot, publicToolOutput } from '../normalization.js';
 import { boundToolOutput } from '@myagentroam/protocol';
 import { agentOperationAction, agentOperationPresentation } from './agent-operation-presentation.js';
@@ -170,6 +170,20 @@ export class MarAgentConversationNormalizer {
                 ...this.#codeModeToolResults(event)
             ];
         }
+        if (event.type === 'tool.updated') {
+            const state = this.#tools.get(event.callId);
+            if (!state?.active ||
+                state.toolName !== event.toolName ||
+                !agentOperationAction(event.toolName))
+                return [];
+            const operation = agentOperationPresentationSchema.safeParse(record(event.data)?.agentOperation);
+            if (!operation.success || operation.data.action !== agentOperationAction(event.toolName))
+                return [];
+            this.#tools.set(event.callId, { ...state, presentationData: event.data });
+            return [
+                genericToolItem(state.itemId, state.toolName, 'IN_PROGRESS', state.input, null, null, false, event.data, state.subagentTitle, state.subagentDetails, undefined, undefined, state.inputTruncated)
+            ];
+        }
         if (event.type === 'sleep.started') {
             const state = this.#tools.get(event.callId);
             if (state?.toolName !== 'sleep')
@@ -673,7 +687,7 @@ export class MarAgentConversationNormalizer {
         }
         const item = genericToolItem(state?.itemId ?? itemId('tool', event.callId), event.toolName, 'COMPLETED', state?.input, generatedImages.length === 0
             ? event.summary
-            : generatedImages.map((image) => image.name).join(', '), null, event.outputTruncation !== undefined, event.data, agentId === undefined ? state?.subagentTitle : this.#subagentTitles.get(agentId), details, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated, event.summaryTruncated === true);
+            : generatedImages.map((image) => image.name).join(', '), null, event.outputTruncation !== undefined, mergeAgentOperationData(event.toolName, state?.presentationData, event.data), agentId === undefined ? state?.subagentTitle : this.#subagentTitles.get(agentId), details, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated, event.summaryTruncated === true);
         return [
             {
                 ...item,
@@ -704,7 +718,11 @@ export class MarAgentConversationNormalizer {
         return [
             genericToolItem(state?.itemId ?? itemId('tool', event.callId), event.toolName, event.code === 'MAR_AGENT_CANCELLED' || event.code === 'MAR_AGENT_EXECUTION_CANCELLED'
                 ? 'CANCELLED'
-                : 'FAILED', state?.input, event.message ?? event.code, event.code, event.truncated === true, event.data === undefined ? state?.presentationData : event.data, state?.subagentTitle, state?.subagentDetails, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated)
+                : 'FAILED', state?.input, event.message ?? event.code, event.code, event.truncated === true, agentOperationAction(event.toolName)
+                ? mergeAgentOperationData(event.toolName, state?.presentationData, event.data)
+                : event.data === undefined
+                    ? state?.presentationData
+                    : event.data, state?.subagentTitle, state?.subagentDetails, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated)
         ];
     }
     #codeModeToolResults(event) {
@@ -1027,6 +1045,28 @@ function codeExecutionError(data) {
         message: compactRunnerText(error.message, 1000)
     };
 }
+function mergeAgentOperationData(toolName, previous, current) {
+    if (!agentOperationAction(toolName))
+        return current;
+    const before = agentOperationPresentationSchema.safeParse(record(previous)?.agentOperation);
+    if (!before.success || before.data.action !== agentOperationAction(toolName))
+        return current;
+    const after = agentOperationPresentationSchema.safeParse(record(current)?.agentOperation);
+    if (!after.success || after.data.action !== before.data.action) {
+        return { ...record(current), agentOperation: before.data };
+    }
+    return {
+        ...record(current),
+        agentOperation: {
+            ...after.data,
+            targets: before.data.targets.map((target) => ({
+                ...after.data.targets.find((candidate) => candidate.agentId === target.agentId),
+                ...target
+            })),
+            ...(before.data.targetsTruncated ? { targetsTruncated: true } : {})
+        }
+    };
+}
 function genericToolItem(id, toolName, status, input, outputSummary = null, errorCode = null, truncated = false, output, subagentTitle, knownSubagentDetails, sleepStartedAt, outputTruncation, inputTruncated = false, summaryTruncated = false) {
     if (toolName === 'code_exec') {
         const code = typeof input === 'string' ? input : record(input)?.code;

package/dist/service/agent-network-bindings.js

@@ -12,8 +12,8 @@ export function actorForAuthenticatedTerminal(actor, workspaceId) {
     terminalCalls.set(authenticated, { workspaceId });
     return authenticated;
 }
-import { sessionPage } from '../session/pagination.js';
-import { marctlSessionSummary, marctlSessionDetail } from './session-recent-activity.js';
+import { marctlSessionDetail } from './session-recent-activity.js';
+import { listAgentNetworkSessions } from './agent-network-list.js';
 /** Bind the collaboration use case to the existing Session, Run and Goal owners. */
 export function createNodeAgentNetwork(options) {
     async function actorSession(actor) {
@@ -44,9 +44,35 @@ export function createNodeAgentNetwork(options) {
             throw new Error('SESSION_NOT_FOUND');
         return session;
     }
-    function origin(parent) {
+    function ancestorDistance(source, targetId) {
+        const seen = new Set([source.id]);
+        let parentId = source.parentSessionId;
+        let distance = 1;
+        while (parentId) {
+            if (seen.has(parentId))
+                throw Object.assign(new Error('Session ancestry contains a cycle.'), {
+                    code: 'SESSION_RELATION_INVALID'
+                });
+            seen.add(parentId);
+            if (parentId === targetId)
+                return distance;
+            const parent = options.runtime.getAgentSession(parentId);
+            if (parent?.id === targetId)
+                return distance;
+            parentId = parent
+                ? parent.parentSessionId
+                : options.database()?.getSessionRecord(parentId)?.metadata.parentSessionId;
+            distance++;
+        }
+        return 0;
+    }
+    function origin(parent, targetId) {
+        const distance = targetId === undefined ? 0 : ancestorDistance(parent, targetId);
         return {
             sessionId: parent.id,
+            ...(distance === 0
+                ? {}
+                : { relation: distance === 1 ? 'child' : 'descendant' }),
             name: parent.customTitle?.trim() || parent.runnerTitle?.trim() || parent.id
         };
     }
@@ -119,6 +145,18 @@ export function createNodeAgentNetwork(options) {
                 options.projection.resolve(record.id, true)));
             return resolved.filter((session) => session !== undefined);
         },
+        validateSend: async (actor, session) => {
+            if (terminalCalls.has(actor))
+                return;
+            const source = await actorSession(actor);
+            if (ancestorDistance(source, session.id) === 0)
+                return;
+            const run = options.runtime.activeSessionRun(session.id);
+            if (!run || run.status === 'CANCELLING')
+                throw Object.assign(new Error('Cannot send messages to an inactive ancestor session.'), {
+                    code: 'AGENT_ANCESTOR_NOT_ACTIVE'
+                });
+        },
         observe: (actor) => {
             options.ensureObservations(actor);
         },
@@ -243,7 +281,7 @@ export function createNodeAgentNetwork(options) {
                     : { personalInstructions: actor.personalInstructions }),
                 ...(actor.usageGrant === undefined ? {} : { usageGrant: actor.usageGrant }),
                 preserveActiveRun: true,
-                ...(parent ? { messageOrigin: origin(parent) } : {}),
+                ...(parent ? { messageOrigin: origin(parent, session.id) } : {}),
                 ...(message === undefined
                     ? {}
                     : {
@@ -267,7 +305,7 @@ export function createNodeAgentNetwork(options) {
                 ...(signal ? { [SESSION_ADMISSION_SIGNAL]: signal } : {}),
                 sessionId: session.id,
                 __suppressNotifications: true,
-                ...(parent ? { __marctlOrigin: origin(parent) } : {})
+                ...(parent ? { __marctlOrigin: origin(parent, session.id) } : {})
             }));
             return publicReceipt(result);
         },
@@ -313,80 +351,18 @@ export function createNodeAgentNetwork(options) {
             const workspaceId = terminal?.workspaceId ?? source?.workspaceId;
             if (!workspaceId)
                 throw new Error('SESSION_INVALID');
-            const current = source ? marctlSessionSummary(options.runtime, source) : null;
-            const scope = input.scope ?? (terminal ? 'workspace' : 'children');
-            if (scope === 'profile') {
-                const runner = input.runner ?? source?.runner;
-                if (!runner)
-                    throw new Error('RUNNER_REQUIRED');
-                const profiles = await options.profiles(actor.secretEnvironment ?? {}, actor.runnerConfiguration?.marAgentModels);
-                const profile = profiles.find((item) => item.runner === runner);
-                if (!profile)
-                    throw new Error('RUNNER_PROFILE_NOT_FOUND');
-                const models = profile.runner !== 'mar-agent'
-                    ? profile.models
-                    : profile.models.filter((model) => {
-                        const configurations = [
-                            actor.runnerConfiguration?.marAgentModel,
-                            ...(Array.isArray(actor.runnerConfiguration?.marAgentModels)
-                                ? actor.runnerConfiguration.marAgentModels
-                                : [])
-                        ];
-                        return configurations.some((value) => isPlainRecord(value) &&
-                            value.id === model.id &&
-                            value.enabled === true &&
-                            value.conversationModel === true &&
-                            value.subagentModel === true);
-                    });
-                return { current, runner: profile.runner, models, capabilities: profile.capabilities };
-            }
-            if (scope === 'workspace') {
-                const result = await options.listSessions({
-                    workspaceId,
-                    view: 'marctl',
-                    registeredOnly: true,
-                    ...(input.query === undefined ? {} : { query: input.query }),
-                    ...(input.parent === undefined ? {} : { parentSessionId: input.parent }),
-                    ...(input.limit === undefined ? {} : { limit: input.limit }),
-                    ...(input.cursor === undefined ? {} : { cursor: input.cursor })
-                });
-                if (!isPlainRecord(result))
-                    throw new Error('SESSION_LIST_INVALID_RESULT');
-                return { ...result, current };
-            }
-            if (scope !== 'children' && scope !== 'descendants')
-                throw new Error('AGENT_LIST_INVALID');
-            const root = input.agentId === undefined || input.agentId === source?.id
-                ? source
-                : await target(actor, input.agentId);
-            if (!root)
-                throw new Error('AGENT_TARGET_REQUIRED');
-            const database = options.database();
-            if (!database)
-                throw new Error('DATABASE_UNAVAILABLE');
-            const records = scope === 'children'
-                ? database.listChildSessionRecords(root.workspaceId, root.id)
-                : database.sessionTreeRecords(root.workspaceId, root.id).slice(1);
-            const sessions = (await Promise.all(records.map((record) => options.runtime.getAgentSession(record.id) ??
-                options.projection.resolve(record.id, true))))
-                .filter((session) => session !== undefined)
-                .filter((session) => !input.query ||
-                (session.customTitle ?? session.runnerTitle ?? '')
-                    .normalize('NFKC')
-                    .toLocaleLowerCase()
-                    .includes(input.query.normalize('NFKC').toLocaleLowerCase()));
-            const page = sessionPage(sessions, { limit: input.limit, cursor: input.cursor });
-            return {
-                current,
-                sessions: page.sessions.map((session) => marctlSessionSummary(options.runtime, session)),
-                nextCursor: page.nextCursor,
-                truncated: page.nextCursor !== null
-            };
+            return listAgentNetworkSessions(source, input, {
+                workspaceId,
+                runtime: options.runtime,
+                database: options.database(),
+                projection: options.projection
+            });
         },
-        view: async (actor, input) => {
+        view: async (actor, input, onResolved) => {
             const source = terminalCalls.has(actor) ? undefined : await actorSession(actor);
             const session = input.agentId === source?.id ? source : await target(actor, input.agentId);
             assertSessionControlOwner(options.runtime, session.id, actor.requestUserId);
+            await onResolved?.([session]);
             return {
                 session: marctlSessionDetail(options.runtime, session, options.runtime.sessionQueue(session.id).itemIds.length),
                 goal: publicGoal(options.goals.get(session.id)) ?? null,

package/dist/service/agent-network-invoke.js

@@ -4,9 +4,9 @@ import { randomUUID } from 'node:crypto';
 import { modelUsageGrantSchema } from '@myagentroam/protocol';
 /** Bind each native invocation to the actual live Node Execution and its captured resources. */
 export function agentNetworkInvoke(input) {
-    return async (executionId, action, payload, context) => {
+    return async (executionId, action, payload, context, onResolved) => {
         const actor = executionAgentActor({ ...input, executionId });
-        return invokeAgentNetwork(input.service, actor, action, payload, context);
+        return invokeAgentNetwork(input.service, actor, action, payload, context, undefined, onResolved);
     };
 }
 /** Read actor resources from the current Node-owned Execution, not caller arguments. */
@@ -51,7 +51,7 @@ export function executionAgentActor(input) {
     };
 }
 /** Shared command dispatch; callers must bind actor authority at their trusted boundary. */
-export async function invokeAgentNetwork(service, actor, action, payload, context, requestSignal) {
+export async function invokeAgentNetwork(service, actor, action, payload, context, requestSignal, onResolved) {
     const signal = context?.signal ?? requestSignal;
     switch (action) {
         case 'start':
@@ -63,16 +63,16 @@ export async function invokeAgentNetwork(service, actor, action, payload, contex
                 typeof payload.title === 'string' &&
                 !payload.title.trim()) {
                 const { title: _title, ...withoutTitle } = payload;
-                return service.start(actor, withoutTitle, signal);
+                return service.start(actor, withoutTitle, signal, onResolved);
             }
             return service.start(actor, {
                 ...payload,
                 ...(typeof payload.title === 'string' ? { title: payload.title.trim() } : {})
-            }, signal);
+            }, signal, onResolved);
         case 'send':
-            return service.send(actor, payload, signal);
+            return service.send(actor, payload, signal, onResolved);
         case 'stop':
-            return service.stop(actor, payload);
+            return service.stop(actor, payload, onResolved);
         case 'wait':
             return service.wait(actor, {
                 ...payload,
@@ -81,11 +81,11 @@ export async function invokeAgentNetwork(service, actor, action, payload, contex
                     : requestSignal
                         ? { signal: requestSignal }
                         : {})
-            });
+            }, onResolved);
         case 'list':
             return service.list(actor, payload);
         case 'view':
-            return service.view(actor, payload);
+            return service.view(actor, payload, onResolved);
     }
 }
 /** Node broker injects the caller only after validating the Server-issued Execution credential. */
@@ -145,8 +145,7 @@ export function agentNetworkExecutionCommand(input) {
         const session = input.runtime.getAgentSession(actor.sessionId);
         if (actor.requestUserId !== data.__requestUserId || session?.workspaceId !== data.workspaceId)
             throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
-        const profileQuery = data.action === 'list' && data.input.scope === 'profile' && data.input.runner === 'mar-agent';
-        const resources = (['start', 'send'].includes(String(data.action)) || profileQuery) &&
+        const resources = ['start', 'send'].includes(String(data.action)) &&
             isPlainRecord(data.__marctlExecutionResources)
             ? data.__marctlExecutionResources
             : undefined;

package/dist/service/agent-network-list.js

@@ -0,0 +1,71 @@
+import { marctlSessionSummary } from './session-recent-activity.js';
+/** Read only registered relationships and live Node facts; never discover or resume a Runner. */
+export async function listAgentNetworkSessions(source, input, options) {
+    if (Object.keys(input).some((key) => !['scope', 'query', 'limit'].includes(key)) ||
+        (input.scope !== undefined && !['tree', 'active'].includes(input.scope)) ||
+        (input.query !== undefined && (typeof input.query !== 'string' || input.query.length > 160)) ||
+        (input.limit !== undefined &&
+            (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > 100)))
+        throw Object.assign(new Error('Invalid Agent list input.'), { code: 'AGENT_LIST_INVALID' });
+    const scope = input.scope ?? (source ? 'tree' : 'active');
+    const known = new Map(options.runtime
+        .listAgentSessions()
+        .filter((session) => session.workspaceId === options.workspaceId)
+        .map((session) => [session.id, session]));
+    if (source)
+        known.set(source.id, source);
+    let sessions;
+    if (scope === 'tree') {
+        if (!source)
+            throw new Error('AGENT_TARGET_REQUIRED');
+        if (!options.database)
+            throw new Error('DATABASE_UNAVAILABLE');
+        const parents = new Map(options.database
+            .listSessionRecords(options.workspaceId)
+            .map((record) => [record.id, record.metadata.parentSessionId ?? null]));
+        for (const session of known.values())
+            parents.set(session.id, session.parentSessionId ?? null);
+        let root = source.id;
+        const ancestors = new Set([root]);
+        while (true) {
+            const parent = parents.get(root);
+            if (!parent || !parents.has(parent))
+                break;
+            if (ancestors.has(parent))
+                throw Object.assign(new Error('Session ancestry contains a cycle.'), {
+                    code: 'SESSION_RELATION_INVALID'
+                });
+            ancestors.add(parent);
+            root = parent;
+        }
+        const children = new Map();
+        for (const [id, parent] of parents) {
+            if (parent === null)
+                continue;
+            const siblings = children.get(parent) ?? [];
+            siblings.push(id);
+            children.set(parent, siblings);
+        }
+        const ids = [root];
+        for (let i = 0; i < ids.length; i++)
+            ids.push(...(children.get(ids[i]) ?? []).sort());
+        sessions = (await Promise.all(ids.map((id) => known.get(id) ?? options.projection.resolve(id, true)))).filter((session) => session !== undefined && session.workspaceId === options.workspaceId);
+    }
+    else {
+        sessions = [...known.values()].sort((left, right) => right.lastActivityAt - left.lastActivityAt || left.id.localeCompare(right.id));
+    }
+    const query = input.query?.trim().normalize('NFKC').toLocaleLowerCase() ?? '';
+    const matches = sessions
+        .map((session) => {
+        const { id, title, runner, status } = marctlSessionSummary(options.runtime, session);
+        return { id, parentSessionId: session.parentSessionId ?? null, title, runner, status };
+    })
+        .filter((session) => (scope !== 'active' || session.status !== 'IDLE') &&
+        (!query || session.title.normalize('NFKC').toLocaleLowerCase().includes(query)));
+    const limit = input.limit ?? 100;
+    return {
+        currentAgentId: source?.id ?? null,
+        sessions: matches.slice(0, limit),
+        truncated: matches.length > limit
+    };
+}

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

@@ -12,10 +12,10 @@ export class AgentNetworkService {
     list(actor, input = {}) {
         return this.options.list(actor, input);
     }
-    view(actor, input) {
-        return this.options.view(actor, input);
+    view(actor, input, onResolved) {
+        return this.options.view(actor, input, onResolved);
     }
-    async start(actor, input, signal) {
+    async start(actor, input, signal, onResolved) {
         signal?.throwIfAborted();
         const goal = parseAgentGoal(input.goal);
         const content = input.content ?? '';
@@ -41,6 +41,7 @@ export class AgentNetworkService {
             clientMessageId: input.clientMessageId ?? randomUUID(),
             goal
         }, signal);
+        await onResolved?.([created.session]);
         try {
             if (created.session.parentSessionId === actor.sessionId)
                 this.options.observe(actor, created.session);
@@ -54,7 +55,7 @@ export class AgentNetworkService {
             };
         }
     }
-    async send(actor, input, signal) {
+    async send(actor, input, signal, onResolved) {
         signal?.throwIfAborted();
         const goal = parseAgentGoal(input.goal);
         const content = input.content ?? '';
@@ -89,9 +90,12 @@ export class AgentNetworkService {
             await this.options.authorize(actor, session, 'send');
         if (goal.kind !== 'unchanged')
             await this.options.authorize(actor, session, 'goal');
+        if (hasMessage || goal.kind === 'set')
+            await this.options.validateSend(actor, session);
         if (input.approval !== undefined)
             await this.options.validateApproval(actor, session, input.approval);
         signal?.throwIfAborted();
+        await onResolved?.([session]);
         if (session.parentSessionId === actor.sessionId)
             this.options.observe(actor, session);
         const approvalResult = input.approval === undefined
@@ -191,7 +195,7 @@ export class AgentNetworkService {
             };
         }
     }
-    async stop(actor, input) {
+    async stop(actor, input, onResolved) {
         if (typeof input.agentId !== 'string' ||
             !input.agentId ||
             typeof input.executionId !== 'string' ||
@@ -199,6 +203,7 @@ export class AgentNetworkService {
             throw new Error('AGENT_STOP_INVALID');
         const session = await this.options.target(actor, input.agentId);
         await this.options.authorize(actor, session, 'stop');
+        await onResolved?.([session]);
         const goalBefore = this.options.goal(session.id);
         try {
             const result = this.options.stop(actor, session, input.executionId);
@@ -224,7 +229,7 @@ export class AgentNetworkService {
             };
         }
     }
-    async wait(actor, input) {
+    async wait(actor, input, onResolved) {
         validateAgentWaitOptions(input);
         if ((input.mode !== undefined && input.agentIds === undefined) ||
             (input.agentId !== undefined && input.agentIds !== undefined) ||
@@ -268,6 +273,7 @@ export class AgentNetworkService {
         if (!targets.length)
             throw new Error('AGENT_EXECUTION_NOT_FOUND');
         const selected = new Set(targets.map((target) => target.agentId));
+        await onResolved?.(targets.map((target) => sessions.find((session) => session.id === target.agentId)));
         const directChildren = new Set();
         for (const session of sessions)
             if (selected.has(session.id) && session.parentSessionId === actor.sessionId) {

package/dist/service/composer-message-input.js

@@ -11,7 +11,11 @@ export function withSessionMessageOrigin(input, origin, parentSessionId) {
         ? parsed
         : {
             ...parsed,
-            relation: parsed.sessionId === parentSessionId ? 'parent' : 'other'
+            relation: parsed.sessionId === parentSessionId
+                ? 'parent'
+                : parsed.relation === 'child' || parsed.relation === 'descendant'
+                    ? parsed.relation
+                    : 'other'
         };
     const tag = serializeComposerTag('mar_session_origin', snapshot);
     const parts = parseComposerTags(input);
@@ -45,10 +49,12 @@ export function prepareComposerResourceInput(input, cwd, workspacePath) {
         if (part.kind !== 'mar_references')
             return part.raw;
         return serializeComposerTag('mar_references', {
-            references: part.payload.references.map((reference) => ({
-                ...reference,
-                runnerPath: relative(cwd, resolve(workspacePath, reference.path)).replaceAll('\\', '/')
-            }))
+            references: part.payload.references.map((reference) => reference.type === 'session'
+                ? reference
+                : {
+                    ...reference,
+                    runnerPath: relative(cwd, resolve(workspacePath, reference.path)).replaceAll('\\', '/')
+                })
         });
     })
         .join('');

package/dist/service/runner-service.js

@@ -1,5 +1,6 @@
 import { runnerDefaultConfigurationSchema } from '@myagentroam/protocol';
 import { parseSecretEnvironment } from '../mcp/secret-environment.js';
+import { isPlainRecord } from '../util/records.js';
 export class RunnerService {
     database;
     capabilities;
@@ -85,7 +86,10 @@ export class RunnerService {
         };
     }
     saveDefaults(data) {
-        const parsed = runnerDefaultConfigurationSchema.safeParse(data);
+        if (!isPlainRecord(data))
+            throw new Error('RUNNER_DEFAULT_INVALID');
+        const { __workspaceWatchSessionHash: _sessionHash, __requestUserId: _userId, __usageGrant: _usageGrant, ...configuration } = data;
+        const parsed = runnerDefaultConfigurationSchema.safeParse(configuration);
         if (!parsed.success)
             throw new Error('RUNNER_DEFAULT_INVALID');
         if (parsed.data.runner === 'mar-agent' &&

package/dist/session/native-session-projection-service.js

@@ -29,11 +29,19 @@ export class NativeSessionProjectionService {
                 return accepted === undefined ? [] : [accepted];
             });
         }
+        const candidates = new Map(ordered.map((session) => [session.id, session]));
         return ordered.flatMap((session) => {
             const record = database.getSessionRecord(session.id);
-            if (record === undefined && session.parentSessionId != null)
+            if (record === undefined && !this.validParent(session, candidates))
                 return [];
-            return [{ ...session, parentSessionId: record?.metadata.parentSessionId ?? null }];
+            return [
+                {
+                    ...session,
+                    parentSessionId: record === undefined
+                        ? (session.parentSessionId ?? null)
+                        : (record.metadata.parentSessionId ?? null)
+                }
+            ];
         });
     }
     async discoverCodex(workspaceId) {
@@ -237,29 +245,30 @@ export class NativeSessionProjectionService {
             createdAt: timestamp
         };
     }
+    validParent(session, candidates) {
+        const database = this.options.database();
+        const visited = new Set([session.id]);
+        let parentId = session.parentSessionId ?? null;
+        let depth = 1;
+        while (parentId !== null) {
+            if (visited.has(parentId) || ++depth > 3)
+                return false;
+            visited.add(parentId);
+            const stored = database?.getSessionRecord(parentId);
+            const candidate = stored === undefined ? candidates.get(parentId) : undefined;
+            if ((stored?.workspaceId ?? candidate?.workspaceId) !== session.workspaceId)
+                return false;
+            parentId =
+                stored === undefined
+                    ? (candidate?.parentSessionId ?? null)
+                    : (stored.metadata.parentSessionId ?? null);
+        }
+        return true;
+    }
     remember(sessions) {
         const database = this.options.database();
         const candidates = new Map(sessions.map((session) => [session.id, session]));
-        const validParent = (session) => {
-            const visited = new Set([session.id]);
-            let parentId = session.parentSessionId ?? null;
-            let depth = 1;
-            while (parentId !== null) {
-                if (visited.has(parentId) || ++depth > 3)
-                    return false;
-                visited.add(parentId);
-                const stored = database?.getSessionRecord(parentId);
-                const candidate = stored === undefined ? candidates.get(parentId) : undefined;
-                if ((stored?.workspaceId ?? candidate?.workspaceId) !== session.workspaceId)
-                    return false;
-                parentId =
-                    stored === undefined
-                        ? (candidate?.parentSessionId ?? null)
-                        : (stored.metadata.parentSessionId ?? null);
-            }
-            return true;
-        };
-        const valid = new Map(sessions.map((session) => [session.id, validParent(session)]));
+        const valid = new Map(sessions.map((session) => [session.id, this.validParent(session, candidates)]));
         const accepted = sessions.flatMap((proposed) => {
             const metadata = database === undefined || proposed.externalSessionId === null
                 ? undefined

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

@@ -322,7 +322,7 @@ export class SessionCatalogService {
             this.options.invalidateWorkspaceSessions(session.workspaceId);
         }
     }
-    async removeTree(root) {
+    async removeTree(root, cleanup) {
         if (root.externalSessionId === null)
             throw new Error('NATIVE_TRANSCRIPT_UNAVAILABLE');
         const database = this.options.database();
@@ -340,13 +340,20 @@ export class SessionCatalogService {
         const ids = [root.externalSessionId];
         const seen = new Set(ids);
         const parents = new Map();
+        const settle = (session, deleted) => {
+            if (cleanup === undefined)
+                return;
+            database.deleteSessionRecord(session.id);
+            this.options.forget(session, this.options.nativeIds(session));
+            cleanup.settled(session, deleted);
+        };
         const releases = [];
         const locked = new Set();
         const lock = (id) => {
             const actual = this.options.runtime.getAgentSession(id)?.id ?? id;
             if (locked.has(actual))
                 return;
-            releases.push(this.options.runtime.beginSessionHistoryMutation(actual, { allowQueued: true }));
+            releases.push(this.options.runtime.beginSessionHistoryMutation(actual, cleanup !== undefined && actual === root.id ? undefined : { allowQueued: true }));
             locked.add(actual);
         };
         try {
@@ -355,6 +362,9 @@ export class SessionCatalogService {
                 const parent = ids[index];
                 const children = [
                     ...database.listChildSessionRecords(root.workspaceId, parent).map((record) => record.id),
+                    ...(cleanup?.children.get(parent) ?? [])
+                        .filter((session) => cleanup?.candidates.has(session.id))
+                        .map((session) => session.externalSessionId ?? session.id),
                     ...(liveChildren.get(parent) ?? [])
                 ];
                 for (const child of children) {
@@ -371,35 +381,64 @@ export class SessionCatalogService {
             }
             const sessions = [];
             for (const id of ids) {
-                const session = this.options.runtime.getAgentSession(id) ??
+                const session = cleanup?.candidates.get(id) ??
+                    this.options.runtime.getAgentSession(id) ??
                     (await this.options.projection.resolve(id, true));
                 if (session === undefined || session.workspaceId !== root.workspaceId)
                     throw new Error('SESSION_NOT_FOUND');
                 sessions.push(session);
             }
             // Validate every member before performing any irreversible native deletion.
-            for (const session of sessions)
-                await this.assertRemovable(session);
-            const batches = new Map();
+            for (const session of sessions) {
+                const missing = cleanup !== undefined && session.externalDiscovered === false;
+                if (missing && !this.options.runnerAvailable(session.runner))
+                    throw new Error('NATIVE_TRANSCRIPT_UNAVAILABLE');
+                await this.assertRemovable(session, cleanup?.budget, missing);
+            }
+            if (cleanup !== undefined && this.cleanupRootProtected(root, cleanup.cutoff)) {
+                throw new Error('SESSION_WATCHING');
+            }
+            let batch = [];
+            const flushBatch = async () => {
+                if (batch.length === 0)
+                    return;
+                cleanup?.budget.check();
+                await this.options.runners.require(batch[0].runner).removeNativeMembers(batch);
+                for (const session of batch)
+                    settle(session, true);
+                batch = [];
+            };
             for (const session of [...sessions].reverse()) {
+                if (cleanup !== undefined &&
+                    (session.externalSessionId === null || session.externalDiscovered === false)) {
+                    await flushBatch();
+                    cleanup.budget.check();
+                    settle(session, true);
+                    continue;
+                }
                 if (session.externalSessionId === null)
                     continue;
                 const runner = this.options.runners.require(session.runner);
                 if (runner.supportsNativeBatchRemoval?.() === true) {
-                    const members = batches.get(session.runner) ?? [];
-                    members.push(session);
-                    batches.set(session.runner, members);
+                    if (batch.length > 0 && batch[0].runner !== session.runner)
+                        await flushBatch();
+                    batch.push(session);
+                }
+                else {
+                    // Preserve descendant-first order across batch and non-batch native owners.
+                    await flushBatch();
+                    cleanup?.budget.check();
+                    const deleted = await this.removeNativeHistories(session, this.options.nativeIds(session));
+                    settle(session, deleted);
                 }
-                else
-                    await this.removeNativeHistories(session, this.options.nativeIds(session));
             }
-            for (const [runner, members] of batches)
-                await this.options.runners.require(runner).removeNativeMembers(members);
-            // Preserve every relationship if any native owner fails, so retries cannot
-            // lose sight of descendants whose native cleanup was already attempted.
-            for (const session of sessions.reverse()) {
-                this.options.database().deleteSessionRecord(session.id);
-                this.options.forget(session, this.options.nativeIds(session));
+            await flushBatch();
+            // Manual deletion preserves all relationships if any native owner fails.
+            if (cleanup === undefined) {
+                for (const session of sessions.reverse()) {
+                    this.options.database().deleteSessionRecord(session.id);
+                    this.options.forget(session, this.options.nativeIds(session));
+                }
             }
         }
         finally {
@@ -443,6 +482,7 @@ export class SessionCatalogService {
         let deleted = 0;
         let skipped = 0;
         let failed = 0;
+        const outcomes = new Map();
         const deletedByRunner = {};
         let candidateCount;
         let timedOut = false;
@@ -458,7 +498,14 @@ export class SessionCatalogService {
                 candidates.set(session.id, session);
             }
             this.mergePersisted(candidates, workspaceId, false);
-            const candidateParents = new Set([...candidates.values()].flatMap((candidate) => candidate.parentSessionId === null ? [] : [candidate.parentSessionId]));
+            const children = new Map();
+            for (const candidate of candidates.values()) {
+                if (candidate.parentSessionId == null)
+                    continue;
+                const siblings = children.get(candidate.parentSessionId) ?? [];
+                siblings.push(candidate);
+                children.set(candidate.parentSessionId, siblings);
+            }
             candidateCount = candidates.size;
             for (const session of candidates.values()) {
                 budget.check();
@@ -472,14 +519,6 @@ export class SessionCatalogService {
                         session.lastActivityAt > 0 &&
                         session.lastActivityAt >= cutoff) ||
                     (session.pinOrder !== null && session.pinOrder !== undefined) ||
-                    (session.externalSessionId !== null &&
-                        (this.options.database().listChildSessionRecords(workspaceId, session.externalSessionId)
-                            .length > 0 ||
-                            candidateParents.has(session.externalSessionId) ||
-                            this.options.runtime
-                                .listAgentSessions()
-                                .some((child) => child.workspaceId === workspaceId &&
-                                child.parentSessionId === session.externalSessionId))) ||
                     this.options.isWatching(session.id) ||
                     this.options.isRecovering?.(session.id) ||
                     this.options.runtime.sessionQueue(session.id).itemIds.length > 0 ||
@@ -487,24 +526,31 @@ export class SessionCatalogService {
                         .listRunsForSession(session.id)
                         .some((run) => !isTerminalRunStatus(run.status)) ||
                     this.options.externalActivity(session.id) === 'BUSY') {
-                    skipped += 1;
+                    outcomes.set(session.id, { session, status: 'skipped' });
                     continue;
                 }
                 try {
-                    if ((await this.removeResolved(session, true, budget)) === 'deleted') {
-                        deleted += 1;
-                        deletedByRunner[session.runner] = (deletedByRunner[session.runner] ?? 0) + 1;
-                    }
-                    else
-                        skipped += 1;
+                    await this.removeTree(session, {
+                        candidates,
+                        children,
+                        cutoff,
+                        budget,
+                        settled: (member, wasDeleted) => {
+                            candidates.delete(member.id);
+                            outcomes.set(member.id, {
+                                session: member,
+                                status: wasDeleted ? 'deleted' : 'skipped'
+                            });
+                        }
+                    });
                 }
                 catch (error) {
                     if (error instanceof WorkspaceSessionCleanupDeadline)
                         throw error;
                     if (isCleanupSkip(error))
-                        skipped += 1;
+                        outcomes.set(session.id, { session, status: 'skipped' });
                     else {
-                        failed += 1;
+                        outcomes.set(session.id, { session, status: 'failed' });
                         nodeLog('workspace.session.cleanup.failed', {
                             workspaceId,
                             sessionId: session.id,
@@ -514,6 +560,7 @@ export class SessionCatalogService {
                     }
                 }
             }
+            budget.check();
         }
         catch (error) {
             if (!(error instanceof WorkspaceSessionCleanupDeadline))
@@ -525,6 +572,16 @@ export class SessionCatalogService {
         finally {
             this.options.invalidateWorkspaceSessions(workspaceId);
         }
+        for (const { session, status } of outcomes.values()) {
+            if (status === 'deleted') {
+                deleted += 1;
+                deletedByRunner[session.runner] = (deletedByRunner[session.runner] ?? 0) + 1;
+            }
+            else if (status === 'skipped')
+                skipped += 1;
+            else
+                failed += 1;
+        }
         const result = {
             deleted,
             skipped,
@@ -535,7 +592,7 @@ export class SessionCatalogService {
                     timedOut: true,
                     ...(candidateCount === undefined
                         ? {}
-                        : { remaining: candidateCount - deleted - skipped - failed })
+                        : { remaining: Math.max(0, candidateCount - outcomes.size) })
                 }
                 : {})
         };
@@ -559,15 +616,16 @@ export class SessionCatalogService {
             lastActivityAt: latestSessionActivityAt(projected.lastActivityAt, native.lastActivityAt)
         };
     }
-    async assertRemovable(session) {
+    async assertRemovable(session, budget, missing = false) {
         if (this.options.isRecovering?.(session.id))
             throw new Error('SESSION_RESTART_PENDING');
         if (this.options.runtime
             .listRunsForSession(session.id)
             .some((run) => !isTerminalRunStatus(run.status)))
             throw new Error('SESSION_ACTIVE');
-        if (session.externalSessionId !== null && session.nativeControl === 'EXTERNAL') {
-            await this.options.refreshActivity(session);
+        if (!missing && session.externalSessionId !== null && session.nativeControl === 'EXTERNAL') {
+            const refresh = () => this.options.refreshActivity(session);
+            await (budget ? budget.read(refresh) : refresh());
             if (this.options.externalActivity(session.id) === 'BUSY')
                 throw new Error('SESSION_ACTIVE');
         }
@@ -592,55 +650,22 @@ export class SessionCatalogService {
         }
         return deleted;
     }
-    async removeResolved(session, requireCleanupSafety = false, budget) {
-        if (session.externalSessionId === null)
-            throw new Error('NATIVE_TRANSCRIPT_UNAVAILABLE');
-        const releaseMutation = this.options.runtime.beginSessionHistoryMutation(session.id, requireCleanupSafety ? undefined : { allowQueued: true });
-        try {
-            if (this.options.isRecovering?.(session.id))
-                throw new Error('SESSION_RESTART_PENDING');
-            const missingCandidate = requireCleanupSafety && session.externalDiscovered === false;
-            if (this.options.runtime
+    cleanupRootProtected(session, cutoff) {
+        // Pin updates and Watch admission do not share the history mutation queue.
+        const pinOrder = session.externalSessionId === null
+            ? undefined
+            : this.options
+                .database()
+                .getNativeSessionMetadata(session.runner, session.externalSessionId, session.workspaceId)?.pinOrder;
+        return ((session.externalDiscovered !== false &&
+            latestSessionActivityAt(session.lastActivityAt, this.options.runtime.getAgentSession(session.id)?.lastActivityAt ?? 0) >= cutoff) ||
+            (pinOrder !== undefined && pinOrder !== null) ||
+            this.options.isWatching(session.id) ||
+            this.options.isRecovering?.(session.id) === true ||
+            this.options.runtime.sessionQueue(session.id).itemIds.length > 0 ||
+            this.options.runtime
                 .listRunsForSession(session.id)
-                .some((run) => !isTerminalRunStatus(run.status)))
-                throw new Error('SESSION_ACTIVE');
-            if (session.nativeControl === 'EXTERNAL' && !missingCandidate) {
-                const refresh = () => this.options.refreshActivity(session);
-                await (budget ? budget.read(refresh) : refresh());
-                if (this.options.externalActivity(session.id) === 'BUSY')
-                    throw new Error('SESSION_ACTIVE');
-            }
-            if (requireCleanupSafety) {
-                if (this.options.isWatching(session.id))
-                    throw new Error('SESSION_WATCHING');
-                if (this.options.runtime.sessionQueue(session.id).itemIds.length > 0)
-                    throw new Error('SESSION_QUEUE_NOT_EMPTY');
-                // Pin updates do not share the cleanup mutation queue.
-                const pinOrder = this.options
-                    .database()
-                    .getNativeSessionMetadata(session.runner, session.externalSessionId, session.workspaceId)?.pinOrder;
-                if (pinOrder !== undefined && pinOrder !== null)
-                    return 'skipped';
-                if (this.options.runtime
-                    .listRunsForSession(session.id)
-                    .some((run) => !isTerminalRunStatus(run.status)))
-                    throw new Error('SESSION_ACTIVE');
-            }
-            budget?.check();
-            const nativeIds = this.options.nativeIds(session);
-            if (missingCandidate) {
-                this.options.database().deleteSessionRecord(session.id);
-                this.options.forget(session, nativeIds);
-                return 'deleted';
-            }
-            const deleted = await this.removeNativeHistories(session, nativeIds);
-            this.options.database().deleteSessionRecord(session.id);
-            this.options.forget(session, nativeIds);
-            return deleted ? 'deleted' : 'skipped';
-        }
-        finally {
-            releaseMutation();
-        }
+                .some((run) => !isTerminalRunStatus(run.status)));
     }
 }
 export function rewindTitle(sourceTitle, existingTitles = []) {
@@ -674,6 +699,7 @@ function deduplicateNativeSessions(sessions) {
 function isCleanupSkip(error) {
     return (error instanceof Error &&
         (error.message === 'SESSION_ACTIVE' ||
+            error.message === 'SESSION_RESTART_PENDING' ||
             error.message === 'SESSION_NOT_FOUND' ||
             error.message === 'SESSION_QUEUE_NOT_EMPTY' ||
             error.message === 'SESSION_WATCHING' ||

package/dist/workspace/git.js

@@ -107,6 +107,18 @@ export async function readRestrictedDiff(workspacePath, fromRef, toRef) {
     }
     return { binary: false, text: result.text, truncated: result.truncated };
 }
+/** Returns a bounded, deterministic refs snapshot, or undefined when it cannot be compared. */
+export async function readGitRefsSnapshot(workspacePath, timeoutMs) {
+    if (timeoutMs <= 0)
+        return undefined;
+    try {
+        const result = await runReadOnlyGit(workspacePath, ['for-each-ref', '--sort=refname', '--format=%(refname)%00%(objectname)%00%(symref)'], { timeoutMs: Math.min(timeoutMs, GIT_TIMEOUT_MS), outputLimit: GIT_LARGE_OUTPUT_LIMIT });
+        return result.truncated ? undefined : result.output;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Fetches refs only; failures never expose remote URLs or authentication diagnostics. */
 export async function fetchGitRepository(workspacePath, timeoutMs) {
     if (timeoutMs <= 0)

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

@@ -2,7 +2,7 @@ import { lstat } from 'node:fs/promises';
 import { basename, posix, resolve } from 'node:path';
 import { publicErrorMessage } from '@myagentroam/protocol';
 import { nodeLog } from '../operational.js';
-import { GitCommandError, fetchGitRepository, isWorkspaceChangeVisible, listGitWorktrees, listGitSubmodules, readCurrentChangesSummary, resolveGitRepository, resolveWorkspaceGitRoot } from './git.js';
+import { GitCommandError, fetchGitRepository, readGitRefsSnapshot, isWorkspaceChangeVisible, listGitWorktrees, listGitSubmodules, readCurrentChangesSummary, resolveGitRepository, resolveWorkspaceGitRoot } from './git.js';
 const CACHE_TTL_MS = 5_000;
 const REPOSITORY_READ_CONCURRENCY = 4;
 const WORKTREE_READ_CONCURRENCY = 4;
@@ -37,7 +37,6 @@ export class WorkspaceChangeService {
         if (selected !== undefined)
             paths = [repositoryPath];
         else {
-            this.invalidate(workspace.id);
             const current = (await this.current(workspace));
             // Linked worktrees share the root's refs and must not fetch them twice.
             paths = current.repositories
@@ -49,15 +48,25 @@ export class WorkspaceChangeService {
             const results = await mapWithConcurrency(paths, REPOSITORY_READ_CONCURRENCY, async (path) => {
                 try {
                     if (performance.now() >= deadline)
-                        return false;
+                        return { success: false, updated: false };
                     const repository = selected ?? (await resolveGitRepository(root, path));
-                    return await fetchGitRepository(repository, Math.max(0, Math.floor(deadline - performance.now())));
+                    const remaining = () => Math.max(0, Math.floor(deadline - performance.now()));
+                    const before = await readGitRefsSnapshot(repository, remaining());
+                    const success = await fetchGitRepository(repository, remaining());
+                    const after = await readGitRefsSnapshot(repository, remaining());
+                    return {
+                        success,
+                        updated: before === undefined || after === undefined || !before.equals(after)
+                    };
                 }
                 catch {
-                    return false;
+                    return { success: false, updated: false };
                 }
             });
-            return { fetchFailed: results.some((success) => !success) };
+            return {
+                fetchFailed: results.some((result) => !result.success),
+                updated: results.some((result) => result.updated)
+            };
         }
         finally {
             // Fetch is request/user scoped, never coalesced with another user's credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.11.46",
+  "version": "0.11.48",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -38,10 +38,10 @@
     "sharp": "0.35.5",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.11.46",
-    "@myagentroam/marctl": "0.11.7",
-    "@myagentroam/protocol": "0.11.46",
-    "@myagentroam/code-navigation": "0.11.1"
+    "@myagentroam/agent": "0.11.48",
+    "@myagentroam/code-navigation": "0.11.1",
+    "@myagentroam/protocol": "0.11.48",
+    "@myagentroam/marctl": "0.11.9"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"