@xneog/dsh-subagent 0.1.0 → 0.1.3-alpha.1

package/lib/types/internal.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Continuation integration markers and host adapters outside the public
+ * Service Definition and model-facing Agent messaging contract.
+ * @module @xneog/dsh-subagent/internal
+ */
+import type { Agent } from '@xneog/dsh-agent';
+import type { ContentBlock, MessageId, MessageSource } from '@xneog/dsh-llm';
+import type { SessionId } from '@xneog/dsh-session';
+import type { ToolDefinition } from '@xneog/dsh-tools';
+import type SubagentRuntime from './index.ts';
+/** Process-stable identity carried only by the standard adjacent-Agent messaging tool. */
+export declare const adjacentAgentSendMessageTool: unique symbol;
+/**
+ * Mark the standard adjacent-Agent messaging tool without changing its model-visible schema.
+ * @param definition - the standard `send_message` definition.
+ * @returns the same definition with its internal identity installed.
+ */
+export declare function markAdjacentAgentSendMessageTool(definition: ToolDefinition): ToolDefinition;
+/**
+ * Test whether one visible definition is the standard adjacent-Agent messaging tool.
+ * @param definition - the scope-resolved `send_message` candidate.
+ * @returns whether the definition carries the internal standard-tool identity.
+ */
+export declare function isAdjacentAgentSendMessageTool(definition: ToolDefinition | undefined): boolean;
+/**
+ * Process-stable symbol-keyed host delivery shared by the bundled runtime
+ * entry and this unbundled internal subpath.
+ * @internal
+ */
+export declare const deliverSubagentPrompt: unique symbol;
+/** Scheduling mode for one host-only direct-child prompt. */
+export type HostPromptDeliveryMode = 'queue' | 'steer';
+/** Runtime face required by the host-only prompt adapters. */
+export interface HostPromptDeliverer {
+    [deliverSubagentPrompt](parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal, delivery: HostPromptDeliveryMode): Promise<MessageId>;
+}
+/**
+ * Queue one host-protocol message without exposing another Service operation.
+ * @param runtime - subagent runtime owning continuation residency.
+ * @param parent - exact live direct parent authorizing delivery.
+ * @param childId - durable direct-child session id.
+ * @param content - host-authored content to deliver.
+ * @param source - durable host-protocol provenance.
+ * @param signal - caller cancellation before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ */
+export declare function queueHostSubagentPrompt(runtime: SubagentRuntime, parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal): Promise<MessageId>;
+/**
+ * Steer one host-protocol message without exposing another Service operation.
+ * @param runtime - subagent runtime owning continuation residency.
+ * @param parent - exact live direct parent authorizing delivery.
+ * @param childId - durable direct-child session id.
+ * @param content - host-authored content to deliver.
+ * @param source - durable host-protocol provenance.
+ * @param signal - caller cancellation before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ */
+export declare function steerHostSubagentPrompt(runtime: SubagentRuntime, parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal): Promise<MessageId>;
+//# sourceMappingURL=internal.d.ts.map

package/lib/types/internal.js

