feat: subagent list use preparation + projection

packages/subagent/subagent/src/index.ts

@@ -20,8 +20,8 @@
  * continuation manager holds their `AgentHandle` directly and orders every turn
  * through the child's own inbox, so providers contribute only the detached
  * creation spec and see no handle, turn, or teardown. Direct-child discovery
- * independently interprets the optional session-query corpus and does not
- * require that continuation runtime.
+ * reads the live session store and optional session persistence directly and
+ * does not require that continuation runtime.
  *
  * Same-process providers are trusted typed collaborators. Requests, provider
  * descriptors, results, and lifecycle payloads are borrowed immutable values;
@@ -65,7 +65,7 @@ import type { ContinuableSetupContribution } from './activation-setup-registry.t
 import { listChildren as listSubagentChildren } from './list-children.ts'
 import type { SubagentListEntry } from './list-children.ts'
 import { snapshotSubagentDescriptor } from './descriptor.ts'
-import { subagentTimingProjectionDefinition } from './projection.ts'
+import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts'
 
 export * from './out-of-process.ts'
 export { SubagentRunId } from './types.ts'
@@ -118,7 +118,7 @@ export type {
 export type { ContinuableSetupContribution } from './activation-setup-registry.ts'
 export type { SubagentListEntry } from './list-children.ts'
 export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts'
-export type { SubagentTimingProjection } from './projection-types.ts'
+export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -190,6 +190,7 @@ export class SubagentService extends Service {
     })
     ctx.inject(['sessionProjections'], (projectionCtx) => {
       projectionCtx.sessionProjections.register(subagentTimingProjectionDefinition)
+      projectionCtx.sessionProjections.register(subagentIdentityProjectionDefinition)
     })
   }
 
@@ -283,22 +284,28 @@ export class SubagentService extends Service {
   }
 
   /**
-   * Enumerate the parent's direct session-backed subagents from the
-   * live-preferred session corpus without loading or resuming an Agent. Session
-   * query supplies lineage, candidate order, event reads, and live state; this
-   * service interprets descriptor mode, activity, and per-child diagnostics
-   * without consulting Agent registrations, Activations, or providers.
+   * Enumerate the parent's direct session-backed subagents without loading or
+   * resuming an Agent and without any query seam: the listing merges the live
+   * session store with optional session persistence (live-preferred) and
+   * serves each child's durable mode/label from the registered `subagent`
+   * projection unit — the registry's watermark snapshot for a live child, one
+   * persistence inspection folded through the registry for a cold one. The
+   * projection fold is the single classification authority; per-child
+   * diagnostics relay a fold that served no identity or a failed inspection,
+   * never a list-time descriptor parse. Absent persistence, enumeration is
+   * live-only (a cold child cannot be resumed then either, so its absence is
+   * capability absence, not an error). This service consults no Agent
+   * registrations, Activations, or providers.
    *
-   * The trace and exact descriptor read receive `signal`; the full event-list
-   * read has no signal parameter, so the scan rechecks cancellation around
-   * every await and between candidates. Query rejections that settle after an
-   * abort become a stable `SubagentError` with code `CANCELLED`.
+   * Every persistence read receives `signal`, and the listing rechecks
+   * cancellation around each of those awaits. Read rejections that settle
+   * after an abort become a stable `SubagentError` with code `CANCELLED`.
    * @param parentSessionId - parent session whose direct children are listed.
-   * @param signal - caller-owned cancellation forwarded where supported and
-   *   observed around every query await.
-   * @returns children and per-child diagnostics in stable trace order.
-   * @throws {@link SubagentError} when session query is unavailable or the
-   *   caller cancels the scan.
+   * @param signal - caller-owned cancellation forwarded to persistence reads
+   *   and observed around every read await.
+   * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+   * @throws {@link SubagentError} when the projection registry is not mounted
+   *   or the caller cancels the listing.
    */
   listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]> {
     return listSubagentChildren(this.ctx, parentSessionId, signal)