@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/storage-json/lib/types/invariant.d.ts

@@ -2,7 +2,7 @@
  * Package-owned invariant companion for `@nomix-ai/nomix-storage-json`.
  * @module @nomix-ai/nomix-storage-json/invariant
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "storage-json-invariant";
 /** Service required before the companion can reserve package ownership. */

package/dist/kernel/storage-json/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomix-ai/nomix-storage-json",
   "description": "JSON file KV storage backend for the Nomix Harness storage hub",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },

package/dist/kernel/storage-sqlite/lib/index.js

@@ -1,4 +1,4 @@
-import z from "@nomix-ai/schemastery";
+import z from "../../schemastery/lib/index.mjs";
 import { StorageError, UNIT_NAME_RE, storageBackendServiceKey } from "../../storage/lib/index.js";
 import { DatabaseSync } from "node:sqlite";
 import { mkdir, open } from "node:fs/promises";

package/dist/kernel/storage-sqlite/lib/types/index.d.ts

@@ -4,8 +4,8 @@
  * as backend `sqlite`; the disposer unregisters first, then closes the medium.
  * @module @nomix-ai/nomix-storage-sqlite
  */
-import type { Context } from '@nomix-ai/cordis';
-import z from '@nomix-ai/schemastery';
+import type { Context } from '../../../cordis/lib/index.js';
+import z from '../../../schemastery/lib/index.mjs';
 import type { KvFacet, StorageBackend } from '../../../storage/lib/index.js';
 import { type JournalMode } from './schema.ts';
 export { STORAGE_SQLITE_SCHEMA_VERSION, type JournalMode } from './schema.ts';

package/dist/kernel/storage-sqlite/lib/types/index.js

@@ -4,7 +4,7 @@
  * as backend `sqlite`; the disposer unregisters first, then closes the medium.
  * @module @nomix-ai/nomix-storage-sqlite
  */
-import z from '@nomix-ai/schemastery';
+import z from '../../../schemastery/lib/index.mjs';
 import { StorageError, UNIT_NAME_RE, storageBackendServiceKey } from '../../../storage/lib/index.js';
 import { openDatabase, recordTableName } from "./schema.js";
 import { SqliteKvUnit } from "./unit.js";

package/dist/kernel/storage-sqlite/lib/types/invariant.d.ts

@@ -2,7 +2,7 @@
  * Package-owned invariant companion for `@nomix-ai/nomix-storage-sqlite`.
  * @module @nomix-ai/nomix-storage-sqlite/invariant
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "storage-sqlite-invariant";
 /** Service required before the companion can reserve package ownership. */

package/dist/kernel/storage-sqlite/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomix-ai/nomix-storage-sqlite",
   "description": "SQLite storage backend (kv facet) for the Nomix Harness storage hub",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },

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

@@ -1,4 +1,4 @@
-import { Service } from "@nomix-ai/cordis";
+import { Service } from "../../cordis/lib/index.js";
 import { scopeTarget } from "../../scope/lib/index.js";
 import { assertObjectJsonSchema } from "../../tools/lib/index.js";
 import { HarnessError, boundContextSummary, createUserMessage, errorChain } from "../../llm/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/activation-setup-registry.d.ts

@@ -10,7 +10,7 @@
  *
  * @module @nomix-ai/nomix-subagent/activation-setup-registry
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 import type { AgentSetupCommit } from '../../../agent/lib/index.js';
 /**
  * One deployment capability installed into a continuable child's unpublished

package/dist/kernel/subagent/lib/types/child-agent.d.ts

@@ -7,7 +7,7 @@
  *
  * @module @nomix-ai/nomix-subagent/child-agent
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 import type { Agent, AgentOptions, CreateAgentOptions } from '../../../agent/lib/index.js';
 import type { SandboxMode } from '../../../sandbox/lib/index.js';
 import type { Session, SessionId } from '../../../session/lib/index.js';

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

@@ -20,7 +20,7 @@
  *
  * @module @nomix-ai/nomix-subagent
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 import type { Agent } from '../../../agent/lib/index.js';
 import type { ContentBlock, MessageId, MessageSource } from '../../../llm/lib/index.js';
 import { SessionId } from '../../../session/lib/index.js';
@@ -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

@@ -30,7 +30,7 @@
  *
  * @module @nomix-ai/nomix-subagent
  */
-import { Context, Service } from '@nomix-ai/cordis';
+import { Context, Service } from '../../../cordis/lib/index.js';
 import type { Scoped } from '../../../scope/lib/index.js';
 import type { ContentBlock, MessageId } from '../../../llm/lib/index.js';
 import type { Agent } from '../../../agent/lib/index.js';
@@ -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

@@ -30,7 +30,7 @@
  *
  * @module @nomix-ai/nomix-subagent
  */
-import { Service } from '@nomix-ai/cordis';
+import { Service } from '../../../cordis/lib/index.js';
 import { scopeTarget } from '../../../scope/lib/index.js';
 import { assertObjectJsonSchema } from '../../../tools/lib/index.js';
 import { SubagentError } from "./error.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/invariant.d.ts

@@ -1,5 +1,5 @@
 /** Package-owned subagent registry and lifecycle invariants. @module @nomix-ai/nomix-subagent/invariant */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "subagent-invariant";
 /** Service required before the companion can reserve package ownership. */

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

@@ -13,7 +13,7 @@
  *
  * @module @nomix-ai/nomix-subagent/lifecycle
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 import type { Agent } from '../../../agent/lib/index.js';
 import type { ContentBlock } from '../../../llm/lib/index.js';
 import type { SessionId } from '../../../session/lib/index.js';

package/dist/kernel/subagent/lib/types/list-children.d.ts

@@ -15,7 +15,7 @@
  *
  * @module @nomix-ai/nomix-subagent
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 import type { SessionId } from '../../../session/lib/index.js';
 /**
  * One entry of a {@link listChildren} result, ordered by header `createdAt`

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