@mstar-harness/dsh 3.8.0 → 3.8.2

package/dist/gates/agent-flow.d.ts

@@ -1,6 +1,7 @@
 import { type Context } from '@deepseek-ai/cordis';
 import type { AgentFlowView } from '../types.ts';
 import type { Config } from './_shared.ts';
+import type { ActiveWorkflowSelection, SessionHint } from './workflow-selection.ts';
 /** The agent-flow ledger file name under `{HARNESS_DIR}`. */
 export declare const AGENT_FLOW_FILE = "agent-flow.jsonl";
 /** Truncation bound: the ledger keeps only the most recent events. */
@@ -26,8 +27,11 @@ export declare const AGENT_FLOW_SIZE_GATE_BYTES: number;
  * unbounded. ID-sized fields (`runId`, `childId`) SKIP the row when
  * oversized — truncating them could forge collisions; display fields
  * (`name`, `label`, `phase`) are truncated deterministically with a suffix
- * marker. `2^31` bounds every sequence number (envelope + member) — the
- * cursor-math safe range (see the consumer's durable watermark).
+ * marker. The settle identity fields are OPTIONAL: an invalid or oversized
+ * `childId` / `taskRef` omits only the FIELD — the real completion still
+ * records (see {@link optionalLedgerId}). `2^31` bounds every sequence number
+ * (envelope + member) — the cursor-math safe range (see the consumer's
+ * durable watermark).
  */
 export declare const WORKFLOW_LEDGER_MAX_ID_LENGTH = 512;
 /** Cap for label-sized display fields (`label`, `phase`). */
@@ -54,6 +58,20 @@ export declare const WORKFLOW_LEDGER_MAX_SEQ: number;
  * most one code point of slack. Pure — NEVER throws.
  */
 export declare function truncateLedgerField(value: string, cap: number): string;
+/**
+ * Canonicalize one Assignment `Execute as` value for the ledger's `role`
+ * field: `trim()`, then strip ONE leading `@`. The `role` column is what
+ * every consumer groups by, so `@explore` and `explore` must be the SAME
+ * role — normalization happens ONCE, at the write boundary (the dispatch row
+ * and its pairing ref, plus the direct `recordSettle` /
+ * `recordSubagentLink` entry points, whose callers may hand in a raw
+ * Assignment value). NO case folding: role ids are host-defined strings, and
+ * folding could merge ids a host intends to keep distinct. No interior
+ * rewrite either — only the edges are trimmed. A missing role stays `''`,
+ * and rows already on disk are never rewritten or renormalized. Pure —
+ * NEVER throws.
+ */
+export declare function normalizeRoleId(value: string): string;
 /** Logger label for the agent-flow ledger (dsh logger naming: `<scope>/<subject>`). */
 export declare const AGENT_FLOW_LOGGER = "mstar/agent-flow";
 /**
@@ -71,12 +89,12 @@ export declare const SETTLE_SEAM = "tools/post-execute";
  * surface, so the constant was renamed to the accurate `PAIRING` name. The
  * message states the VERIFIED pairing facts: the seam is emitted by the
  * registry; foreground dispatch calls settle via it, background subagents
- * settle via `ctx.jobs.onJobDone` pairing; only unpaired payloads stay
- * dispatch-only (never fabricated settlement). Logged ONCE per logger binding
- * (≈ once per apply — the same module-level flag) when the pairing
- * listener is registered.
+ * settle via the `ctx.inject(['jobs'])` → `jobs.onJobDone` pairing; only
+ * unpaired payloads stay dispatch-only (never fabricated settlement). Logged
+ * ONCE per logger binding (≈ once per apply — the same module-level flag)
+ * when the pairing listener is registered.
  */
-export declare const SETTLE_SEAM_PAIRING_NOTE = "settle seam \"tools/post-execute\" IS part of the verified dsh-tools registry surface (runPostExecute dispatches it for every tool call) \u2014 foreground dispatch calls settle here, background subagents settle via ctx.jobs.onJobDone pairing; only UNPAIRED payloads (non-dispatch tools, calls outside the apply-scoped pairing window) stay dispatch-only \u2014 never a fabricated settle";
+export declare const SETTLE_SEAM_PAIRING_NOTE = "settle seam \"tools/post-execute\" IS part of the verified dsh-tools registry surface (runPostExecute dispatches it for every tool call) \u2014 foreground dispatch calls settle here, background subagents settle via ctx.inject(['jobs']) \u2192 jobs.onJobDone pairing; only UNPAIRED payloads (non-dispatch tools, calls outside the apply-scoped pairing window) stay dispatch-only \u2014 never a fabricated settle";
 /** Dispatch verdict vocabulary (spec §2.1.3). */
 export type DispatchVerdict = 'ok' | 'advisory' | 'denied';
 /** Settle outcome vocabulary (spec §2.1.3). */
@@ -177,13 +195,55 @@ export type AgentFlowEvent = {
      * `role` is the Assignment `Execute as` ('' when missing), `planId` /
      * `taskId` the plan + `Task N` tags. Written for every paired settle;
      * ABSENT on unpaired (legacy) settles — the client pairs on identity
-     * presence. The registry background-task id is deliberately NOT
-     * written here (`taskRef` is reserved as the distinct field name if a
-     * future audit needs it — it never collides with `taskId`).
+     * presence (`paired` in the view never depends on `childId`).
      */
     role?: string;
     planId?: string;
     taskId?: string;
+    /**
+     * The settled child session's stable id, when a seam actually supplied
+     * one: the returned foreground `runId`, or a background job's child id
+     * once the catalog join copied it onto the dispatch ref. OMITTED
+     * otherwise — never fabricated, never a registry job id.
+     */
+    childId?: string;
+    /**
+     * The registry background-job id a background settle pairs on
+     * (`jobs.onJobDone` → `recordJobSettle`). A jobs-registry key
+     * (`<kind>-N`), NEVER a child session id and never the Assignment
+     * `Task N` tag (`taskId`).
+     */
+    taskRef?: string;
+} | {
+    v: 1;
+    ts: number;
+    kind: 'subagent-link';
+    /** The dispatching session's stable id (the paired dispatch ref's agent; absent when it carried none). */
+    agent?: string;
+    /**
+     * The catalog `childId` — the child session the dispatch actually
+     * started. REQUIRED: a row whose identity is missing, empty, or
+     * oversized is skipped (never truncated, never fabricated).
+     */
+    childId: string;
+    /**
+     * The delegation `description` the join correlated on, DISPLAY-
+     * normalized and capped at this write boundary (the matcher always
+     * compares the RAW label, never this value).
+     */
+    label: string;
+    /** The paired dispatch's Assignment `Execute as` — written even when `''`. */
+    role: string;
+    /** The paired dispatch's `planIdOf(header)`. */
+    planId?: string;
+    /** The paired dispatch's Assignment `Task N` tag. */
+    taskId?: string;
+    /**
+     * The registry background-job id, on a link whose dispatch started a
+     * background job (`<kind>-N`). A continuable link omits it — that path
+     * starts no registry job. Never a child session id.
+     */
+    taskRef?: string;
 } | {
     v: 1;
     ts: number;
@@ -220,12 +280,71 @@ export interface AgentFlowDispatchRef {
     workflowDir: string;
     /** The dispatching session's stable id ('' when the exec carried none). */
     agent?: string;
-    /** Assignment `Execute as` ('' when missing — the dispatch event's grammar). */
+    /** Assignment `Execute as`, canonicalized by `normalizeRoleId` ('' when missing — the dispatch event's grammar). */
     role: string;
     /** `planIdOf(header)` — the dispatch event's grammar. */
     planId?: string;
     /** `taskIdOf(prompt)` — the Assignment `Task N` tag, NOT a registry task id. */
     taskId?: string;
+    /**
+     * The child session's stable id, once an upstream seam actually supplied
+     * one: the catalog join copies the observed catalog `childId` onto this
+     * ref (the same object survives into `dispatchByJobId`, so a background
+     * settle then carries it). Omitted until known — never a synthetic id and
+     * never a registry job id.
+     */
+    childId?: string;
+    /**
+     * The registry job id of the background call this dispatch started
+     * (observed at `tools/post-execute`, paired by `recordJobSettle`). A
+     * jobs-registry key (`<kind>-N`) — NEVER a child session id and never the
+     * `Task N` tag.
+     */
+    taskRef?: string;
+    /**
+     * The admitted call-window catalog CANDIDATE of this dispatch: the live
+     * parent Session it runs on plus the RAW delegation label that names its
+     * slot. Present only while a reservation is live — `recordDispatch`
+     * installs it, and the post-execute branch either advances it to eligible
+     * or retires it (both release this field). Its presence is what lets the
+     * post-execute path find the join without re-deriving the session.
+     */
+    catalog?: {
+        session: AgentFlowSessionView;
+        label: string;
+    };
+}
+/**
+ * The structural view of one live dsh `Session` the call-window join needs:
+ * the VERIFIED upstream surface (`id` / `seq` / `eventAt`). A real Session
+ * exposes no `events` member — that read is why the join uses `eventAt(seq)`
+ * over a bounded window instead of copying a log. Structural by design (no
+ * session package dependency); `seq` is read LIVE at every use, so the
+ * captured view is also the catch-up bound source while `fromSeq` (stored on
+ * the join) keeps the capture moment.
+ */
+export interface AgentFlowSessionView {
+    readonly id: string;
+    readonly seq: number;
+    eventAt(seq: number): unknown;
+}
+/**
+ * One pending call-window catalog candidate: the recorded dispatch ref and
+ * the `fromSeq` window start. `result` marks ELIGIBILITY — an inert
+ * candidate (no `result` yet, awaiting its post-execute branch) can never be
+ * matched by a catalog, and the slot's `null` tombstone is a
+ * consumed/rejected candidate, never a second one.
+ */
+export interface AgentFlowCatalogJoin {
+    ref: AgentFlowDispatchRef;
+    fromSeq: number;
+    result?: {
+        kind: 'background';
+        jobId: string;
+    } | {
+        kind: 'continuable';
+        subagentId: string;
+    };
 }
 /**
  * The apply-scoped pairing store (
@@ -233,8 +352,8 @@ export interface AgentFlowDispatchRef {
  * cache; an HMR restart resets it, and completions outside the window stay
  * unpaired → no settle, the documented honest degrade). Maps are keyed by
  * the TWO verified pairing keys: the tool-call `callId` (pre → post-execute)
- * and the registry background-task id (post-execute background shape →
- * `onJobDone` terminal).
+ * and the registry background-job id (post-execute background shape →
+ * `jobs.onJobDone` terminal).
  */
 export interface AgentFlowPairing {
     /**
@@ -248,8 +367,19 @@ export interface AgentFlowPairing {
      * by the post-execute branch — the map holds only in-flight calls.
      */
     dispatchByCallId: Map<string, AgentFlowDispatchRef>;
-    /** Registry background-job id (`JobSnapshot.id`) → the dispatch that started it (populated by the post-execute background branch; consumed by `recordTaskSettle`). */
-    dispatchByTaskId: Map<string, AgentFlowDispatchRef>;
+    /** Registry background-job id (`JobSnapshot.id`) → the dispatch that started it (populated by the post-execute background branch; consumed by `recordJobSettle`). */
+    dispatchByJobId: Map<string, AgentFlowDispatchRef>;
+    /**
+     * The call-window catalog join's slots: the EXACT parent Session object →
+     * (RAW delegation label → candidate). A `null` slot is a consumed or
+     * rejected tombstone, never a second candidate — reuse is what would let a
+     * delayed duplicate label or a pre-existing catalog acquire a new owner.
+     * Keying on the session OBJECT (not its id) is what makes the namespace
+     * session-incarnation safe and delimiter-free; per Session the map holds at
+     * most `AGENT_FLOW_MAX_EVENTS` slots (new keys are refused at capacity —
+     * existing pending entries and tombstones are retained).
+     */
+    catalogBySession: WeakMap<object, Map<string, AgentFlowCatalogJoin | null>>;
 }
 /** Module-scoped log sink (bound to `mstar/agent-flow` by the entry at apply). */
 type AgentFlowLogSink = (level: 'info' | 'warn' | 'error', message: string) => void;
@@ -274,8 +404,8 @@ type AgentFlowInvalidator = (harnessDir: string) => void;
 export declare function setAgentFlowInvalidator(invalidate: AgentFlowInvalidator | undefined): AgentFlowInvalidator | undefined;
 /**
  * Bind the module's log sink (called once at apply; tests may rebind to
- * capture ledger logs). Rebinding RESETS the once-per-apply settle trace
- * flag — each binding is a fresh "apply" (production binds once; tests bind
+ * capture ledger logs). Rebinding RESETS the once-per-apply trace latches
+ * — each binding is a fresh "apply" (production binds once; tests bind
  * per case for deterministic capture).
  * @param sink - the sink (entry binds `ctx.logger('mstar/agent-flow')`);
  * `undefined` clears the binding (restores the pre-bind no-op state).
@@ -295,24 +425,50 @@ export declare function setAgentFlowLogger(sink: AgentFlowLogSink | undefined):
  */
 export declare function taskIdOf(prompt: string): string | undefined;
 /**
- * Resolve the agent-flow WRITE target dir for one harness dir: the ACTIVE
- * workflow's dir (root v2 `workflows[]` first entry — the shared active-set
- * resolver; the terminal-mtime fallback is catalog-read-only and MUST NOT
- * enter the writer's module graph). The active set is defined by root
- * `workflows[]` MEMBERSHIP — non-terminal lifecycles (`running` AND
- * `paused`; terminal lifecycles are removed at terminal) — so a paused
- * lifecycle stays a valid append target (explicit decision, plan
+ * The write-path selection for one session: the resolver verdict plus the
+ * absolute dir that verdict resolves to. The ledger needs BOTH (it
+ * classifies the unbound skip to keep the no-backfill floor honest), and
+ * both must come from ONE registry read — {@link resolveAgentFlowWriteDir}
+ * is the dir-only facade over this.
+ */
+export interface AgentFlowWriteTarget {
+    /** The absolute workflow dir (`<harnessDir>/workflows/<id>`), or `null` when this session may not write. */
+    dir: string | null;
+    /** The verdict `dir` was derived from. */
+    selection: ActiveWorkflowSelection;
+}
+/**
+ * Resolve the agent-flow WRITE target for one harness dir: the ACTIVE
+ * workflow the CARRYING SESSION is bound to (root v2 `workflows[]` — the
+ * shared active-set resolver; the terminal-mtime fallback is
+ * catalog-read-only and MUST NOT enter the writer's module graph). The active
+ * set is defined by root `workflows[]` MEMBERSHIP — non-terminal lifecycles
+ * (`running` AND `paused`; terminal lifecycles are removed at terminal) — so
+ * a paused lifecycle stays a valid append target (explicit decision, plan
  * the workflow viz plan).
  *
- * No active entry → `null`: the record is SKIPPED with a one-time warn
+ * D4 binding: `hint` carries the session's lease/cwd/pick evidence, so two
+ * sessions writing in ONE harness reach two different workflow dirs. An
+ * omitted hint is the exec-less case — the automatic rungs miss and only a
+ * unique active lifecycle resolves.
+ *
+ * No bound entry → `dir: null`: the record is SKIPPED with a one-time warn
  * (per sink binding) — never a silent write into the root v1 file, never a
- * write into a terminal snapshot dir (compass v3.0.0 § Catalog selection
- * rule — the writer appends only to an active lifecycle).
+ * write into a terminal snapshot dir, never another session's lifecycle
+ * (compass v3.0.0 § Catalog selection rule — the writer appends only to an
+ * active lifecycle).
  * @param harnessDir - the resolved `{HARNESS_DIR}`.
- * @returns the absolute workflow dir (`<harnessDir>/workflows/<id>`), or
- *   `null` when no active lifecycle resolves.
+ * @param hint - the carrying session's structural identity + durable pick.
  */
-export declare function resolveAgentFlowWriteDir(harnessDir: string): string | null;
+export declare function resolveAgentFlowWriteTarget(harnessDir: string, hint?: SessionHint): AgentFlowWriteTarget;
+/**
+ * The dir-only facade over {@link resolveAgentFlowWriteTarget} — the pinned
+ * writer contract every record path uses.
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param hint - the carrying session's structural identity + durable pick.
+ * @returns the absolute workflow dir, or `null` when nothing may be written.
+ */
+export declare function resolveAgentFlowWriteDir(harnessDir: string, hint?: SessionHint): string | null;
 /**
  * Lock-directory name for the per-workflow write lock :
  * guards the ledger append + size-gated truncating read-modify-write AND
@@ -378,11 +534,16 @@ export declare function withWorkflowDirLock<T>(workflowDir: string, fn: () => T,
  * only after the ledger append SUCCEEDED — a failed record never pairs to a
  * phantom dispatch. An exec-less record (host-hook path) has no callId → no
  * pairing. The pairing sub-path has its OWN catch scope: a `Map.set` throw must not log "record
- * failed" after the dispatch was already appended.
+ * failed" after the dispatch was already appended. On that same successful
+ * pairing the dispatch's call-window catalog candidate is RESERVED (the
+ * first RAW-label slot under the live parent Session, when the exec carries
+ * one) — the child-identity join's step 1; admission is all-or-nothing and
+ * never affects the dispatch, the pairing, or a later settle.
  * @param input - the harness dir; the dispatching exec's agent id; the
  * Assignment text; the gate's violations; the hard-enforcement resolution;
  * the apply-scoped pairing store (the adapter passes its own; direct callers
- * may omit it).
+ * may omit it); the carrying session's `hint` (the adapter derives it — this
+ * module never reads the picker store).
  */
 export declare function recordDispatch(input: {
     harnessDir: string;
@@ -391,6 +552,8 @@ export declare function recordDispatch(input: {
     violations: readonly unknown[];
     hard: boolean;
     pairing?: AgentFlowPairing;
+    /** The carrying session's selection hint — decides WHICH active lifecycle the row lands in. */
+    hint?: SessionHint;
 }): void;
 /**
  * Record one settle event (spec §2.1.3). Fully try/catch-contained; a failing
@@ -405,7 +568,15 @@ export declare function recordDispatch(input: {
  * outcome + optional duration + the PAIRED dispatch's identity
  * (`role`/`planId`/`taskId` — same field names + semantics as the dispatch
  * event; written for every paired settle, so the client can exactly pair
- * the settle back to its dispatch).
+ * the settle back to its dispatch — `role` is canonicalized by
+ * `normalizeRoleId`, so a direct caller's raw `@role` lands in the same
+ * grammar as the dispatch row) + the OPTIONAL child identity
+ * (`childId` — the settled child session; `taskRef` — a background settle's
+ * registry job id). A missing, empty, or oversized optional id is OMITTED
+ * from the row (never truncated, never re-keyed) and the completion still
+ * records. The carrying session's `hint` is the no-dir fallback (a PAIRED
+ * settle keeps its pinned `workflowDir` — a later pick must never split a
+ * dispatch from its settle).
  */
 export declare function recordSettle(input: {
     harnessDir: string;
@@ -416,6 +587,10 @@ export declare function recordSettle(input: {
     role?: string;
     planId?: string;
     taskId?: string;
+    /** The carrying session's selection hint — consulted ONLY when no `workflowDir` is pinned. */
+    hint?: SessionHint;
+    childId?: string;
+    taskRef?: string;
 }): void;
 /**
  * Record one workflow ledger event (the JSONL schema below
@@ -436,10 +611,11 @@ export declare function recordSettle(input: {
  * `harnessDir`. No active lifecycle → `false` (skipped with a one-time warn
  * — never a root v1 write, never a terminal snapshot write).
  * @param input - harness dir + optional pre-resolved active workflow dir +
- * the fully-shaped v1 workflow event.
+ * the fully-shaped v1 workflow event + the carrying session's `hint` for the
+ * no-dir fallback (a pinned dir always wins).
  * @returns `true` when the row was appended (the caller may durably advance
  *   its watermark); `false` on a contained append failure OR when no active
- *   lifecycle resolves — the caller must leave the cursor behind so the row
+ *   lifecycle is bound — the caller must leave the cursor behind so the row
  *   is re-attempted at the next scan (advance-then-record made a
  *   failed append permanent loss).
  */
@@ -447,6 +623,8 @@ export declare function recordWorkflowEvent(input: {
     harnessDir: string;
     workflowDir?: string;
     event: AgentFlowWorkflowEvent;
+    /** The carrying session's selection hint — consulted ONLY when no `workflowDir` is pinned. */
+    hint?: SessionHint;
 }): boolean;
 /**
  * Input for {@link recordWorkflowVerdict} — one gated workflow/ralph call's
@@ -470,6 +648,13 @@ export interface WorkflowVerdictInput {
     verdict: WorkflowVerdict;
     /** The policy violation code (advisory/ask/denied rows only). */
     code?: string;
+    /**
+     * The carrying session's selection hint (the adapter derives it from the
+     * same `exec` it passes here) — decides WHICH active lifecycle the verdict
+     * row lands in. Absent (exec-less / unreadable binding store) → the row is
+     * skipped rather than attributed to an arbitrary lifecycle.
+     */
+    hint?: SessionHint;
 }
 /**
  * Record one workflow/ralph gate verdict row . Fully
@@ -532,18 +717,37 @@ export declare function readAgentFlow(workflowDir: string, limit?: number): Agen
  * - `result.isError === true` OR an `error` payload present → settle `error`
  *   immediately (fabrication guard — the dispatch
  *   call failed; a result carrying `error` without `isError` never settles ok);
- * - successful `result.value` shape `{ kind: 'background', taskId }` with a
- *   valid taskId → store `taskId → dispatchRef` (the real settle arrives via
- *   `ctx.jobs.onJobDone`); `{ kind: 'background' }` WITHOUT a valid taskId
- *   → nothing mappable (no settle);
+ * - successful `result.value` shape `{ kind: 'background', jobId }` with a
+ *   valid jobId (the registry id, `<kind>-N` — never a child session id) →
+ *   store `jobId → dispatchRef` and the bounded job id as the ref's `taskRef`
+ *   (so the eventual `jobs.onJobDone` settle carries it); `{ kind: 'background' }`
+ *   WITHOUT a valid jobId → nothing mappable (no settle);
  * - `{ kind: 'continuable', subagentId }` → no terminal signal this round →
- *   no settle (documented limit — the child owns its turns);
+ *   no settle (documented limit — the child owns its turns), and NOTHING is
+ *   copied from its value onto any row;
  * - any other successful value (foreground `{ kind: 'foreground', … }`
  *   included) → settle `ok` (the call completed synchronously).
+ * Child identity: a returned foreground `runId` becomes the settle's
+ * `childId`, extracted from the value INDEPENDENTLY of the outcome branch —
+ * a failed call whose value still carries a foreground `runId` keeps that
+ * identity on its `error` settle (identity never turns an error into `ok`).
  * The consumed `dispatchByCallId` entry is DELETED after the branch resolves
  * the call (map pruning — each callId
  * pairs exactly once; the map holds only in-flight calls).
  *
+ * Catalog candidate (steps 2–3 of the child-identity join): the SAME branch
+ * decides the dispatch's reserved call-window catalog candidate — a valid
+ * background result makes it eligible expecting the job's `one-shot` catalog
+ * (after the job pairing + `taskRef` are in place), a valid continuable
+ * result makes it eligible for exactly the returned `subagentId`, and every
+ * other outcome (other success / foreground, tool error, missing result
+ * payload, malformed result, invalid background job id) retires it to its
+ * tombstone. Eligibility then runs the catch-up walk over
+ * `[fromSeq, session.seq)` through the same matcher the live observer uses,
+ * so a catalog appended before this seam ran is still recovered. Both
+ * candidate helpers are self-contained: a throwing join degrades to a log
+ * line and NEVER costs the settle/awarded identity its row.
+ *
  * The waterfall MUST be delegated via `next()` on every path — returning
  * without calling `next` bails the chain and breaks every tool call. A
  * throwing record never propagates.
@@ -554,21 +758,24 @@ export declare function readAgentFlow(workflowDir: string, limit?: number): Agen
  * @param ctx - registrant context (fiber disposal unwinds the listener).
  * @param config - the plugin Config (dispatch-tool matching).
  * @param pairing - the apply-scoped pairing store (dispatchByCallId read,
- * dispatchByTaskId written by the background branch).
+ * dispatchByJobId written by the background branch, catalogBySession
+ * advanced/retired here).
  */
 export declare function registerSettleListener(ctx: Context, config: Config, pairing: AgentFlowPairing): void;
 /**
  * The structural read of the dsh-jobs terminal snapshot the pairing consumes
- * (the settle-pairing upgrade). The `ctx.jobs.onJobDone`
- * contract was verified against the upstream `@deepseek-ai/dsh-jobs`
- * `types.ts`: `JobDoneListener = (snapshot, owner) => …`, terminal
- * `snapshot.status` ∈ `completed | killed | failed`, `startedAt`/`finishedAt`
- * are epoch ms (`finishedAt` absent while running). Structural (no runtime or
+ * (the settle-pairing upgrade). The `ctx.inject(['jobs'])` →
+ * `jobs.onJobDone` contract was verified against the upstream
+ * `@deepseek-ai/dsh-jobs` `types.ts`: `JobDoneListener = (snapshot, owner) =>
+ * …`, terminal `snapshot.status` ∈ `completed | killed | failed`,
+ * `startedAt`/`finishedAt` are epoch ms (`finishedAt` absent while running).
+ * `id` stays the registry-issued JOB id (`<kind>-N`, e.g. `subagent-1`) — it
+ * is a jobs-registry key, NOT a child session id. Structural (no runtime or
  * type import of the optional dsh-jobs seam — the plugin treats it as an
  * optional service, wired via `ctx.inject(['jobs'])`).
  */
-export interface TaskDoneSnapshot {
-    /** The registry-issued task id (`<kind>-N`, e.g. `subagent-1`). */
+export interface JobDoneSnapshot {
+    /** The registry-issued job id (`<kind>-N`, e.g. `subagent-1`) — never a child session id. */
     id: string;
     /** Terminal lifecycle status: `completed | killed | failed`. */
     status: string;
@@ -578,20 +785,65 @@ export interface TaskDoneSnapshot {
     finishedAt?: number;
 }
 /**
- * Record the settle for one background-task terminal (plan
- * the `ctx.jobs.onJobDone` path):
- * the snapshot's task id must hit the pairing store's `dispatchByTaskId`
- * (populated by the post-execute background branch) — a miss records NOTHING
- * (honest degrade, never fabricated). Outcome mapping: `completed → ok` /
- * `killed → denied` / `failed → error`; `durationMs = finishedAt − startedAt`
- * when both are present. After a SUCCESSFUL settle the consumed
- * `dispatchByTaskId` entry is deleted (map pruning — the map holds only
- * in-flight tasks; a contract-violating
+ * Record the settle for one background-job terminal (plan
+ * the `ctx.inject(['jobs'])` → `jobs.onJobDone` path):
+ * the snapshot's registry job id must hit the pairing store's
+ * `dispatchByJobId` (populated by the post-execute background branch) — a
+ * miss records NOTHING (honest degrade, never fabricated). Outcome mapping:
+ * `completed → ok` / `killed → denied` / `failed → error`;
+ * `durationMs = finishedAt − startedAt` when both are present. After a
+ * SUCCESSFUL settle the consumed `dispatchByJobId` entry is deleted (map
+ * pruning — the map holds only in-flight jobs; a contract-violating
  * non-terminal snapshot records nothing and KEEPS the entry so a later real
- * terminal can still settle). Fully contained — never throws into the task
+ * terminal can still settle). Fully contained — never throws into the job
  * registry's listener notification.
- * @param snapshot - the terminal task snapshot (structural read).
+ * @param snapshot - the terminal job snapshot (structural read).
  * @param pairing - the apply-scoped pairing store.
  */
-export declare function recordTaskSettle(snapshot: TaskDoneSnapshot, pairing: AgentFlowPairing): void;
+export declare function recordJobSettle(snapshot: JobDoneSnapshot, pairing: AgentFlowPairing): void;
+/**
+ * Record one NONTERMINAL `subagent-link` row — the call-window join's output:
+ * the child session a dispatch actually started, correlated back to the
+ * dispatch identity mstar recorded. This is an IDENTITY record, not a
+ * completion: the row carries NO `outcome`, NO `verdict` and NO `paired`
+ * marker (the child is still running this round), and `ts` is the link
+ * OBSERVATION time — never a fabricated child-creation time
+ * (`childCreatedAt` is validated upstream, it is not another ledger clock).
+ * The row is written ONLY from a candidate that actually matched, and only
+ * from the ref of a dispatch that was really recorded: a link is never a
+ * guess or a synthesis.
+ *
+ * Attribution follows the dispatch, not the clock: the row lands in
+ * `ref.workflowDir` (the dir the dispatch was appended to), never in today's
+ * active workflow dir, and the ref's `harnessDir` is the invalidation key.
+ * Fully try/catch-contained — a failing link write logs only and never
+ * escapes into the session append (or the job notification) that triggered
+ * it.
+ * @param input - the retained dispatch ref, the observed catalog `childId`,
+ *   and the RAW delegation label the join matched on.
+ */
+export declare function recordSubagentLink(input: {
+    ref: AgentFlowDispatchRef;
+    childId: string;
+    label: string;
+}): void;
+/**
+ * The LIVE half of the call-window join (step 4): ONE root-context
+ * `session/event` observer, registered by the entry at apply — before
+ * execution can start — that reads only an ELIGIBLE slot of the EXACT
+ * carrying Session. The root (untagged) registration is admitted globally by
+ * the session store's scope carrier, so a catalog appended by any session
+ * reaches it; slots for every other session are simply absent from the
+ * WeakMap, and an inert (pending) or tombstoned slot is skipped. Its window
+ * bound is the live `session.seq`, not the catch-up endpoint, so a catalog
+ * appended after eligibility is still joined.
+ *
+ * No cold scan and no `session/created` backfill: a catalog written before
+ * apply has no surviving dispatch ref, so it can never label a future
+ * same-label dispatch. Contained — a throwing observation never escapes the
+ * session append.
+ * @param ctx - registrant context (fiber disposal unwinds the observer).
+ * @param pairing - the apply-scoped pairing store (the slots).
+ */
+export declare function registerSubagentCatalogListener(ctx: Context, pairing: AgentFlowPairing): void;
 export {};