@@ -0,0 +1,58 @@
+/**
+ * Continuation integration markers and host adapters outside the public
+ * Service Definition and model-facing Agent messaging contract.
+ * @module @xneog/dsh-subagent/internal
+ */
+/** Process-stable identity carried only by the standard adjacent-Agent messaging tool. */
+export const adjacentAgentSendMessageTool = Symbol.for('dsh.subagent.adjacentAgentSendMessageTool');
+/**
+ * Mark the standard adjacent-Agent messaging tool without changing its model-visible schema.
+ * @param definition - the standard `send_message` definition.
+ * @returns the same definition with its internal identity installed.
+ */
+export function markAdjacentAgentSendMessageTool(definition) {
+    Object.defineProperty(definition, adjacentAgentSendMessageTool, { value: true });
+    return definition;
+}
+/**
+ * Test whether one visible definition is the standard adjacent-Agent messaging tool.
+ * @param definition - the scope-resolved `send_message` candidate.
+ * @returns whether the definition carries the internal standard-tool identity.
+ */
+export function isAdjacentAgentSendMessageTool(definition) {
+    return definition !== undefined
+        && definition[adjacentAgentSendMessageTool] === true;
+}
+/**
+ * Process-stable symbol-keyed host delivery shared by the bundled runtime
+ * entry and this unbundled internal subpath.
+ * @internal
+ */
+export const deliverSubagentPrompt = Symbol.for('dsh.subagent.deliverPrompt');
+/**
+ * Queue one host-protocol message without exposing another Service operation.
+ * @param runtime - subagent runtime owning continuation residency.
+ * @param parent - exact live direct parent authorizing delivery.
+ * @param childId - durable direct-child session id.
+ * @param content - host-authored content to deliver.
+ * @param source - durable host-protocol provenance.
+ * @param signal - caller cancellation before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ */
+export function queueHostSubagentPrompt(runtime, parent, childId, content, source, signal) {
+    return runtime[deliverSubagentPrompt](parent, childId, content, source, signal, 'queue');
+}
+/**
+ * Steer one host-protocol message without exposing another Service operation.
+ * @param runtime - subagent runtime owning continuation residency.
+ * @param parent - exact live direct parent authorizing delivery.
+ * @param childId - durable direct-child session id.
+ * @param content - host-authored content to deliver.
+ * @param source - durable host-protocol provenance.
+ * @param signal - caller cancellation before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ */
+export function steerHostSubagentPrompt(runtime, parent, childId, content, source, signal) {
+    return runtime[deliverSubagentPrompt](parent, childId, content, source, signal, 'steer');
+}
+//# sourceMappingURL=internal.js.map

package/lib/types/lifecycle.js

@@ -15,6 +15,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { foldConsumedWork } from '@xneog/dsh-agent';
+import { SessionLogOffset } from '@xneog/dsh-session';
 import { finalAssistantOutput } from "./assistant-output.js";
 import { SubagentRunId } from "./types.js";
 /**
@@ -90,7 +91,7 @@ export function createActivationObserver(emit, provider, childId, parent) {
     // A cold resume replays earlier turns, so this epoch's telemetry must come
     // from the suffix it actually produced — never the whole session, which
     // would report a previous epoch's answer when this one opened no turn.
-    let boundary = 0;
+    let boundary = SessionLogOffset(0);
     // Assigned by `capture()`, which the disposal path always runs before
     // `settle()`; a resident epoch therefore always has its facts by then.
     let captured = { stopReason: 'completed' };
@@ -101,11 +102,11 @@ export function createActivationObserver(emit, provider, childId, parent) {
         : { stopReason: 'error' };
     return {
         start: (child) => {
-            boundary = child.session.events.length;
+            boundary = child.session.seq;
             emit('subagent/start', identity, parent);
         },
         capture: (child) => {
-            const own = child.session.events.slice(boundary);
+            const own = child.session.snapshotEvents(boundary);
             const output = finalAssistantOutput(own);
             captured = {
                 stopReason: epochStopReason(own),

package/lib/types/list-children.d.ts

@@ -1,13 +1,14 @@
 /**
  * Read-only enumeration of durable subagent children and descendant trees
- * straight from the live session store and optional session persistence — no
- * query service. Candidates come from one live-preferred corpus; each child's
- * mode/label is the registered `subagent` projection unit's value, resolved
+ * through the Session query service. Candidates come from one live-preferred
+ * corpus; each child's mode/label is the registered `subagent` projection
+ * unit's value, resolved
  * down a three-rung ladder: the registry's watermark cache for a live child,
- * a durable projection-cache row when it serves an own-suffix identity (the
- * seq gate), and one persistence inspection folded through the registry
- * otherwise, validated against the enumerated lifecycle. The projection fold
- * is the single classification authority — this module parses no descriptor
+ * an unseeded durable projection-cache row, and one shared Session observation
+ * otherwise. A seeded header deliberately lacks its exact inherited cut, so
+ * it takes the body-bearing observation path before classifying an identity.
+ * The projection fold is the single classification
+ * authority — this module parses no descriptor
  * itself. Absent persistence, enumeration is live-only: a cold child is
  * unreachable for resume anyway, so its absence is capability absence, not an
  * error. The module owns no catalog state and does not consult Activation,
@@ -17,55 +18,8 @@
  */
 import type { Context } from '@xneog/cordis';
 import type { SessionId } from '@xneog/dsh-session';
