@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/subagent/lib/index.js

@@ -772,9 +772,10 @@ var SubagentContinuationManager = class {
 		const request = spec.request;
 		const parent = request.parent;
 		this.assertAdmitting(parent);
-		this.requirePersistence();
+		const persistence = this.requirePersistence();
 		assertSubagentMaxDepth(request.maxDepth);
-		const childId = SessionId(randomUUID());
+		const childId = spec.childId ?? SessionId(randomUUID());
+		this.assertChildIdAvailable(childId);
 		const childDepth = resolveChildDepth(parent, request.maxDepth);
 		const agentProvider = request.agentOptions?.provider ?? parent.options.provider;
 		const agentModel = request.agentOptions?.model ?? parent.options.model;
@@ -800,6 +801,16 @@ var SubagentContinuationManager = class {
 		return {
 			childId,
 			messageId: await this.locks.run(childId, async () => {
+				spec.signal.throwIfAborted();
+				this.assertAdmitting(parent);
+				this.assertChildIdAvailable(childId);
+				if (spec.childId !== void 0) {
+					const persisted = await persistence.listSnapshots(spec.signal);
+					spec.signal.throwIfAborted();
+					this.assertAdmitting(parent);
+					this.assertChildIdAvailable(childId);
+					if (persisted.some((snapshot) => snapshot.header.id === childId)) throw new SubagentError(`subagent "${childId}" already exists`, "DUPLICATE_CHILD");
+				}
 				const activation = await this.materialize({
 					childId,
 					provider: spec.provider,
@@ -820,6 +831,10 @@ var SubagentContinuationManager = class {
 			})
 		};
 	}
+	/** Reject one child identity already owned by a live Agent or Session. */
+	assertChildIdAvailable(childId) {
+		if (this.ctx.agents.get(childId) !== void 0 || this.ctx.get("sessions")?.get(childId) !== void 0) throw new SubagentError(`subagent "${childId}" already exists`, "DUPLICATE_CHILD");
+	}
 	/**
 	* Deliver one later message to a known continuable child as its next FIFO
 	* turn. Routing depends only on Activation residency: a `running` Activation
@@ -941,7 +956,7 @@ var SubagentContinuationManager = class {
 				senderSessionId: activation.childId
 			}
 		});
-		if (delivery === "wakeup") this.sendWaking(parent, message, () => {
+		if (delivery === "next-step") this.sendWaking(parent, message, () => {
 			this.sendReport(parent, message, delivery);
 		});
 		else this.sendReport(parent, message, delivery);
@@ -951,7 +966,7 @@ var SubagentContinuationManager = class {
 	* Perform one waking send to a parent, accounted against that parent's own
 	* Activation when it has one. Registering the id before the send is what
 	* keeps a continuation-managed parent from being judged quiescent in the
-	* window between `followup()` and the microtask that admits it.
+	* window between a waking send and the microtask that admits it.
 	* @param parent - the exact live parent receiving the waking message.
 	* @param message - the message whose id is accounted.
 	* @param send - the synchronous waking send to perform.
@@ -964,7 +979,7 @@ var SubagentContinuationManager = class {
 	/** Send one report while translating only the parent's own rejection. */
 	sendReport(parent, message, delivery) {
 		try {
-			if (delivery === "wakeup") parent.followup(message);
+			if (delivery === "next-step") parent.steer(message);
 			else parent.inject(message);
 		} catch (error) {
 			throw new SubagentError("direct parent is not live; report was not delivered", "PARENT_UNAVAILABLE", { cause: error });
@@ -1027,6 +1042,28 @@ var SubagentContinuationManager = class {
 		await Promise.all(materializations.map((materialization) => materialization.settled));
 		await this.disposeRoots(targetRoots, "scoped activation(s)");
 	}
+	/**
+	* Release selected resident direct children of one exact live parent without
+	* closing admission for the parent's other continuable children. Owned
+	* descendants are released recursively through the same lifecycle.
+	* @param parent - exact live direct parent authorizing the selected release.
+	* @param childIds - durable direct-child ids to release when resident.
+	* @returns once every selected Activation released its handle.
+	* @throws {SubagentError} `UNAUTHORIZED` when a resident target is not the
+	*   parent's direct continuable child or the parent identity is stale.
+	*/
+	async drainChildren(parent, childIds) {
+		if (this.ctx.agents.get(parent.id) !== parent) throw new SubagentError("selected child teardown requires the exact live parent agent", "UNAUTHORIZED");
+		const targets = [];
+		for (const childId of new Set(childIds)) {
+			const activation = this.activations.get(childId);
+			if (activation === void 0) continue;
+			if (activation.parentSession !== parent.id || !activation.ancestry.has(parent)) throw new SubagentError(`subagent "${childId}" is not a direct child of agent "${parent.id}"`, "UNAUTHORIZED");
+			targets.push(activation);
+		}
+		for (const activation of targets) this.dispose(activation).catch(() => void 0);
+		await this.disposeRoots(targets, "selected activation(s)");
+	}
 	/** Dispose independent roots and report every branch failure after all settle. */
 	async disposeRoots(roots, failureSubject) {
 		const reasons = (await Promise.all(roots.map(async (activation) => {
@@ -1911,6 +1948,25 @@ function sameLifecycle(meta, expected) {
 function assertListingNotCancelled(signal) {
 	if (signal?.aborted) throw new SubagentError("subagent listing was cancelled", "CANCELLED");
 }
+//#endregion
+//#region lib/types/projection.js
+/**
+* Pure session projections for subagent identity (mode/label) and active-turn
+* duration.
+*
+* @module @nomix-ai/nomix-subagent/projection
+*/
+const activeIntervalSchema = z.object({
+	since: z.number().int().nonnegative(),
+	through: z.number().int().nonnegative()
+}).strict();
+const projectionSchema = z.object({
+	settledMs: z.number().int().nonnegative(),
+	active: activeIntervalSchema.optional()
+}).strict().transform(({ settledMs, active }) => ({
+	settledMs,
+	...active === void 0 ? {} : { active }
+}));
 /**
 * Fold turn boundaries around the child's own durable descriptor.
 *
@@ -1921,12 +1977,11 @@ function assertListingNotCancelled(signal) {
 */
 const subagentTimingProjectionDefinition = {
 	key: "subagentTiming",
-	schema: z.object({
+	stateSchema: z.object({
 		settledMs: z.number().int().nonnegative(),
-		active: z.object({
-			since: z.number().int().nonnegative(),
-			through: z.number().int().nonnegative()
-		}).strict().optional()
+		active: activeIntervalSchema.optional(),
+		pendingTurnStart: z.number().int().nonnegative().optional(),
+		descriptorSeen: z.boolean()
 	}).strict(),
 	init: () => ({
 		descriptorSeen: false,
@@ -1976,13 +2031,16 @@ const subagentTimingProjectionDefinition = {
 			}
 		};
 	},
-	view: (state) => ({
-		settledMs: state.settledMs,
-		...state.active === void 0 ? {} : { active: state.active }
-	}),
+	wire: {
+		viewSchema: projectionSchema,
+		view: (state) => ({
+			settledMs: state.settledMs,
+			...state.active === void 0 ? {} : { active: state.active }
+		})
+	},
 	stateVersion: 2
 };
-const identitySchema = z.discriminatedUnion("mode", [z.object({
+const identityValueSchema = z.discriminatedUnion("mode", [z.object({
 	mode: z.literal("one-shot"),
 	label: z.string().optional(),
 	seq: z.number().int().nonnegative()
@@ -1990,7 +2048,9 @@ const identitySchema = z.discriminatedUnion("mode", [z.object({
 	mode: z.literal("continuable"),
 	label: z.string(),
 	seq: z.number().int().nonnegative()
-}).strict()]).nullable();
+}).strict()]);
+const identitySchema = identityValueSchema.nullable();
+const identityStateSchema = z.object({ identity: identityValueSchema.optional() }).strict();
 /** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
 function descriptorIdentity(event) {
 	let descriptor;
@@ -2023,14 +2083,17 @@ function descriptorIdentity(event) {
 */
 const subagentIdentityProjectionDefinition = {
 	key: "subagent",
-	schema: identitySchema,
+	stateSchema: identityStateSchema,
 	init: () => ({}),
 	apply: (state, event) => {
 		if (event.type !== "subagent/descriptor") return state;
 		const identity = descriptorIdentity(event);
 		return identity === void 0 ? {} : { identity };
 	},
-	view: (state) => state.identity ?? null,
+	wire: {
+		viewSchema: identitySchema,
+		view: (state) => state.identity ?? null
+	},
 	stateVersion: 2
 };
 //#endregion
@@ -2047,6 +2110,23 @@ const subagentIdentityProjectionDefinition = {
 *
 * @module @nomix-ai/nomix-subagent/out-of-process
 */
+/** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
+const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4096;
+const DIAGNOSTIC_TRUNCATION_SUFFIX = "\n[diagnostic truncated]";
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/**
+* Limit provider-authored failure detail without splitting a UTF-8 sequence.
+* @param diagnostic - safe diagnostic text produced by the provider.
+* @returns the original text, or a visibly truncated value within the limit.
+*/
+function limitSubagentDiagnostic(diagnostic) {
+	const bytes = utf8Encoder.encode(diagnostic);
+	if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES) return diagnostic;
+	let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
+	while ((bytes[prefixBytes] & 192) === 128) prefixBytes -= 1;
+	return utf8Decoder.decode(bytes.subarray(0, prefixBytes)) + DIAGNOSTIC_TRUNCATION_SUFFIX;
+}
 /**
 * The capability advertisement of an out-of-process backend: NONE. A child in
 * another process cannot honor parent-enforced start features
@@ -2160,8 +2240,11 @@ async function settleRunResult(parts) {
 		try {
 			parts.onError?.(toError(error), "error");
 		} catch {}
+		const collected = parts.collectDiagnostic?.();
+		const diagnostic = collected === void 0 ? void 0 : limitSubagentDiagnostic(collected);
 		return {
 			output: parts.collectOutput(),
+			...diagnostic === void 0 ? {} : { diagnostic },
 			stopReason: "error"
 		};
 	} finally {
@@ -2204,6 +2287,11 @@ function subprocessRunHandle(parts) {
 function finalText(blocks) {
 	return blocks.filter((block) => block.type === "text").map((block) => block.text).join("");
 }
+/** Render a failed stop reason with optional provider-authored detail. */
+function failureDetail(result) {
+	const stopReason = result.stopReason;
+	return result.diagnostic === void 0 ? stopReason : `${stopReason}; diagnostic: ${result.diagnostic}`;
+}
 /**
 * Map a child result to the task outcome: completed carries final text,
 * aborted is killed, and every other reason is failed without partial output.
@@ -2221,11 +2309,11 @@ function runOutcome(result) {
 		case "max-tokens":
 		case "refusal": return {
 			status: "failed",
-			detail: result.stopReason
+			detail: failureDetail(result)
 		};
 		default: return {
 			status: "failed",
-			detail: String(result.stopReason)
+			detail: failureDetail(result)
 		};
 	}
 }
@@ -2409,6 +2497,21 @@ var SubagentRuntime = class extends Service {
 		await manager.drainDescendants(parents);
 	}
 	/**
+	* Release selected resident continuable direct children of one exact live
+	* parent. Other children of the same parent remain admitted and resident.
+	* Absent targets and a manager-less composition are accepted no-ops.
+	* @param parent - exact live direct parent authorizing the selected release.
+	* @param childIds - durable direct-child ids to release when resident.
+	* @returns once every selected Activation released its `AgentHandle`.
+	* @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
+	*   different parent or the supplied parent identity is stale.
+	*/
+	async drainContinuableChildren(parent, childIds) {
+		const manager = this.continuations;
+		if (manager === void 0) return;
+		await manager.drainChildren(parent, childIds);
+	}
+	/**
 	* Enumerate the parent's direct session-backed subagents without loading or
 	* resuming an Agent and without any query service: the listing merges the live
 	* session store with optional session persistence (live-preferred) and

package/dist/kernel/subagent/lib/types/continuation.d.ts

@@ -68,7 +68,7 @@ declare module '@nomix-ai/nomix-llm' {
     }
 }
 /** Deployment scheduling policy for accepted child reports. */
-export type SubagentReportDelivery = 'quiet' | 'wakeup';
+export type SubagentReportDelivery = 'quiet' | 'next-step';
 /** Options for one continuable child's report to its direct parent. */
 export interface SubagentReportOptions {
     /** Already-resolved parent scheduling policy. */
@@ -82,6 +82,12 @@ export interface ContinuableStartSpec {
     readonly provider: string;
     /** The initial delegation's short `description`, persisted as the child's creation label. */
     readonly label: string;
+    /**
+     * Optional caller-reserved child identity. Omission preserves the manager's
+     * UUID allocation; supplying one lets a durable parent record provisioning
+     * before child materialization without a second identity handshake.
+     */
+    readonly childId?: SessionId;
     /**
      * The delegation request. The manager reserves the stable child id, resolves
      * the durable descriptor, and composes the child itself.
@@ -182,6 +188,8 @@ export declare class SubagentContinuationManager {
      * @returns the durable child id and the accepted initial prompt's message id.
      */
     startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;
+    /** Reject one child identity already owned by a live Agent or Session. */
+    private assertChildIdAvailable;
     /**
      * Deliver one later message to a known continuable child as its next FIFO
      * turn. Routing depends only on Activation residency: a `running` Activation
@@ -245,7 +253,7 @@ export declare class SubagentContinuationManager {
      * Perform one waking send to a parent, accounted against that parent's own
      * Activation when it has one. Registering the id before the send is what
      * keeps a continuation-managed parent from being judged quiescent in the
-     * window between `followup()` and the microtask that admits it.
+     * window between a waking send and the microtask that admits it.
      * @param parent - the exact live parent receiving the waking message.
      * @param message - the message whose id is accounted.
      * @param send - the synchronous waking send to perform.
@@ -273,6 +281,17 @@ export declare class SubagentContinuationManager {
      * @throws an aggregate error after all scoped branches settle when any failed.
      */
     drainDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * Release selected resident direct children of one exact live parent without
+     * closing admission for the parent's other continuable children. Owned
+     * descendants are released recursively through the same lifecycle.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     * @returns once every selected Activation released its handle.
+     * @throws {SubagentError} `UNAUTHORIZED` when a resident target is not the
+     *   parent's direct continuable child or the parent identity is stale.
+     */
+    drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
     /** Dispose independent roots and report every branch failure after all settle. */
     private disposeRoots;
     /** Return the retained member set for one exact scoped-teardown root. */

package/dist/kernel/subagent/lib/types/continuation.js

@@ -154,9 +154,10 @@ export class SubagentContinuationManager {
         const request = spec.request;
         const parent = request.parent;
         this.assertAdmitting(parent);
-        this.requirePersistence();
+        const persistence = this.requirePersistence();
         assertSubagentMaxDepth(request.maxDepth);
-        const childId = SessionId(randomUUID());
+        const childId = spec.childId ?? SessionId(randomUUID());
+        this.assertChildIdAvailable(childId);
         const childDepth = resolveChildDepth(parent, request.maxDepth);
         // Snapshot before any await: invalid descriptor JSON rejects the call
         // before a child exists, and the detached value is what reaches the log.
@@ -184,6 +185,18 @@ export class SubagentContinuationManager {
         const lineageSeedLength = prepared.seed?.length ?? 0;
         const seed = seedDescriptorTurn(childId, prepared.seed, descriptor);
         const messageId = await this.locks.run(childId, async () => {
+            spec.signal.throwIfAborted();
+            this.assertAdmitting(parent);
+            this.assertChildIdAvailable(childId);
+            if (spec.childId !== undefined) {
+                const persisted = await persistence.listSnapshots(spec.signal);
+                spec.signal.throwIfAborted();
+                this.assertAdmitting(parent);
+                this.assertChildIdAvailable(childId);
+                if (persisted.some(snapshot => snapshot.header.id === childId)) {
+                    throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD');
+                }
+            }
             const activation = await this.materialize({
                 childId,
                 provider: spec.provider,
@@ -197,6 +210,12 @@ export class SubagentContinuationManager {
         });
         return { childId, messageId };
     }
+    /** Reject one child identity already owned by a live Agent or Session. */
+    assertChildIdAvailable(childId) {
+        if (this.ctx.agents.get(childId) !== undefined || this.ctx.get('sessions')?.get(childId) !== undefined) {
+            throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD');
+        }
+    }
     /**
      * Deliver one later message to a known continuable child as its next FIFO
      * turn. Routing depends only on Activation residency: a `running` Activation
@@ -347,7 +366,7 @@ export class SubagentContinuationManager {
                 senderSessionId: activation.childId,
             },
         });
-        if (delivery === 'wakeup') {
+        if (delivery === 'next-step') {
             this.sendWaking(parent, message, () => { this.sendReport(parent, message, delivery); });
         }
         else {
@@ -359,7 +378,7 @@ export class SubagentContinuationManager {
      * Perform one waking send to a parent, accounted against that parent's own
      * Activation when it has one. Registering the id before the send is what
      * keeps a continuation-managed parent from being judged quiescent in the
-     * window between `followup()` and the microtask that admits it.
+     * window between a waking send and the microtask that admits it.
      * @param parent - the exact live parent receiving the waking message.
      * @param message - the message whose id is accounted.
      * @param send - the synchronous waking send to perform.
@@ -376,8 +395,8 @@ export class SubagentContinuationManager {
     /** Send one report while translating only the parent's own rejection. */
     sendReport(parent, message, delivery) {
         try {
-            if (delivery === 'wakeup')
-                parent.followup(message);
+            if (delivery === 'next-step')
+                parent.steer(message);
             else
                 parent.inject(message);
         }
@@ -471,6 +490,38 @@ export class SubagentContinuationManager {
         await Promise.all(materializations.map(materialization => materialization.settled));
         await this.disposeRoots(targetRoots, 'scoped activation(s)');
     }
+    /**
+     * Release selected resident direct children of one exact live parent without
+     * closing admission for the parent's other continuable children. Owned
+     * descendants are released recursively through the same lifecycle.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     * @returns once every selected Activation released its handle.
+     * @throws {SubagentError} `UNAUTHORIZED` when a resident target is not the
+     *   parent's direct continuable child or the parent identity is stale.
+     */
+    async drainChildren(parent, childIds) {
+        if (this.ctx.agents.get(parent.id) !== parent) {
+            throw new SubagentError('selected child teardown requires the exact live parent agent', 'UNAUTHORIZED');
+        }
+        const targets = [];
+        for (const childId of new Set(childIds)) {
+            const activation = this.activations.get(childId);
+            if (activation === undefined)
+                continue;
+            if (activation.parentSession !== parent.id || !activation.ancestry.has(parent)) {
+                throw new SubagentError(`subagent "${childId}" is not a direct child of agent "${parent.id}"`, 'UNAUTHORIZED');
+            }
+            targets.push(activation);
+        }
+        // Open every transaction before the first await so cancellation propagates
+        // across the selected roots in one synchronous span.
+        for (const activation of targets) {
+            const disposal = this.dispose(activation);
+            void disposal.catch(() => undefined);
+        }
+        await this.disposeRoots(targets, 'selected activation(s)');
+    }
     /** Dispose independent roots and report every branch failure after all settle. */
     async disposeRoots(roots, failureSubject) {
         const failures = await Promise.all(roots.map(async (activation) => {
@@ -814,7 +865,7 @@ export class SubagentContinuationManager {
      * @returns the accepted message id.
      */
     admitWaking(activation, messageId, send) {
-        // `Agent.followup()` publishes inbox events synchronously, so observers must
+        // Waking Agent sends publish inbox events synchronously, so observers must
         // see this Activation as busy before the call begins.
         activation.accepted.add(messageId);
         try {

package/dist/kernel/subagent/lib/types/index.d.ts

@@ -182,6 +182,17 @@ export declare class SubagentRuntime extends Service {
      * @throws an aggregate error after all branches settle when any failed.
      */
     drainContinuableDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * Release selected resident continuable direct children of one exact live
+     * parent. Other children of the same parent remain admitted and resident.
+     * Absent targets and a manager-less composition are accepted no-ops.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     * @returns once every selected Activation released its `AgentHandle`.
+     * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
+     *   different parent or the supplied parent identity is stale.
+     */
+    drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
     /**
      * Enumerate the parent's direct session-backed subagents without loading or
      * resuming an Agent and without any query service: the listing merges the live

package/dist/kernel/subagent/lib/types/index.js

@@ -173,6 +173,22 @@ export class SubagentRuntime extends Service {
             return;
         await manager.drainDescendants(parents);
     }
+    /**
+     * Release selected resident continuable direct children of one exact live
+     * parent. Other children of the same parent remain admitted and resident.
+     * Absent targets and a manager-less composition are accepted no-ops.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     * @returns once every selected Activation released its `AgentHandle`.
+     * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
+     *   different parent or the supplied parent identity is stale.
+     */
+    async drainContinuableChildren(parent, childIds) {
+        const manager = this.continuations;
+        if (manager === undefined)
+            return;
+        await manager.drainChildren(parent, childIds);
+    }
     /**
      * Enumerate the parent's direct session-backed subagents without loading or
      * resuming an Agent and without any query service: the listing merges the live

package/dist/kernel/subagent/lib/types/out-of-process.d.ts

@@ -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. */

package/dist/kernel/subagent/lib/types/out-of-process.js

@@ -12,6 +12,28 @@
  */
 import { accessSync, constants, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
+/** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
+const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096;
+const DIAGNOSTIC_TRUNCATION_SUFFIX = '\n[diagnostic truncated]';
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/**
+ * Limit provider-authored failure detail without splitting a UTF-8 sequence.
+ * @param diagnostic - safe diagnostic text produced by the provider.
+ * @returns the original text, or a visibly truncated value within the limit.
+ */
+function limitSubagentDiagnostic(diagnostic) {
+    const bytes = utf8Encoder.encode(diagnostic);
+    if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES)
+        return diagnostic;
+    const suffixBytes = utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
+    let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - suffixBytes;
+    while ((bytes[prefixBytes] & 0b1100_0000) === 0b1000_0000) {
+        prefixBytes -= 1;
+    }
+    return utf8Decoder.decode(bytes.subarray(0, prefixBytes))
+        + DIAGNOSTIC_TRUNCATION_SUFFIX;
+}
 /**
  * The capability advertisement of an out-of-process backend: NONE. A child in
  * another process cannot honor parent-enforced start features
@@ -148,7 +170,15 @@ export async function settleRunResult(parts) {
         catch {
             // The diagnostic sink cannot reject the run result.
         }
-        return { output: parts.collectOutput(), stopReason: 'error' };
+        const collected = parts.collectDiagnostic?.();
+        const diagnostic = collected === undefined
+            ? undefined
+            : limitSubagentDiagnostic(collected);
+        return {
+            output: parts.collectOutput(),
+            ...diagnostic === undefined ? {} : { diagnostic },
+            stopReason: 'error',
+        };
     }
     finally {
         parts.signal.removeEventListener('abort', parts.onAbort);

package/dist/kernel/subagent/lib/types/projection.d.ts

@@ -4,21 +4,29 @@
  *
  * @module @nomix-ai/nomix-subagent/projection
  */
-import type { ProjectionDefinition } from '../../../session-projection/lib/index.js';
-import type { SubagentIdentityProjection } from './projection-types.ts';
-interface TimingState {
+import { z } from 'zod';
+import type { SessionEvent } from '../../../session/lib/index.js';
+import type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
+/** Fold state for a subagent's latest timing snapshot. */
+export interface TimingState {
     /** Milliseconds accumulated across completed post-descriptor turns. */
     settledMs: number;
     /** Current open interval kept paired inside the fold. */
     active?: {
         since: number;
         through: number;
-    };
+    } | undefined;
     /** Latest pre-descriptor turn start, promoted when the child's own descriptor arrives. */
-    pendingTurnStart?: number;
+    pendingTurnStart?: number | undefined;
     /** Whether the fold has crossed a descriptor in this logical log. */
     descriptorSeen: boolean;
 }
+declare module '@nomix-ai/nomix-session-projection/types' {
+    interface SessionProjectionStateMap {
+        subagentTiming: TimingState;
+        subagent: IdentityState;
+    }
+}
 /**
  * Fold turn boundaries around the child's own durable descriptor.
  *
@@ -27,10 +35,39 @@ interface TimingState {
  * admits only a child with exactly one descriptor in its own suffix, making
  * the final reset the child's authoritative timing origin.
  */
-export declare const subagentTimingProjectionDefinition: ProjectionDefinition<'subagentTiming', TimingState>;
+export declare const subagentTimingProjectionDefinition: {
+    key: "subagentTiming";
+    stateSchema: z.ZodType<TimingState, unknown, z.core.$ZodTypeInternals<TimingState, unknown>>;
+    init: () => {
+        descriptorSeen: false;
+        settledMs: number;
+    };
+    apply: (state: NoInfer<TimingState>, event: SessionEvent) => {
+        /** Milliseconds accumulated across completed post-descriptor turns. */
+        settledMs: number;
+        /** Current open interval kept paired inside the fold. */
+        active?: {
+            since: number;
+            through: number;
+        } | undefined;
+        /** Whether the fold has crossed a descriptor in this logical log. */
+        descriptorSeen: boolean;
+    };
+    wire: {
+        viewSchema: z.ZodType<SubagentTimingProjection, unknown, z.core.$ZodTypeInternals<SubagentTimingProjection, unknown>>;
+        view: (state: NoInfer<TimingState>) => {
+            active?: {
+                since: number;
+                through: number;
+            };
+            settledMs: number;
+        };
+    };
+    stateVersion: number;
+};
 interface IdentityState {
     /** Identity from the last valid descriptor; absent before one, and after an invalid one. */
-    identity?: SubagentIdentityProjection;
+    identity?: SubagentIdentityProjection | undefined;
 }
 /**
  * Fold the durable mode/label identity from `subagent/descriptor` events,
@@ -43,6 +80,16 @@ interface IdentityState {
  * holding the earlier identity replaces it instead of keeping it stale;
  * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
  */
-export declare const subagentIdentityProjectionDefinition: ProjectionDefinition<'subagent', IdentityState>;
+export declare const subagentIdentityProjectionDefinition: {
+    key: "subagent";
+    stateSchema: z.ZodType<IdentityState, unknown, z.core.$ZodTypeInternals<IdentityState, unknown>>;
+    init: () => {};
+    apply: (state: NoInfer<IdentityState>, event: SessionEvent) => IdentityState;
+    wire: {
+        viewSchema: z.ZodNullable<z.ZodType<SubagentIdentityProjection, unknown, z.core.$ZodTypeInternals<SubagentIdentityProjection, unknown>>>;
+        view: (state: NoInfer<IdentityState>) => SubagentIdentityProjection | null;
+    };
+    stateVersion: number;
+};
 export {};
 //# sourceMappingURL=projection.d.ts.map