Tianyi Cui
9dcc8fa985
Integrate master 78ae4fc2d4d8ecaebb4b674028f781a358b92cc9 after the four independent review fixes. Keep this base update separate from those fixes and from subsequent review changes so the integration is independently reviewable and the observed-master checkpoint remains preserved. Retain activation-owned execution, caller-independent local discovery, and unconditional parent final-answer delivery. Preserve master's preset scoped scheduling tools and all delegated-child schedule deny rules. Move the new scheduling regression from the removed driver package into the surviving subagent package and run it through a real Spawn activation. Preserve master's removal of runtime invariant plugins, dependencies, exports, and test mounts. Keep context disposal before fixture directory cleanup. Combine Python workflow ordering with activation/catalog events without inventing unsupported source-plane import paths. Keep all frozen Agent Note archives byte-for-byte identical to master; do not accept Git's automatic edits to renamed archived notes. Retain current lifecycle and delivery facts in active documentation, repair its links, and regenerate catalogs/persistence schemas from merged source. All 62 master persistence roots remain; only subagent/catalog gains the PR's external membership extension. Keep master's third-party lock graph and update only workspace dependency changes. Validation before this checkpoint: 683 focused tests passed, seven Windows-only cases skipped; 2,772 archived artifacts verified. Generated catalog and active-pair checks passed. Fresh artifact build and remaining build-dependent documentation checks continue before publication.
6.5 KiB
Agent Note: Parent-owned subagent catalog events
Status: implemented
English | 中文
Problem
Direct-child discovery once reconstructed a catalog from the global Session corpus and each selected child's log. Creation already knows the direct parent, child id, mode, and label, so repository-wide enumeration and child-log reads duplicated an owned fact and made browser refresh cost depend on unrelated Sessions.
The child descriptor remains necessary for recovery and composition, but it cannot be the discovery source because a reader must find and open the child before it can read the descriptor. Forks add a separate requirement: a seeded copy of a parent log must not inherit the original Session's children.
Decision
The shared activation entry point, external execution ownership, and caller-versus-parent result delivery are governed by Unified subagent activations. This record retains the independent rationale described below.
The parent Session's required subagent/catalog events are the persistent authority for direct-child discovery. Every local child enters the catalog independently of its result recipient; external children enter only with parent delivery. Workflow membership records describe execution progress and do not replace local Session discovery. Each event contains childId, childCreatedAt, mode, and the mode-discriminated label. Local children use continuable; external executions use external and cannot be opened as local Sessions. Historical one-shot and unknown entries remain readable. Invalid own facts, including unsupported payload versions, reject projection restoration because silently dropping a required fact would return an incomplete catalog.
Creation publishes only successful facts. A local activation admits the initial prompt before appending its catalog event. An external activation appends its event after provider startup and before returning the receipt. Failed admission or publication releases the unpublished execution; there is no compensating catalog event or rollback protocol.
The child header and subagent/descriptor remain authoritative for recovery and composition. An Activation and the exact parent relationship remain authoritative for authorization and delivery. Mode and label are snapshotted once and the same detached values reach the parent catalog fact and child descriptor.
The registered subagentCatalog projection materializes the parent facts. It delegates storage, append, iteration, and checkpoint validation to dsh-chunked-list, which stores facts in a persistent stack of 64-entry chunks, so an append copies at most the head chunk in bounded O(1) work. Materialization visits chunks from oldest to newest and preserves parent catalog event order in O(D) time for D facts. Concurrent creation is ordered by successful catalog append, independent of child timestamps and ids. A projection checkpoint clones the state once in O(D); projection-cache writes remain asynchronous and use the existing mandatory creation, turn-end, and disposal points.
The utility owns chunk layout and its shared capacity constant; the catalog owns event validation, fork filtering, and row conversion. Catalog projection state version 6 accepts external membership, so the projection registry rebuilds incompatible caches from Session events. Payload v0 and v1 remain unchanged; v2 records external executions.
Fork isolation uses the exact Session.inheritedEventCount supplied to projection initialization. The fold ignores subagent/catalog events below that offset. The state stores the inherited offset but not each event seq because acceptance is decided during folding.
Headless snapshot collection assigns sibling fixture roles by their parent catalog order, regardless of child creation timestamps: provider startup can publish an older Session after a newer one. The collection preserves each log verbatim.
Snapshot normalizers zero childCreatedAt because it originates from the process clock. Event order and source-event references remain intact: adjacent facts can come from sequential creation, so adjacency does not establish commutativity.
Current-writer snapshot expectations include catalog facts even when replay input retains a historical Session generation. The comparison preserves the catalog and its source-event references; historical replay files remain unchanged.
Alternatives considered
A flat immutable array. Appending with [...facts, fact] copies D facts, so creation is O(D). Mutating a shared array would violate projection state ownership and checkpoint safety.
A node-per-fact linked list. It provides O(1) append and O(D) read, but persisted projection checkpoints form JSON nested D levels deep. Sixty-four-entry chunks preserve the asymptotic costs while reducing nesting.
Separate host-state observation output. Returning internal projection states duplicates the existing observation result mechanism and copies states unrelated to child discovery. A catalog view supplies the direct-child list through the existing typed projection map.
A durable SQLite child index. An index would create another write path, reconciliation protocol, schema, and corruption surface for a fact already ordered in the parent Session log.
A compensating failure event. Recording catalog membership before initial prompt admission requires a second operation, pairing rules, rollback cleanup, and client reconciliation. Delaying the success fact until admission completes removes that protocol.
Consequences
Session observations and client snapshots expose the direct-child list through projections.values.subagentCatalog. The projection change feed publishes a complete list when catalog state changes. Each view costs O(D), so D creations can incur O(D²) cumulative view work; this follows the existing projection mechanism. listChildren() reads the parent projection through one live-preferred Session observation; descendant listing recursively calls the same reader in catalog order. Reachable catalog facts supply identity and membership without a global Session scan or a separate child-identity cache path. Unreadable branches remain diagnostics; uncataloged Sessions are outside discovery. Web projection consumption owns browser loading and synchronization.
Creation metadata exclusion records why model configuration is absent from catalog facts.