@deepseek-ai/dsh-subagent 0.0.1-rc.1

package/lib/types/list-children.js

@@ -0,0 +1,316 @@
+/**
+ * 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
+ * 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
+ * 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,
+ * Agent-registry, continuation-manager, or provider state.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+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.
+ */
+const COLD_READ_CONCURRENCY = 4;
+/**
+ * Enumerate one parent's origin-classified direct children from the
+ * 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.
+ * @see SubagentService.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.
+ * @param parentSessionId - parent session whose direct children are listed.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
+ */
+export async function listChildren(ctx, parentSessionId, signal) {
+    const listing = await prepareListing(ctx, signal);
+    const candidates = [...listing.corpus.values()]
+        .filter(record => record.header.parentSession === parentSessionId
+        && record.header.origin === 'subagent')
+        .sort(compareCorpusRecords);
+    const rows = await resolveCandidateRows(candidates, listing, signal);
+    return rows.filter((row) => row !== undefined);
+}
+/**
+ * Enumerate every session-backed subagent below one root in stable pre-order.
+ * Ordinary sessions and one-shot children remain traversal nodes, so a
+ * continuable child below either is still discovered. Classification uses the
+ * same projection-backed runtime as {@link listChildren}; no Agent is loaded or
+ * resumed.
+ * @see SubagentService.listDescendants for the public cancellation and failure contract.
+ * @param ctx - context carrying the session store, projection registry, and optional persistence/cache.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns interpreted subagents with durable direct-parent and root-relative depth.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+export async function listDescendants(ctx, rootSessionId, signal) {
+    const listing = await prepareListing(ctx, signal);
+    const positioned = descendantCandidates(listing.corpus, rootSessionId);
+    const rows = await resolveCandidateRows(positioned.map(candidate => candidate.record), listing, signal);
+    const entries = [];
+    positioned.forEach((position, index) => {
+        const row = rows[index];
+        if (row !== undefined) {
+            entries.push({ ...row, parentId: position.parentId, depth: position.depth });
+        }
+    });
+    return entries;
+}
+/** Resolve listing services once and build one live-preferred session corpus. */
+async function prepareListing(ctx, signal) {
+    const projections = ctx.get('sessionProjections');
+    // Checked before any read, even with zero candidates: mode/label are the
+    // row's strong contract, so a missing fold capability is a deterministic
+    // deployment configuration error, never an empty success.
+    if (projections === undefined) {
+        throw new SubagentError('listing subagents requires the sessionProjections registry (load @deepseek-ai/dsh-session-projection)', 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE');
+    }
+    // Strict global read, never the `ctx.sessions` property proxy: the proxy is
+    // caller-scope bound, so a consumer plugin without its own `sessions`
+    // injection (the model-facing tool, the API proxy) would throw on access.
+    const sessions = ctx.get('sessions');
+    if (sessions === undefined) {
+        throw new SubagentError('listing subagents requires the session store (load @deepseek-ai/dsh-session)', 'SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE');
+    }
+    assertListingNotCancelled(signal);
+    const persistence = ctx.get('sessionPersistence');
+    // 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;
+        }
+        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 });
+    }
+    const subagentParents = new Set();
+    for (const record of corpus.values()) {
+        if (record.header.origin === 'subagent' && record.header.parentSession !== undefined) {
+            subagentParents.add(record.header.parentSession);
+        }
+    }
+    return { projections, persistence, 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 rows = Array.from({ length: candidates.length });
+    const coldReads = [];
+    candidates.forEach((candidate, index) => {
+        const childId = candidate.header.id;
+        if (candidate.live === undefined) {
+            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.
+        let identity;
+        try {
+            identity = projections.snapshot(candidate.live).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.
+            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)
+            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) {
+        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);
+            }
+        }));
+    }
+    assertListingNotCancelled(signal);
+    return rows;
+}
+/** Build origin-classified candidates from the complete tree without recursion. */
+function descendantCandidates(corpus, rootSessionId) {
+    const children = new Map();
+    for (const record of corpus.values()) {
+        const parentId = record.header.parentSession;
+        if (parentId === undefined)
+            continue;
+        const siblings = children.get(parentId);
+        if (siblings === undefined)
+            children.set(parentId, [record]);
+        else
+            siblings.push(record);
+    }
+    for (const siblings of children.values())
+        siblings.sort(compareCorpusRecords);
+    const positioned = [];
+    const stack = (children.get(rootSessionId) ?? [])
+        .map(record => ({ record, parentId: rootSessionId, depth: 1 }))
+        .reverse();
+    const visited = new Set([rootSessionId]);
+    while (stack.length > 0) {
+        // The length guard proves one frame exists.
+        // oxlint-disable-next-line typescript/no-non-null-assertion
+        const position = stack.pop();
+        const id = position.record.header.id;
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        if (position.record.header.origin === 'subagent')
+            positioned.push(position);
+        const descendants = children.get(id) ?? [];
+        for (const record of [...descendants].reverse()) {
+            stack.push({ record, parentId: id, depth: position.depth + 1 });
+        }
+    }
+    return positioned;
+}
+/** Compare siblings by durable creation time, then id. */
+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
+ * 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;
+        }
+        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;
+        }
+        // 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);
+        }
+    }
+    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.
+        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;
+    }
+    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' };
+    }
+    if (identity === undefined || identity === null) {
+        return { kind: 'diagnostic', id: childId, reason: 'corrupt' };
+    }
+    return childRow(childId, identity, 'inactive', hasChildren);
+}
+/** Materialize one served identity as its child row. */
+function childRow(id, identity, activity, hasChildren) {
+    return identity.mode === 'one-shot'
+        ? {
+            kind: 'child',
+            id,
+            mode: 'one-shot',
+            ...identity.label !== undefined ? { label: identity.label } : {},
+            activity,
+            hasChildren,
+        }
+        : {
+            kind: 'child',
+            id,
+            mode: 'continuable',
+            label: identity.label,
+            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',
+];
+/** Whether an inspected log still belongs to the enumerated lifecycle. */
+function sameLifecycle(meta, expected) {
+    return LIFECYCLE_WITNESS_KEYS.every(key => meta[key] === expected[key]);
+}
+/** Stop a listing at its next cancellation checkpoint. */
+function assertListingNotCancelled(signal) {
+    if (signal?.aborted) {
+        throw new SubagentError('subagent listing was cancelled', 'CANCELLED');
+    }
+}
+//# sourceMappingURL=list-children.js.map

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

@@ -0,0 +1,115 @@
+/**
+ * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
+ * that enforce this seam's own contracts around a child in another process:
+ * the no-capabilities advertisement, timing-bound validation, child
+ * working-directory resolution (config override, else the delegating parent
+ * session's workspace), the never-reject result settlement, and the standard
+ * run-handle publication. Backends compose these with their own wire drivers;
+ * the process machinery itself (spawn, env scrub, tree-scoped teardown)
+ * belongs to the `dsh-subprocess` seam.
+ *
+ * @module @deepseek-ai/dsh-subagent/out-of-process
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SubagentCapabilities, SubagentResult, SubagentRun, SubagentStopReason } from './types.ts';
+/**
+ * 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
+ * request needing any of them before `start` runs — never accepted-then-ignored.
+ */
+export declare const NO_START_CAPABILITIES: SubagentCapabilities;
+/**
+ * Assert a configured timing bound is a positive finite number (it bounds a
+ * teardown or shutdown wait; zero, negative, or NaN would skip or wedge it).
+ * @param prefix - the consuming plugin's diagnostic prefix (e.g. `subagent-acp`).
+ * @param name - the config field name, for the diagnostic.
+ * @param value - the configured value.
+ */
+export declare function assertPositiveFinite(prefix: string, name: string, value: number): void;
+/**
+ * Assert `cwd` can actually host the child: absolute (it doubles as the
+ * child's workspace identity, and a relative path would be re-anchored to the
+ * server process's launch directory) and an existing directory (fail here,
+ * before the process boundary, instead of as an ambiguous spawn ENOENT).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param label - which source supplied the value, for the diagnostic.
+ * @param cwd - the candidate working directory.
+ * @returns `cwd`, validated.
+ */
+export declare function assertUsableCwd(prefix: string, label: string, cwd: string): string;
+/**
+ * Validate a configured `cwd` override ONCE, at plugin load: reject the empty
+ * string (`path.resolve('')` is the process cwd — it would silently
+ * reintroduce the launch-directory fallback this resolution removes),
+ * interpret a relative path against the harness launch directory, and require
+ * an enterable directory.
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param cwd - the configured override, or `undefined` when the config omits it.
+ * @returns the validated absolute override, or `undefined` when omitted.
+ */
+export declare function validateConfiguredCwd(prefix: string, cwd: string | undefined): string | undefined;
+/**
+ * Resolve the child's working directory at start: the deployment override
+ * when configured (already validated at load), else the parent session's
+ * workspace cwd (validated here, its earliest resolvable point). Fails loud
+ * when neither exists — falling back to the harness process cwd would
+ * silently bind the child to the server's launch directory instead of the
+ * delegating session's workspace (one server process serves many sessions,
+ * each with its own cwd).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param configured - the load-validated override, or `undefined`.
+ * @param parentCwd - the delegating parent session's workspace cwd, if any.
+ * @returns the absolute child working directory.
+ */
+export declare function resolveChildCwd(prefix: string, configured: string | undefined, parentCwd: string | undefined): string;
+/** Inputs to {@link settleRunResult}. */
+export interface RunResultSettlement {
+    /** The turn attempt (typically racing local cancellation); returns the terminal result. */
+    attempt: () => Promise<SubagentResult>;
+    /** Snapshot the provider exposes when cancellation or failure wins settlement. */
+    collectOutput: () => ContentBlock[];
+    /** 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. */
+    onError?: ((error: Error, stopReason: SubagentStopReason) => void) | undefined;
+    /** The request's cancellation signal (the listener is removed at settlement). */
+    signal: AbortSignal;
+    /** The abort listener registered on {@link signal} at start. */
+    onAbort: () => void;
+}
+/**
+ * Settle an out-of-process run result under the seam contract: `result` never
+ * 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.
+ * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
+ * @returns the terminal result (never a rejection).
+ */
+export declare function settleRunResult(parts: RunResultSettlement): Promise<SubagentResult>;
+/** Inputs to {@link subprocessRunHandle}. */
+export interface SubprocessRunHandleParts {
+    /** The parent-scoped run id. */
+    id: SubagentRun['id'];
+    /** The flattened, never-rejecting result (the seam contract). */
+    result: Promise<SubagentResult>;
+    /** The request's cancellation signal (the listener is removed on dispose). */
+    signal: AbortSignal;
+    /** The abort listener registered on {@link signal} at start. */
+    onAbort: () => void;
+    /** Settle local cancellation so {@link result} resolves without the child. */
+    requestCancel: () => void;
+    /** Tear the child process down to quiescence (backend-owned ladder). */
+    teardown: () => Promise<void>;
+}
+/**
+ * Publish the seam run handle for an out-of-process child. `dispose()` is
+ * idempotent (one memoized teardown): it removes the abort listener, settles
+ * local cancellation — there is no assumption the child cooperates — and then
+ * awaits the backend's teardown to actual exit.
+ * @param parts - the run identity, result, cancellation wiring, and teardown.
+ * @returns the seam run handle (`localAgent` is `undefined` for remote runs).
+ */
+export declare function subprocessRunHandle(parts: SubprocessRunHandleParts): SubagentRun;
+//# sourceMappingURL=out-of-process.d.ts.map

package/lib/types/out-of-process.js

@@ -0,0 +1,181 @@
+/**
+ * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
+ * that enforce this seam's own contracts around a child in another process:
+ * the no-capabilities advertisement, timing-bound validation, child
+ * working-directory resolution (config override, else the delegating parent
+ * session's workspace), the never-reject result settlement, and the standard
+ * run-handle publication. Backends compose these with their own wire drivers;
+ * the process machinery itself (spawn, env scrub, tree-scoped teardown)
+ * belongs to the `dsh-subprocess` seam.
+ *
+ * @module @deepseek-ai/dsh-subagent/out-of-process
+ */
+import { accessSync, constants, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * 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
+ * request needing any of them before `start` runs — never accepted-then-ignored.
+ */
+export const NO_START_CAPABILITIES = Object.freeze({
+    outputSchema: false,
+    depthLimit: false,
+    toolFilter: false,
+    persona: false,
+});
+/**
+ * Assert a configured timing bound is a positive finite number (it bounds a
+ * teardown or shutdown wait; zero, negative, or NaN would skip or wedge it).
+ * @param prefix - the consuming plugin's diagnostic prefix (e.g. `subagent-acp`).
+ * @param name - the config field name, for the diagnostic.
+ * @param value - the configured value.
+ */
+export function assertPositiveFinite(prefix, name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${prefix}: ${name} must be a positive finite number`);
+    }
+}
+/**
+ * Whether `path` names an existing directory the harness can ENTER. The
+ * search-permission probe matters: `statSync().isDirectory()` is true for a
+ * mode-600 directory, but a subprocess cwd needs `X_OK` or spawn fails EACCES.
+ */
+function isEnterableDirectory(path) {
+    try {
+        if (!statSync(path).isDirectory())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        // statSync/accessSync throw only filesystem access errors here
+        // (ENOENT/EACCES/ENOTDIR/…), and every one of them means the path cannot
+        // serve as the child's cwd.
+        return false;
+    }
+}
+/**
+ * Assert `cwd` can actually host the child: absolute (it doubles as the
+ * child's workspace identity, and a relative path would be re-anchored to the
+ * server process's launch directory) and an existing directory (fail here,
+ * before the process boundary, instead of as an ambiguous spawn ENOENT).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param label - which source supplied the value, for the diagnostic.
+ * @param cwd - the candidate working directory.
+ * @returns `cwd`, validated.
+ */
+export function assertUsableCwd(prefix, label, cwd) {
+    if (!isAbsolute(cwd)) {
+        throw new Error(`${prefix}: ${label} must be an absolute path: ${cwd}`);
+    }
+    if (!isEnterableDirectory(cwd)) {
+        throw new Error(`${prefix}: ${label} is not an accessible directory: ${cwd}`);
+    }
+    return cwd;
+}
+/**
+ * Validate a configured `cwd` override ONCE, at plugin load: reject the empty
+ * string (`path.resolve('')` is the process cwd — it would silently
+ * reintroduce the launch-directory fallback this resolution removes),
+ * interpret a relative path against the harness launch directory, and require
+ * an enterable directory.
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param cwd - the configured override, or `undefined` when the config omits it.
+ * @returns the validated absolute override, or `undefined` when omitted.
+ */
+export function validateConfiguredCwd(prefix, cwd) {
+    if (cwd === undefined)
+        return undefined;
+    if (cwd === '') {
+        throw new Error(`${prefix}: config cwd must not be empty — omit the key to inherit the parent session cwd`);
+    }
+    return assertUsableCwd(prefix, 'config cwd', resolve(cwd));
+}
+/**
+ * Resolve the child's working directory at start: the deployment override
+ * when configured (already validated at load), else the parent session's
+ * workspace cwd (validated here, its earliest resolvable point). Fails loud
+ * when neither exists — falling back to the harness process cwd would
+ * silently bind the child to the server's launch directory instead of the
+ * delegating session's workspace (one server process serves many sessions,
+ * each with its own cwd).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param configured - the load-validated override, or `undefined`.
+ * @param parentCwd - the delegating parent session's workspace cwd, if any.
+ * @returns the absolute child working directory.
+ */
+export function resolveChildCwd(prefix, configured, parentCwd) {
+    if (configured !== undefined)
+        return configured;
+    if (parentCwd === undefined) {
+        throw new Error(`${prefix}: no working directory for the child — configure \`cwd\` or delegate from a parent session that has one`);
+    }
+    return assertUsableCwd(prefix, 'parent session cwd', parentCwd);
+}
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value) {
+    // The rejecting surfaces (wire clients, spawn failures) only throw
+    // `Error`s; the `String(value)` arm is a defensive fallback for a non-Error
+    // throw the typed surfaces cannot produce.
+    /* v8 ignore next */
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Settle an out-of-process run result under the seam contract: `result` never
+ * 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.
+ * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
+ * @returns the terminal result (never a rejection).
+ */
+export async function settleRunResult(parts) {
+    try {
+        const result = await parts.attempt();
+        return parts.cancelled()
+            ? { output: parts.collectOutput(), stopReason: 'aborted' }
+            : result;
+    }
+    catch (error) {
+        // Cover a rejection already queued when cancellation arrives.
+        if (parts.cancelled())
+            return { output: parts.collectOutput(), stopReason: 'aborted' };
+        // Flatten post-publication transport failures while preserving diagnostics.
+        try {
+            parts.onError?.(toError(error), 'error');
+        }
+        catch {
+            // The diagnostic sink cannot reject the run result.
+        }
+        return { output: parts.collectOutput(), stopReason: 'error' };
+    }
+    finally {
+        parts.signal.removeEventListener('abort', parts.onAbort);
+    }
+}
+/**
+ * Publish the seam run handle for an out-of-process child. `dispose()` is
+ * idempotent (one memoized teardown): it removes the abort listener, settles
+ * local cancellation — there is no assumption the child cooperates — and then
+ * awaits the backend's teardown to actual exit.
+ * @param parts - the run identity, result, cancellation wiring, and teardown.
+ * @returns the seam run handle (`localAgent` is `undefined` for remote runs).
+ */
+export function subprocessRunHandle(parts) {
+    let disposal;
+    return {
+        id: parts.id,
+        localAgent: undefined,
+        result: parts.result,
+        dispose() {
+            if (disposal !== undefined)
+                return disposal;
+            parts.signal.removeEventListener('abort', parts.onAbort);
+            parts.requestCancel();
+            disposal = parts.teardown();
+            return disposal;
+        },
+    };
+}
+//# sourceMappingURL=out-of-process.js.map

package/lib/types/projection-types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure client-safe subagent projection vocabulary.
+ *
+ * @module @deepseek-ai/dsh-subagent/projection-types
+ */
+/** Durable active-turn timing for one descriptor-backed child session. */
+export interface SubagentTimingProjection {
+    /** Milliseconds accumulated across completed turns after the child's own descriptor. */
+    settledMs: number;
+    /** Same-cut bounds of the currently open turn, when one has not reached `turn/end`. */
+    active?: {
+        /** Start of the open turn. */
+        since: number;
+        /** Latest event time folded into this projection cut. */
+        through: number;
+    };
+}
+/**
+ * Durable identity of one descriptor-backed subagent session: lifecycle mode
+ * plus creation label, folded last-wins from `subagent/descriptor` events.
+ * Label strength follows the descriptor schema: a continuable child always
+ * carries one, a one-shot child may omit it.
+ */
+export type SubagentIdentityProjection = {
+    /** A terminal one-shot child. */
+    mode: 'one-shot';
+    /** Optional durable creation label from the child's descriptor. */
+    label?: string;
+    /**
+     * Seq of the `subagent/descriptor` event this identity was folded from.
+     * `seq >= header.seedLength` proves the identity comes from the child's
+     * OWN log suffix — where a descriptor is immutable once appended — and
+     * not from a fork seed's replayed ancestor descriptor.
+     */
+    seq: number;
+} | {
+    /** A resumable conversation. */
+    mode: 'continuable';
+    /** Durable creation label from the child's descriptor. */
+    label: string;
+    /** Seq of the folded descriptor event; see the one-shot arm for the own-suffix proof. */
+    seq: number;
+};
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Active-turn duration for a descriptor-backed subagent session. */
+        subagentTiming: SubagentTimingProjection;
+        /**
+         * Identity of a descriptor-backed subagent session. `null` ⟺ no valid
+         * descriptor (missing, malformed, or unrecognized-version — deliberately
+         * undistinguished). The sentinel is deliberately serializable: a
+         * value pushed over JSON transports must survive `JSON.stringify`
+         * losslessly, where an `undefined` field would be dropped and a stale
+         * identity would survive on the receiving side. The entry itself stays
+         * non-optional.
+         */
+        subagent: SubagentIdentityProjection | null;
+    }
+}
+//# sourceMappingURL=projection-types.d.ts.map