@myagentroam/node 0.11.47 → 0.11.49

package/dist/connector.js

@@ -67,7 +67,7 @@ import { SessionScheduleService } from './session/session-schedule-service.js';
 import { ScheduledSessionCoordinator } from './service/scheduled-session-coordinator.js';
 import { ScheduledSessionStore } from './service/scheduled-session-store.js';
 import { RunAuthorizationControl } from './service/run-authorization-control.js';
-import { PlannedRestartHandoff } from './service/planned-restart-handoff.js';
+import { PlannedRestartHandoff, plannedRestartCaptureDiagnostic } from './service/planned-restart-handoff.js';
 import { NodeUpgradeCredentialControl } from './service/node-upgrade-credential-control.js';
 import { RestartSessionRestorer } from './service/restart-session-restorer.js';
 import { ScheduleMcpBridge } from './service/schedule-mcp-bridge.js';
@@ -200,7 +200,8 @@ export class NodeConnector {
         publish: (snapshot) => this.restartHandoff.publish(snapshot),
         diagnose: (stage, error) => nodeLog('node.shutdown.failed', {
             stage,
-            errorCode: safeErrorCode(error, 'NODE_SHUTDOWN_FAILED')
+            errorCode: safeErrorCode(error, 'NODE_SHUTDOWN_FAILED'),
+            ...(stage === 'capture' ? plannedRestartCaptureDiagnostic(error) : undefined)
         })
     });
     get stopped() {
@@ -651,25 +652,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 +1098,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.' }
         }
     },
     {
@@ -131,7 +131,9 @@ const tools = [
 ];
 const delegationPrompt = [
     '# Delegation and coordination',
-    'Delegate bounded, self-contained tasks when independent progress or context savings materially helps. Keep simple or tightly coupled work local.',
+    'Handle focused or tightly coupled work locally by default.',
+    'Delegate a clearly separable subtask when parallel progress or context savings materially outweigh coordination overhead.',
+    'Do not split work merely because agents are available.',
     'Give each child an objective, necessary context, expected output, and a read-only boundary or non-overlapping write scope.',
     'Follow up through the direct delegate by default; inspect deeper Sessions only when a concrete issue needs independent verification.',
     'While children run, continue meaningful non-overlapping work. Do not redo delegated work. Wait only when the next step needs the result.',
@@ -140,7 +142,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 +157,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 +207,10 @@ export function agentNetworkExtension(invoke, currentExecution) {
                         'effort',
                         'waitFor',
                         'waitMs',
-                        'scope'
+                        'scope',
+                        'query',
+                        'limit',
+                        'cursor'
                     ],
                     inputSchema: {
                         type: 'object',
@@ -203,13 +223,20 @@ 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;
+                                (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) => ({

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/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,75 +351,12 @@ 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, onResolved) => {
             const source = terminalCalls.has(actor) ? undefined : await actorSession(actor);

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

@@ -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

@@ -90,6 +90,8 @@ 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();

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/planned-restart-handoff.js

@@ -84,6 +84,44 @@ const legacyPlannedRestartSchema = plannedRestartSchema.extend({
         })
     }))
 });
+// Only this producer can associate log-safe metadata with an original failure.
+const captureDiagnostics = new WeakMap();
+const captureFields = new Set([
+    ...Object.keys(plannedRestartSchema.shape),
+    ...Object.keys(sessionSchema.shape),
+    ...Object.keys(sessionSchema.shape.session.shape),
+    ...Object.keys(goalSchema.shape),
+    ...Object.keys(goalSchema.shape.goal.shape),
+    ...Object.keys(messageSchema.shape),
+    ...Object.keys(attachmentSchema.shape)
+]);
+export function plannedRestartCaptureDiagnostic(error) {
+    return error instanceof Error ? captureDiagnostics.get(error) : undefined;
+}
+function parseCapture(schema, input, reason) {
+    const result = schema.safeParse(input);
+    if (result.success)
+        return result.data;
+    captureDiagnostics.set(result.error, {
+        reason,
+        issues: result.error.issues.slice(0, 12).map((issue) => ({
+            code: issue.code,
+            // Only schema-owned fields and array offsets, never unknown keys or input values.
+            path: issue.path
+                .slice(0, 8)
+                .map((part) => typeof part === 'number'
+                ? `[${part}]`
+                : captureFields.has(String(part))
+                    ? String(part)
+                    : '*')
+                .join('.')
+                .replaceAll('.[', '[')
+                .slice(0, 160)
+        })),
+        issuesTruncated: result.error.issues.length > 12
+    });
+    throw result.error;
+}
 export const RESTART_NOTICE = 'The previous execution was interrupted by a system restart. Check the session history and current workspace, then continue unfinished work. Verify completed or uncertain actions before proceeding; do not blindly repeat actions with external side effects.';
 /** A one-shot orderly-shutdown handoff, not a crash-recovery journal. */
 export class PlannedRestartHandoff {
@@ -197,8 +235,13 @@ export class PlannedRestartHandoff {
                 : toMessage(currentId, pending.clientMessageId ?? active.clientMessageId, pending.restartMessage.content, [...pending.restartMessage.attachments], pending.restartMessage.initiatedByUserId ?? active?.initiatedByUserId, active?.suppressNotifications);
             if (current === undefined && items.length === 0 && goal === undefined && !awaitingGoal)
                 continue;
-            if (session.externalSessionId === null)
-                throw new Error('RESTART_SESSION_NOT_READY');
+            if (session.externalSessionId === null) {
+                const error = Object.assign(new Error('RESTART_SESSION_NOT_READY'), {
+                    code: 'RESTART_SESSION_NOT_READY'
+                });
+                captureDiagnostics.set(error, { reason: 'session_not_ready' });
+                throw error;
+            }
             const ownerUserId = active?.initiatedByUserId ??
                 items[0]?.initiatedByUserId ??
                 this.owners.get(session.id) ??
@@ -220,18 +263,20 @@ export class PlannedRestartHandoff {
                 ...(notificationSource?.suppressNotifications === true
                     ? { suppressNotifications: true }
                     : {}),
-                ...(goal === undefined ? {} : { goal: goalSchema.parse(goal) }),
+                ...(goal === undefined
+                    ? {}
+                    : { goal: parseCapture(goalSchema, goal, 'goal_schema_invalid') }),
                 ...(current === undefined ? {} : { current }),
                 queue: items
             });
         }
-        return plannedRestartSchema.parse({
+        return parseCapture(plannedRestartSchema, {
             schemaVersion: 2,
             id: randomUUID(),
             ...this.options.identity(),
             createdAt: Date.now(),
             sessions
-        });
+        }, 'snapshot_schema_invalid');
     }
     async publish(snapshot) {
         for (const entry of snapshot.sessions) {

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/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.47",
+  "version": "0.11.49",
   "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.49",
     "@myagentroam/code-navigation": "0.11.1",
-    "@myagentroam/marctl": "0.11.8",
-    "@myagentroam/agent": "0.11.47",
-    "@myagentroam/protocol": "0.11.47"
+    "@myagentroam/marctl": "0.11.9",
+    "@myagentroam/protocol": "0.11.49"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"