-/**
- * One entry of a {@link listChildren} result, ordered by header `createdAt`
- * with ties broken on id. Only a candidate whose durable header has
- * `origin: 'subagent'` is interpreted. A served `subagent` projection value
- * produces a `child`; a settled candidate whose fold served no identity
- * produces a `diagnostic`; a running candidate without one is omitted — its
- * descriptor may not be appended yet (the creation window). Diagnostics
- * relay the projection fold's outcome or a failed read, never a per-child
- * event scan, and never expose model-hidden descriptor content.
- */
-export type SubagentListEntry = {
-    readonly kind: 'child';
-    /** The durable child session id, stable across Activations. */
-    readonly id: SessionId;
-    /**
-     * Store snapshot activity: `running` means the logical record is live in
-     * `ctx.sessions`; `inactive` means it exists only in persistence. Neither
-     * encodes a durable outcome, and a continuable child may still reject
-     * delivery as an ownership conflict.
-     */
-    readonly activity: 'running' | 'inactive';
-    /** Whether a direct descendant has durable `origin: 'subagent'`. */
-    readonly hasChildren: boolean;
-} & ({
-    /** A terminal one-shot child. */
-    readonly mode: 'one-shot';
-    /** Optional durable creation label from the child's descriptor. */
-    readonly label?: string;
-} | {
-    /** A resumable conversation. */
-    readonly mode: 'continuable';
-    /** Durable creation label from the child's descriptor. */
-    readonly label: string;
-}) | {
-    readonly kind: 'diagnostic';
-    /** The candidate's session id. */
-    readonly id: SessionId;
-    /**
-     * Why the candidate has no `child` row: `corrupt` for a settled candidate
-     * whose projection fold served no identity (a missing, malformed, or
-     * unrecognized-version descriptor — deliberately undistinguished), and
-     * for any candidate whose log makes a registered unit's fold or schema
-     * throw (deterministic data damage, contained per child); `unavailable`
-     * when the candidate's persistence inspection failed (retried on the
-     * next listing). `unsupported` is never produced; it remains in the
-     * union for consumers that route on it.
-     */
-    readonly reason: 'corrupt' | 'unsupported' | 'unavailable';
-};
+import type { SubagentListEntry } from './control-types.ts';
+export type { SubagentListEntry } from './control-types.ts';
 /**
  * One entry of a descendant listing: the interpreted subagent facts plus its
  * position in the complete session tree. `parentId` is the durable direct
@@ -82,9 +36,8 @@ export type SubagentDescendantListEntry = SubagentListEntry & {
  * live-preferred merge of `ctx.sessions` and optional session persistence,
  * serving each identity from the `subagent` projection unit: the registry's
  * watermark snapshot for a live child; for a cold one, a durable
- * projection-cache row when it serves an own-suffix identity (the seq gate),
- * else one bounded-concurrency persistence inspection folded through the
- * registry.
+ * projection-cache read for an unseeded lifecycle, else one bounded-concurrency
+ * shared Session observation carrying the exact inherited cut.
  * @see SubagentRuntime.listChildren for the public cancellation and failure contract.
  * @param ctx - context carrying the session store, the projection registry,
  *   optional persistence, and the optional projection cache.

package/lib/types/list-children.js

@@ -1,13 +1,14 @@
 /**
  * Read-only enumeration of durable subagent children and descendant trees
- * straight from the live session store and optional session persistence — no
- * query service. Candidates come from one live-preferred corpus; each child's
- * mode/label is the registered `subagent` projection unit's value, resolved
+ * through the Session query service. Candidates come from one live-preferred
+ * corpus; each child's mode/label is the registered `subagent` projection
+ * unit's value, resolved
  * down a three-rung ladder: the registry's watermark cache for a live child,
- * a durable projection-cache row when it serves an own-suffix identity (the
- * seq gate), and one persistence inspection folded through the registry
- * otherwise, validated against the enumerated lifecycle. The projection fold
- * is the single classification authority — this module parses no descriptor
+ * an unseeded durable projection-cache row, and one shared Session observation
+ * otherwise. A seeded header deliberately lacks its exact inherited cut, so
+ * it takes the body-bearing observation path before classifying an identity.
+ * The projection fold is the single classification
+ * authority — this module parses no descriptor
  * itself. Absent persistence, enumeration is live-only: a cold child is
  * unreachable for resume anyway, so its absence is capability absence, not an
  * error. The module owns no catalog state and does not consult Activation,
@@ -15,11 +16,64 @@
  *
  * @module @xneog/dsh-subagent
  */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { SessionLogOffset } from '@xneog/dsh-session';
 import { SubagentError } from "./error.js";
 /**
- * Concurrent cold inspections per listing; a constant because it bounds one
- * read-only scan of local media, not deployment behavior. Should a networked
- * persistence backend appear, promote it to a validated `Config` field.
+ * Concurrent cold observations per explicit catalog listing. Current Session
+ * persistence providers are local; a networked provider must promote this to
+ * a validated deployment setting.
  */
 const COLD_READ_CONCURRENCY = 4;
 /**
@@ -27,9 +81,8 @@ const COLD_READ_CONCURRENCY = 4;
  * live-preferred merge of `ctx.sessions` and optional session persistence,
  * serving each identity from the `subagent` projection unit: the registry's
  * watermark snapshot for a live child; for a cold one, a durable
- * projection-cache row when it serves an own-suffix identity (the seq gate),
- * else one bounded-concurrency persistence inspection folded through the
- * registry.
+ * projection-cache read for an unseeded lifecycle, else one bounded-concurrency
+ * shared Session observation carrying the exact inherited cut.
  * @see SubagentRuntime.listChildren for the public cancellation and failure contract.
  * @param ctx - context carrying the session store, the projection registry,
  *   optional persistence, and the optional projection cache.
@@ -91,31 +144,32 @@ async function prepareListing(ctx, signal) {
         throw new SubagentError('listing subagents requires the session store (load @xneog/dsh-session)', 'SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE');
     }
     assertListingNotCancelled(signal);
-    const persistence = ctx.get('sessionPersistence');
+    const query = ctx.get('sessionQuery');
+    if (query === undefined) {
+        throw new SubagentError('listing subagents requires the sessionQuery service (load @xneog/dsh-session-query)', 'SUBAGENT_CONTROL_QUERY_UNAVAILABLE');
+    }
     // Optional acceleration only: an absent cache service just means every
     // cold candidate takes the authoritative preparation rung, so it carries
     // no error code and no configuration check.
     const cache = ctx.get('sessionProjectionCache');
-    let persistedHeaders = [];
-    if (persistence !== undefined) {
-        try {
-            persistedHeaders = await persistence.list(signal);
-        }
-        catch (error) {
-            // The backend may reject with its own abort failure after observing the
-            // forwarded signal; cancellation stays a stable subagent failure.
-            assertListingNotCancelled(signal);
-            throw error;
-        }
+    let records;
+    try {
+        records = await query.listSessions(signal);
+    }
+    catch (error) {
         assertListingNotCancelled(signal);
+        throw error;
     }
+    assertListingNotCancelled(signal);
     // Live-preferred merge without header reconciliation: a live record wins
     // its id wholesale, exactly as a live-preferred corpus would serve it.
     const corpus = new Map();
-    for (const header of persistedHeaders)
-        corpus.set(header.id, { header, live: undefined });
-    for (const session of sessions.list()) {
-        corpus.set(session.header.id, { header: session.header, live: session });
+    for (const record of records) {
+        const live = sessions.get(record.header.id);
+        corpus.set(record.header.id, {
+            header: live?.header ?? record.header,
+            live,
+        });
     }
     const subagentParents = new Set();
     for (const record of corpus.values()) {
@@ -123,11 +177,11 @@ async function prepareListing(ctx, signal) {
             subagentParents.add(record.header.parentSession);
         }
     }
-    return { projections, persistence, cache, corpus, subagentParents };
+    return { projections, query, cache, corpus, subagentParents };
 }
 /** Resolve projection-backed rows for aligned candidates with bounded cold reads. */
 async function resolveCandidateRows(candidates, listing, signal) {
-    const { projections, persistence, cache, subagentParents } = listing;
+    const { projections, query, cache, subagentParents } = listing;
     const rows = Array.from({ length: candidates.length });
     const coldReads = [];
     candidates.forEach((candidate, index) => {
@@ -136,34 +190,31 @@ async function resolveCandidateRows(candidates, listing, signal) {
             coldReads.push({ index, header: candidate.header });
             return;
         }
-        // The registry's watermark cache serves the live value with zero log
-        // reads; a live child without an identity yet is the creation window
-        // before the establishing provider appends its descriptor.
+        // Read only the identity unit. A live child without an identity yet is the
+        // creation window before the establishing provider appends its descriptor.
         let identity;
         try {
-            identity = projections.snapshot(candidate.live).values.subagent;
+            identity = projections.snapshot(candidate.live, ['subagent']).values.subagent;
         }
         catch {
-            // The snapshot folds EVERY registered unit over this child's log, so
-            // any unit's fold or schema can reject damaged payloads. That is
-            // deterministic data damage in this one child; it degrades to one
-            // corrupt diagnostic instead of failing the whole listing.
+            // A rejecting identity fold is deterministic data damage in this child;
+            // contain it as one diagnostic instead of failing the whole listing.
             rows[index] = { kind: 'diagnostic', id: childId, reason: 'corrupt' };
             return;
         }
         // The unit's serializable no-value sentinel is `null`; `undefined` can
         // only mean the key was dropped at a JSON boundary. Both are no value.
-        if (identity === undefined || identity === null)
+        if (identity === undefined || identity === null
+            || !candidate.live.isOwnSeq(identity.seq))
             return;
         rows[index] = childRow(childId, identity, 'running', subagentParents.has(childId));
     });
-    // Cold candidates exist only when persistence listed them, so the narrow
-    // re-check is about types, not reachability.
-    if (persistence !== undefined && coldReads.length > 0) {
+    // Cold candidates came from the query corpus and are resolved concurrently.
+    if (coldReads.length > 0) {
         const queue = [...coldReads];
         await Promise.all(Array.from({ length: Math.min(COLD_READ_CONCURRENCY, queue.length) }, async () => {
             for (let job = queue.shift(); job !== undefined; job = queue.shift()) {
-                rows[job.index] = await resolveColdIdentity(persistence, projections, cache, job.header, subagentParents.has(job.header.id), signal);
+                rows[job.index] = await resolveColdIdentity(query, cache, job.header, subagentParents.has(job.header.id), signal);
             }
         }));
     }
@@ -212,72 +263,82 @@ function compareCorpusRecords(a, b) {
     return a.header.createdAt - b.header.createdAt || a.header.id.localeCompare(b.header.id);
 }
 /**
- * Resolve one cold candidate down the remaining ladder: a durable
- * projection-cache row when it serves an own-suffix identity (the seq gate),
- * otherwise one persistence inspection folded through the projection
- * registry (the same detached recipe the API proxy uses for detached session
- * projections). A failed inspection is one transient `unavailable` row
- * retried on the next listing; an inspection naming another lifecycle, and a
+ * Resolve one cold candidate down the remaining ladder: an unseeded durable
+ * projection-cache row, otherwise one shared Session observation. An absent or transiently failed
+ * observation is one `unavailable` row retried on the next listing; an observation
+ * source naming another lifecycle, and a
  * settled log the fold cannot identify — or that makes any registered unit
  * throw — are final, so they report `corrupt`.
  */
-async function resolveColdIdentity(persistence, projections, cache, header, hasChildren, signal) {
-    const childId = header.id;
-    if (cache !== undefined) {
-        let cached;
-        try {
-            cached = cache.cachedSnapshot(header)?.values.subagent;
+async function resolveColdIdentity(query, cache, header, hasChildren, signal) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const childId = header.id;
+        // A header deliberately exposes only whether a fork cut exists, not its
+        // integer. An unseeded lifecycle has the exact cut 0 and may use the cache;
+        // a seeded lifecycle must read the body before an identity seq can be
+        // classified as inherited or owned.
+        if (cache !== undefined && !header.isSeeded) {
+            let cached;
+            try {
+                cached = cache.cachedSnapshot(header, SessionLogOffset(0), ['subagent'])?.values.subagent;
+            }
+            catch {
+                // Unlike the preparation fold below, a throwing cache read renders no
+                // verdict: the cache is derived data, so its damage (a poisoned stored
+                // row of ANY unit) silently falls through to the authoritative re-fold.
+                cached = undefined;
+            }
+            // An unseeded child's descriptor is owned at every valid seq. Everything
+            // else falls through to preparation: an absent key and the `null`
+            // sentinel, whose verdict belongs to the authoritative re-fold, not to a
+            // derived row.
+            if (cached !== undefined && cached !== null) {
+                return childRow(childId, cached, 'inactive', hasChildren);
+            }
         }
-        catch {
-            // Unlike the preparation fold below, a throwing cache read renders no
-            // verdict: the cache is derived data, so its damage (a poisoned stored
-            // row of ANY unit) silently falls through to the authoritative re-fold.
-            cached = undefined;
+        assertListingNotCancelled(signal);
+        let observation;
+        try {
+            observation = await query.observeSession(childId, {
+                ...(signal === undefined ? {} : { signal }),
+            });
         }
-        // A child's OWN descriptor is immutable once appended, so a cached
-        // identity is final only when the seq gate proves it was folded from the
-        // own suffix: a creation-window checkpoint may instead carry a fork
-        // seed's replayed ANCESTOR descriptor (seq below `seedLength`), which
-        // must not outrank the re-fold. Everything else also falls through to
-        // preparation: an absent key (a cut before any descriptor) and the
-        // `null` sentinel, whose verdict belongs to the authoritative re-fold,
-        // not to a derived row.
-        if (cached !== undefined && cached !== null && cached.seq >= (header.seedLength ?? 0)) {
-            return childRow(childId, cached, 'inactive', hasChildren);
+        catch (error) {
+            // Per-child isolation: durable corruption is stable; absence and backend
+            // failures remain retryable. Either way, the listing itself still succeeds.
+            assertListingNotCancelled(signal);
+            return {
+                kind: 'diagnostic',
+                id: childId,
+                reason: sessionQueryCode(error) === 'SESSION_QUERY_CORRUPT_SESSION'
+                    || sessionQueryCode(error) === 'SESSION_QUERY_SOURCE_CONFLICT'
+                    ? 'corrupt'
+                    : 'unavailable',
+            };
         }
-    }
-    assertListingNotCancelled(signal);
-    let inspected;
-    try {
-        inspected = await persistence.inspect(childId, signal);
-    }
-    catch {
-        // Per-child isolation: the child vanished or its backend read failed —
-        // one diagnostic row, and the listing itself still succeeds.
+        const ownedObservation = __addDisposableResource(env_1, observation, false);
         assertListingNotCancelled(signal);
-        return { kind: 'diagnostic', id: childId, reason: 'unavailable' };
-    }
-    assertListingNotCancelled(signal);
-    // A session id names a slot, not a lifecycle: a child deleted and
-    // re-published under another owner between the enumeration and this read
-    // must not leak into the old parent's listing.
-    if (!sameLifecycle(inspected.meta, header)) {
-        return { kind: 'diagnostic', id: childId, reason: 'corrupt' };
-    }
-    let identity;
-    try {
-        identity = projections.restore({}, inspected.events, 0).snapshot.values.subagent;
+        // A session id names a slot, not a lifecycle: a child deleted and
+        // re-published under another owner between the enumeration and this read
+        // must not leak into the old parent's listing.
+        if (!sameLifecycle(ownedObservation.header, header)) {
+            return { kind: 'diagnostic', id: childId, reason: 'corrupt' };
+        }
+        const identity = ownedObservation.projections?.values.subagent;
+        if (identity === undefined || identity === null
+            || identity.seq < ownedObservation.inheritedEventCount) {
+            return { kind: 'diagnostic', id: childId, reason: 'corrupt' };
+        }
+        return childRow(childId, identity, 'inactive', hasChildren);
     }
-    catch {
-        // The restore folds EVERY registered unit over this child's log, so any
-        // unit's fold or schema can reject damaged payloads — deterministic data
-        // damage in this one child, contained as its own corrupt diagnostic.
-        return { kind: 'diagnostic', id: childId, reason: 'corrupt' };
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
     }
-    if (identity === undefined || identity === null) {
-        return { kind: 'diagnostic', id: childId, reason: 'corrupt' };
+    finally {
+        __disposeResources(env_1);
     }
-    return childRow(childId, identity, 'inactive', hasChildren);
 }
 /** Materialize one served identity as its child row. */
 function childRow(id, identity, activity, hasChildren) {
@@ -301,7 +362,8 @@ function childRow(id, identity, activity, hasChildren) {
 }
 /** Immutable header fields that distinguish one session lifecycle from another under the same id. */
 const LIFECYCLE_WITNESS_KEYS = [
-    'version', 'id', 'createdAt', 'cwd', 'parentSession', 'seedLength', 'delegationDepth',
+    'version', 'id', 'createdAt', 'cwd', 'parentSession', 'isSeeded', 'delegationDepth',
+    'origin', 'agentPreset',
 ];
 /** Whether an inspected log still belongs to the enumerated lifecycle. */
 function sameLifecycle(meta, expected) {
@@ -313,4 +375,7 @@ function assertListingNotCancelled(signal) {
         throw new SubagentError('subagent listing was cancelled', 'CANCELLED');
     }
 }
+function sessionQueryCode(error) {
+    return error instanceof Error && 'code' in error ? error.code : undefined;
+}
 //# sourceMappingURL=list-children.js.map

package/lib/types/out-of-process.d.ts

@@ -15,7 +15,7 @@ import type { SubagentCapabilities, SubagentResult, SubagentRun, SubagentStopRea
 /**
  * The capability advertisement of an out-of-process backend: NONE. A child in
  * another process cannot honor parent-enforced start features
- * (`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+ * (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
  * request needing any of them before `start` runs — never accepted-then-ignored.
  */
 export declare const NO_START_CAPABILITIES: SubagentCapabilities;
@@ -69,6 +69,8 @@ export interface RunResultSettlement {
     attempt: () => Promise<SubagentResult>;
     /** Snapshot the provider exposes when cancellation or failure wins settlement. */
     collectOutput: () => ContentBlock[];
+    /** Snapshot safe provider-authored detail when a failure wins settlement. */
+    collectDiagnostic?: (() => string | undefined) | undefined;
     /** Whether local cancellation settled before the attempt's outcome is observed. */
     cancelled: () => boolean;
     /** Diagnostic sink for a failure flattened to a stop reason; a throw from it is contained. */
@@ -83,7 +85,8 @@ export interface RunResultSettlement {
  * rejects after publication. A normally completed or rejected attempt resolves
  * as `aborted` when cancellation already settled locally; another rejection is
  * flattened to `stopReason: 'error'` through the contained diagnostic sink.
- * The abort listener is removed on every path.
+ * Provider-returned diagnostics use the same byte limit. The abort listener is
+ * removed on every path.
  * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
  * @returns the terminal result (never a rejection).
  */