@mstar-harness/dsh 3.8.1 → 3.8.3

package/dist/gates/catalog.d.ts

@@ -3,49 +3,67 @@ import { type UserMessage } from '@deepseek-ai/dsh-llm';
 import type { PreStepDecision } from '@deepseek-ai/dsh-agent';
 import type { MstarEngineStatusPayload } from '../types.ts';
 import { HarnessResolver } from './_shared.ts';
+import { type SessionHint } from './workflow-selection.ts';
 /** Default catalog cache refresh interval (ms) — see Config `catalogTtlMs`. */
 export declare const DEFAULT_CATALOG_TTL_MS = 60000;
-/** Catalog cache key for the explicit-`harnessDir` app-wide entry (one entry for every session). */
-export declare const EXPLICIT_CACHE_KEY = "\0explicit";
 /** One TTL cache entry: the unified payload plus the build timestamp. */
 export interface CatalogCacheEntry {
     payload: MstarEngineStatusPayload;
     builtAt: number;
 }
 /**
- * The apply-scoped `harnessDir → cache key` reverse map + invalidation
- * closure : the
- * catalog cache is keyed by {@link EXPLICIT_CACHE_KEY} or the session cwd,
- * while ledger records (dispatch/settle) identify the affected workspace by
- * `{HARNESS_DIR}` — the reverse map bridges the two so a ledger change
- * deletes EXACTLY the affected workspace's entry (no global clear; a
- * multi-workspace deployment does not rebuild every workspace). BOTH the map
- * and the closure are created per-apply by the entry (same lifetime as the
- * cache): module-level state would survive an HMR fiber restart and point at
- * a destroyed cache.
+ * The apply-scoped catalog invalidation (D4): the `harnessDir → { session →
+ * cache key }` reverse map + the digest set, created per-apply by the entry
+ * (same lifetime as the cache — module-level state would survive an HMR fiber
+ * restart and point at a destroyed cache).
+ *
+ * WHY a set per harness: two sessions in one workspace key their OWN catalog
+ * payloads, so a ledger record for that harness must drop EVERY current
+ * session key (never a single shared one) — and a picker commit must drop
+ * exactly ONE session's key without touching its neighbours.
  */
 export interface CatalogInvalidation {
     /**
-     * Register `key` as the cache key of `harnessDir` — called by
-     * `catalogPayloadFor` on cache hit AND build, and pre-registered by the
-     * entry at apply for the explicit-config boot entry (a ledger record
-     * between apply and the first pre-step must still invalidate the
-     * pre-seeded entry). A null harness dir (no `{HARNESS_DIR}` resolved) has
-     * no cache entry to invalidate → no-op.
+     * Register `key` as one session's cache key for `harnessDir` — called by
+     * `catalogPayloadFor` on hit AND build. A session whose hint changed
+     * (a picker commit) has its OLD key dropped here, so the reverse map never
+     * grows a key history. A null harness dir or a session with no stable id
+     * has no cached entry to invalidate → no-op.
      */
-    register(harnessDir: string | null, key: string): void;
+    register(harnessDir: string | null, sessionId: string | undefined, key: string): void;
     /**
-     * Delete the cache entry of `harnessDir` (D3 — the ledger record path
-     * invokes this through the apply-bound hook). A missing mapping is a safe
-     * no-op, and a missing entry after a previous invalidation is a no-op too
-     * (the next pre-step rebuilds regardless). A throwing invalidation is
-     * contained by the record path (log-only — it never blocks the ledger
-     * record).
+     * Delete every current session's cache entry for `harnessDir` (the ledger
+     * record path invokes this through the apply-bound hook). A missing mapping
+     * is a safe no-op, and a missing entry after a previous invalidation is a
+     * no-op too (the next pre-step rebuilds regardless). A throwing
+     * invalidation is contained by the record path (log-only — it never blocks
+     * the ledger record).
      */
     invalidate(harnessDir: string): void;
+    /**
+     * Delete ONE session's cache entry (and its re-emission digest) — the
+     * picker commit path: the session's durable hint changed, so the next
+     * pre-step rebuilds from the acknowledged binding and re-emits the row
+     * within the same turn instead of serving the pre-pick payload until the
+     * TTL expires.
+     */
+    invalidateSession(harnessDir: string | null, sessionId: string | undefined): void;
 }
-/** Create the apply-scoped invalidation bound to ONE catalog cache (entry-internal wiring — see {@link CatalogInvalidation}). */
-export declare function createCatalogInvalidation(cache: Map<string, CatalogCacheEntry>): CatalogInvalidation;
+/** Create the apply-scoped invalidation bound to ONE catalog cache + its digests. */
+export declare function createCatalogInvalidation(cache: Map<string, CatalogCacheEntry>, digests: Map<string, TurnDigest>): CatalogInvalidation;
+/**
+ * The cache key of ONE session's catalog payload (D4): the resolved harness
+ * dir + the durable `session.header.id` + the session cwd + the EFFECTIVE
+ * hint fields that can change the selection (the opaque lease holder and the
+ * durable pick — cwd and session id are already in the tuple). Two sessions in
+ * the same cwd therefore never share a payload, and a picker commit is a
+ * different key rather than a mutated entry.
+ *
+ * Encoded as a JSON string array so a delimiter (NUL / quote / comma) inside
+ * an opaque field cannot fuse two distinct tuples — `\u0000`-join was not
+ * collision-free for those values.
+ */
+export declare function catalogCacheKey(harnessDir: string | null, sessionId: string, cwd: string, hint: SessionHint | undefined): string;
 /**
  * Build the unified catalog payload for one harness dir (boot for the
  * explicit config, first-use per workspace otherwise, then TTL-refreshed —
@@ -54,8 +72,11 @@ export declare function createCatalogInvalidation(cache: Map<string, CatalogCach
  * fallback is never silent.
  * @param ctx - registrant context (logger for the manifest fallback).
  * @param harnessDir - the resolved `{HARNESS_DIR}` (null when none found).
+ * @param hint - the carrying session's structural identity + durable pick
+ *   (omitted ⇒ the automatic rungs miss and only a unique active lifecycle —
+ *   or the picker error — resolves).
  */
-export declare function buildCatalogPayload(ctx: Context, harnessDir: string | null): MstarEngineStatusPayload;
+export declare function buildCatalogPayload(ctx: Context, harnessDir: string | null, hint?: SessionHint): MstarEngineStatusPayload;
 /**
  * Advisory `agent/pre-step` waterfall listener (agent
  * catalog): delegates through `next()` (never `reject` — that would block the
@@ -89,26 +110,26 @@ export declare function buildCatalogPayload(ctx: Context, harnessDir: string | n
  * @param ctx - registrant context (logger for the containment path).
  * @param resolver - the per-workspace `{HARNESS_DIR}` resolver (the probe
  * never starts from the process cwd).
- * @param explicitKey - the app-wide cache key when an explicit
- * `harnessDir` config is set (undefined → per-session-cwd keys).
- * @param cache - per-workspace TTL catalog sources cache (boot pre-seeded
- * for the explicit-config case; otherwise built on first use of each
- * workspace root and TTL-refreshed — Config `catalogTtlMs`).
+ * @param cache - per-session TTL catalog cache: each session's payload is
+ * keyed by harness dir + `session.header.id` + cwd + effective hint, so two
+ * sessions in one workspace never share a selection; a session with no stable
+ * id is built uncached.
  * @param ttlMs - catalog refresh interval in milliseconds.
- * @param register - the apply-scoped `harnessDir → cache key` reverse-map
- * registration. * @param digests - per agent+workspace turn digests (last rendered text)
+ * @param invalidation - the apply-scoped session-keyed invalidation (ledger
+ * records evict every session of a harness; a picker commit evicts one).
+ * @param digests - per session+workspace turn digests (last rendered text)
  * for the digest-gated re-emission.
  * @param payload - the proposed step the loop is about to enter.
  * @param next - the remaining pre-step chain; its value is the delegated decision.
  */
-export declare function preStepCatalogListener(ctx: Context, resolver: HarnessResolver, explicitKey: string | undefined, cache: Map<string, CatalogCacheEntry>, ttlMs: number, register: (harnessDir: string | null, key: string) => void, digests: Map<string, TurnDigest>, payload: {
+export declare function preStepCatalogListener(ctx: Context, resolver: HarnessResolver, cache: Map<string, CatalogCacheEntry>, ttlMs: number, invalidation: CatalogInvalidation, digests: Map<string, TurnDigest>, payload: {
     agent: unknown;
     messages: UserMessage[];
     turn: number;
     step: number;
     signal: AbortSignal;
 }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>;
-/** Per agent+workspace turn digest: the rendered catalog text as of the last injection. */
+/** Per session+workspace turn digest: the rendered catalog text as of the last injection. */
 export interface TurnDigest {
     turn: number;
     text: string;

package/dist/gates/dispatch.d.ts

@@ -3,6 +3,7 @@ import type { AssignmentFields, GateResult, ValidationResult } from '@mstar-harn
 import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools';
 import { HarnessResolver } from './_shared.ts';
 import type { Config } from './_shared.ts';
+import type { SessionHint } from './workflow-selection.ts';
 import type { DshHostAdapter } from './adapter.ts';
 /** Logger label for the dispatch gate (dsh logger naming: `<scope>/<subject>`). */
 export declare const DISPATCH_LOGGER = "mstar/dispatch-gate";
@@ -116,8 +117,13 @@ export declare function sessionIdOf(exec: ToolExecution): string | undefined;
  * claim-before-InProgress red line needs the plan's execution_lease, and a
  * missing root/snapshot cannot confirm it — `lease.dispatch.unverifiable`
  * fires (advisory in warn, deny under hard).
+ * @param hint - the carrying session's selection hint: it decides WHICH
+ *   active lifecycle's snapshot the lease is re-verified against, so a
+ *   session that is not bound to the lifecycle holding the plan row stops
+ *   with `lease.dispatch.plan-not-found` instead of verifying a lease it
+ *   does not own.
  */
-export declare function leaseGateViolations(harnessDir: string | null, exec: ToolExecution, writable: boolean | undefined, prompt: string): ValidationResult[];
+export declare function leaseGateViolations(harnessDir: string | null, exec: ToolExecution, writable: boolean | undefined, prompt: string, hint?: SessionHint): ValidationResult[];
 /**
  * The dispatch-gate validation core — the engine's SINGLE dispatch-gate
  * composition (`dispatch.composeDispatchGate`, opencode/omp/CLI parity — the
@@ -142,8 +148,11 @@ export declare function leaseGateViolations(harnessDir: string | null, exec: Too
  *
  * @returns the violations plus the writable flag (false for read-only
  * roles — the listener feeds it to the lease gate).
+ * @param hint - the carrying session's selection hint (the adapter derives
+ *   it once per dispatch and shares it with the lease gate, the ledger
+ *   record and every selection read below).
  */
-export declare function dispatchGateCore(config: Config, harnessDir: string | null, prompt: string): {
+export declare function dispatchGateCore(config: Config, harnessDir: string | null, prompt: string, hint?: SessionHint): {
     violations: ValidationResult[];
     writable: boolean | undefined;
 };

package/dist/gates/goal-bridge.d.ts

@@ -1,13 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { Config, HarnessResolver } from './_shared.ts';
+import type { HarnessResolver } from './_shared.ts';
 /** Logger label for the goal bridge (dsh logger naming: `<scope>/<subject>`). */
 export declare const GOAL_BRIDGE_LOGGER = "mstar/goal-bridge";
-/**
- * Flat `maxGoalRounds` config fallback (architect decision — plan
- *  ): 256, aligned with the GoalService default
- * (`goal/src/index.ts:187`) and ralph `maxRounds` (`tool-ralph/src/index.ts:37`).
- */
-export declare const DEFAULT_MAX_GOAL_ROUNDS = 256;
 /** Consumer log levels the module sink understands. */
 export type GoalBridgeLogLevel = 'debug' | 'warn';
 /** Module-level consumer log sink — bound by `apply` to `ctx.logger(GOAL_BRIDGE_LOGGER)` (agent-flow ledger precedent). */
@@ -19,130 +13,16 @@ export type GoalBridgeLogSink = (level: GoalBridgeLogLevel, message: string) =>
  */
 export declare function setGoalBridgeLogger(sink: GoalBridgeLogSink): GoalBridgeLogSink;
 /**
- * Root-agent discriminator (T1-verified; shared with the planMode bridge via
- * explicit no-barrel import): `header.parentSession === undefined` ⇒
- * root-like. Conversation forks also carry `parentSession` (seed lineage) →
- * conservatively excluded from the goal mirror (accepted boundary).
- */
-export declare function isRootLikeAgent(agent: unknown): boolean;
-/** CAS identity for one exact goal revision (upstream `GoalRef`). */
-export interface GoalRefView {
-    readonly id: string;
-    readonly revision: number;
-}
-/** The one goal surface the bridge reads (`GoalSnapshot` fields used by the mirror). */
-export interface GoalView extends GoalRefView {
-    readonly objective: string;
-    readonly phase: string;
-    readonly maxGoalRounds: number;
-}
-/**
- * Minimal structural view of the goals service the bridge consumes
- * (`@deepseek-ai/dsh-goal` `GoalService` — every method is agent-scoped;
- * the runtime read is `ctx.get('goals')` without the inject requirement,
- * same pattern as the probe's service view). `create` throws
- * `GOAL_ALREADY_EXISTS` on a live non-complete goal and REPLACES a
- * completed one ("A completed goal may be replaced" — `goal/src/
- * index.ts:244-257`); `complete` is a CAS by `{ id, revision }`
- * (`GOAL_STALE_REVISION` on stale). The drift path uses complete+create
- * (never `edit`) so each new iteration gets a FRESH goal with a clean
- * round budget. */
-export interface GoalsServiceView {
-    get(agent: unknown): GoalView | undefined;
-    create(agent: unknown, request: {
-        objective: string;
-        maxGoalRounds?: number;
-    }): unknown;
-    complete(agent: unknown, ref: GoalRefView): unknown;
-}
-/** The `agents` service surface the `subagent/start` root walk reads. */
-interface AgentsView {
-    get(id: string): unknown;
-}
-/**
- * The mirrored goal objective: the COMPLETE iteration flow with the exit
- * definition (mstar-host `/goal` rule — advancing an iteration means the
- * entire flow, never a sub-stage). Session-level text only — `status.json`
- * stays the harness SSOT.
- */
-export declare function iterationGoalObjective(iterationId: string): string;
-/**
- * Locate the steering iteration compass (mirror of the engine's
- * `resolveCompassEnforcement` scan + the catalog's `steeringCompassPath`):
- * the FIRST `{ITERATION_DIR}/<id>/delivery-compass.md` whose frontmatter
- * `status` is `active` or `locked` — the directory name IS the iteration id
- * (plan-conventions `{ITERATION_DIR}/<id>/`). Completed/status-less/archived
- * compasses do not steer. Silent on any read failure (advisory degrade).
- * Shared with the planMode bridge via explicit no-barrel import (the same "is an active iteration steering" read).
- * @param harnessDir - the resolved `{HARNESS_DIR}`.
- */
-export declare function steeringCompass(harnessDir: string): {
-    iterationId: string;
-} | undefined;
-/** Inputs of the mirror: the structural goals view, the per-workspace resolver, and the resolved round cap. */
-export interface MirrorIterationGoalInput {
-    resolver: HarnessResolver;
-    /** The structural goals view (`ctx.get('goals')`); absent → the mirror is inert. */
-    goals?: GoalsServiceView;
-    /** The resolved `maxGoalRounds` (flat config key, absent → {@link DEFAULT_MAX_GOAL_ROUNDS}). */
-    maxGoalRounds: number;
-}
-/**
- * Mirror the steering iteration objective into the goal of ONE agent.
- * Root-like agent (`header.parentSession === undefined`) + active iteration
- * (compass `status: active|locked`): `get` → absent → `create` (get-先行 —
- * no `GOAL_ALREADY_EXISTS`); present with drifted objective → REPLACE with
- * a fresh goal for the new iteration (see {@link replaceDriftedGoal} — a
- * completed goal is `create`d directly, a live goal is `complete`d first;
- * the new goal starts with a CLEAN round budget); present with the matching
- * objective → no-op (idempotent decision-point re-evaluation). ONE stale
- * re-read retry; a second stale failure is warned and abandoned —
- * goal-service-side concurrency is rare.
- *
- * @returns `true` when the mirror is ensured for this agent (created,
- * replaced, or already in place); `false` when not applicable or a
- * contained failure occurred. Never throws — the caller's listener stays
- * contained.
- */
-export declare function mirrorIterationGoal(agent: unknown, input: MirrorIterationGoalInput): boolean;
-/**
- * Resolve the ROOT agent of a published child via the `parentSession` walk
- * (upstream `subagent/src/continuation.ts:819-831` precedent): in-process
- * subagent children stamp `header.parentSession` = the parent SESSION id,
- * which IS the parent agent id (a session per agent); the walk stops at the
- * first root-like ancestor. `undefined` when unresolvable (fork lineage,
- * non-in-process provider, registry gap, or a cycle) — the decision point
- * then silently skips. Cycle guard: a `seen` set over visited session ids
- * (the upstream `liveLineage` guard) breaks on ANY revisited id — a 1-hop self-loop, a 2+ hop cycle
- * (A→B→A), or a longer malformed lineage — instead of spinning forever on
- * the synchronous `subagent/start` decision-point listeners (reachable via
- * HMR remounts, resumed/forked sessions with stale headers, or a future
- * host change). Shared with the planMode bridge via explicit no-barrel
- * import (the same `subagent/start` decision-point root walk).
- */
-export declare function rootAgentOf(agent: unknown, agents: AgentsView): unknown | undefined;
-/**
- * Register the goal bridge: an `agent/session-start` listener (root filter
- * inside the mirror — root and children alike fire, `runtime-types.ts:217`)
- * plus a decision-point re-evaluation on `subagent/start` (the existing
- * decision point — index.ts advisory slot), resolving the delegating ROOT
- * via the `parentSession` walk — the two mirror edges are idempotent (get +
- * compare when the mirror is in place — no churn) — plus a THIRD, advisory
- * listener on the `session/event` firehose : a `goal/change`
- * envelope whose goal is blocked logs ONE warn (code + objective summary +
- * project-register residual pointer) with ZERO harness writes
- * (the one-way mirror; see {@link warnBlockedGoal}). The goals service is an
- * OPTIONAL seam (`ctx.get('goals')` structural read): absent → ONE debug log
- * + the mirror stays inert, never a boot failure — the blocked advisory is
- * independent of it (it only needs the firehose + resolver). Every listener
- * body is try/catch-contained.
+ * Register the goal bridge: ONE `session/event` firehose listener
+ * (workflow-ledger consumer precedent) that structurally filters the durable
+ * `goal/change` envelopes and logs the blocked advisory (see
+ * {@link warnBlockedGoal}). It resolves no service — the envelope carries
+ * the facts, and the workspace attribution comes from the goal-owning
+ * session's `header.cwd`; an unresolvable harness → silent skip. Observe-only:
+ * no goal mutation of any kind (`create` / `edit` / `complete` / `pause` /
+ * `resume`), and the goal-owning agent is never read.
  *
  * @param ctx - the plugin's registrant context (the app composition root).
  * @param resolver - the shared per-workspace `{HARNESS_DIR}` resolver.
- * @param config - validated plugin configuration (flat `maxGoalRounds`,
- *   absent → {@link DEFAULT_MAX_GOAL_ROUNDS}; a non-positive / non-integer
- *   value warns once and falls back to the default — see
- *   {@link resolveGoalRounds}).
  */
-export declare function registerGoalBridge(ctx: Context, resolver: HarnessResolver, config: Config): void;
-export {};
+export declare function registerGoalBridge(ctx: Context, resolver: HarnessResolver): void;

package/dist/gates/plan-mode-bridge.d.ts

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { HarnessResolver } from './_shared.ts';
+import type { SessionHint } from './workflow-selection.ts';
 /** Logger label for the planMode bridge (dsh logger naming: `<scope>/<subject>`). */
 export declare const PLAN_MODE_BRIDGE_LOGGER = "mstar/plan-mode-bridge";
 /** Consumer log levels the module sink understands. */
@@ -27,13 +28,20 @@ export interface PlanModeServiceView {
     set(agent: unknown, active: boolean): unknown;
 }
 /**
- * The planMode target for one harness: `true` iff an active iteration steers
- * (compass `status: active|locked`) AND a Prepare window exists (≥1 plan
- * row `Todo`). No active iteration / no Prepare window → `false` (plan mode
- * OFF — the host default).
+ * The planMode target for one harness + carrying session: `true` iff the
+ * SELECTED lifecycle's own compass still steers (compass `status:
+ * active|locked`, `iteration_id` matching the snapshot) AND the selected
+ * snapshot carries a Prepare window (≥1 plan row `Todo`). Otherwise the
+ * target is OFF.
  * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param hint - the root session's carrying hint (lease / cwd / durable pick).
+ * @returns `true`/`false` for a resolved selection, or `undefined` when this
+ *   session has NO selected lifecycle (unbound multi-active / unreadable
+ *   binding record) — the caller must leave plan mode alone rather than
+ *   fabricate `false`, which would assert a state for a workflow the session
+ *   never selected.
  */
-export declare function planModeTarget(harnessDir: string): boolean;
+export declare function planModeTarget(harnessDir: string, hint?: SessionHint): boolean | undefined;
 /** Inputs of the sync: the structural planMode view and the per-workspace resolver. */
 export interface PlanModeSyncInput {
     resolver: HarnessResolver;
@@ -43,11 +51,12 @@ export interface PlanModeSyncInput {
 /**
  * Mirror the harness Prepare state into the planMode selection of ONE agent:
  * root-like agent (`header.parentSession === undefined`) → resolve the
- * workspace → compute {@link planModeTarget} → `planMode.set(agent, target)`.
- * The service's `'noop'` return makes repeated evaluation at multiple
- * decision points churn-free (no new `plan/mode` event when already in
- * target). Non-root agent / unresolvable harness / missing planMode service
- * → no set.
+ * workspace → compute {@link planModeTarget} from THAT root session's selected
+ * lifecycle → `planMode.set(agent, target)`. The service's `'noop'` return
+ * makes repeated evaluation at multiple decision points churn-free (no new
+ * `plan/mode` event when already in target). Non-root agent / unresolvable
+ * harness / missing planMode service / an UNBOUND session (no selected
+ * lifecycle) → no set.
  *
  * @returns `true` when the sync ran for this agent (set called); `false`
  * when not applicable or a contained failure occurred. Never throws — the
@@ -57,7 +66,7 @@ export declare function syncPlanMode(agent: unknown, input: PlanModeSyncInput):
 /**
  * Register the planMode bridge: an `agent/session-start` listener (root
  * filter inside — root and children alike fire, `runtime-types.ts:217`) plus
- * the EXISTING `subagent/start` decision point (the goal-bridge precedent),
+ * the EXISTING `subagent/start` decision point,
  * resolving the delegating ROOT via the shared `parentSession` walk — the
  * two edges are idempotent (`'noop'` when already in target — no churn). The
  * planMode service is an OPTIONAL seam (`ctx.get('planMode')` structural

package/dist/gates/role-persona.d.ts

@@ -228,6 +228,22 @@ export declare function setRolePersonaAgentsDir(dir: string | undefined): string
  * applying fiber — an HMR fiber swap unwinds it (reads return the raw
  * service again) and a re-apply restores it.
  *
+ * Composition-order independence (`prepend`): the SAME seam is wrapped by a
+ * mounted role-identity layer (`dsh-llm-fallbacks` — its dispatch seam resolves
+ * the Assignment's declared role and merges that role's declared `persona`),
+ * and BOTH wrappers fill the SAME native `persona` slot, each only when it is
+ * free — so whichever wrapper runs FIRST owns the slot. A waterfall runs
+ * listeners outermost-first, and `prepend` registers this one at the front,
+ * so the harness channel is outermost on ANY row order: the default profile
+ * mounts the mstar row first, while a re-ordered profile (or a re-applied
+ * plugin row) mounts it last. The operator's `rolePersonas` override — the
+ * harness's authoritative role identity for a role it resolves — therefore
+ * wins the slot over a fallbacks-side persona for the same role instead of
+ * losing it to whichever layer happened to apply first. A role the harness
+ * resolves NOTHING for still falls through to the fallbacks seam (the
+ * outermost wrapper delegates the caller's own request object on every skip
+ * path), and reads of every other service are returned untouched.
+ *
  * Never throws: the wrap step is contained — on any internal error the read
  * returns the UNWRAPPED service value (persona delivery degrades, the
  * runtime is untouched).

package/dist/gates/steering.d.ts

@@ -0,0 +1,41 @@
+/** The `agents` service surface the `subagent/start` root walk reads. */
+interface AgentsView {
+    get(id: string): unknown;
+}
+/**
+ * Root-agent discriminator (the root filter the planMode bridge decides on):
+ * `header.parentSession === undefined` ⇒ root-like. Conversation forks also
+ * carry `parentSession` (seed lineage) → conservatively excluded (accepted
+ * boundary).
+ */
+export declare function isRootLikeAgent(agent: unknown): boolean;
+/**
+ * Resolve the ROOT agent of a published child via the `parentSession` walk
+ * (upstream `subagent/src/continuation.ts:819-831` precedent): in-process
+ * subagent children stamp `header.parentSession` = the parent SESSION id,
+ * which IS the parent agent id (a session per agent); the walk stops at the
+ * first root-like ancestor. `undefined` when unresolvable (fork lineage,
+ * non-in-process provider, registry gap, or a cycle) — the decision point
+ * then silently skips. Cycle guard: a `seen` set over visited session ids
+ * (the upstream `liveLineage` guard) breaks on ANY revisited id — a 1-hop self-loop, a 2+ hop cycle
+ * (A→B→A), or a longer malformed lineage — instead of spinning forever on
+ * the synchronous `subagent/start` decision-point listeners (reachable via
+ * HMR remounts, resumed/forked sessions with stale headers, or a future
+ * host change). The same `subagent/start` decision-point root walk the
+ * planMode bridge consumes.
+ */
+export declare function rootAgentOf(agent: unknown, agents: AgentsView): unknown | undefined;
+/**
+ * Locate the steering iteration compass (mirror of the engine's
+ * `resolveCompassEnforcement` scan + the catalog's `steeringCompassPath`):
+ * the FIRST `{ITERATION_DIR}/<id>/delivery-compass.md` whose frontmatter
+ * `status` is `active` or `locked` — the directory name IS the iteration id
+ * (plan-conventions `{ITERATION_DIR}/<id>/`). Completed/status-less/archived
+ * compasses do not steer. Silent on any read failure (advisory degrade).
+ * The same "is an active iteration steering" read the planMode bridge consumes.
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ */
+export declare function steeringCompass(harnessDir: string): {
+    iterationId: string;
+} | undefined;
+export {};

package/dist/gates/workflow-ledger.d.ts

@@ -4,11 +4,16 @@
  * into the CALLING PARENT session's log (top-level runs only — nested
  * transport calls record nothing upstream; Task 1 seam notes §4). The
  * consumer has THREE halves (the architect-verified seam):
- *  1. COLD SCAN at apply — iterate `ctx.get('sessions').list()`, read each
- *     session's `events` snapshot, and record any `tool-workflow/*` rows
+ *  1. COLD SCAN at apply — iterate `ctx.get('sessions').list()`, walk each
+ *     session's log through the installed `seq` + `eventAt(seq)` surface
+ *     (never a whole-log copy), and record any `tool-workflow/*` rows
  *     already present. Constructor-seeded events (replay/resume/fork) NEVER
  *     publish on the `session/event` firehose (`firstLiveSeq`), so without
- *     the cold scan pre-restart runs would be invisible.
+ *     the cold scan pre-restart runs would be invisible. A forked
+ *     conversation's INHERITED prefix (`Session.inheritedEventCount`) is
+ *     never part of that walk: those envelopes are the fork PARENT's rows,
+ *     so a child records only its own events (never a second copy of the
+ *     parent's rows, attributed to the child, in the same workflow dir).
  *  2. LIVE FIREHOSE — `ctx.events.on('session/event', …)`: the post-commit
  *     append feed, delivered to ALL sessions for a root-context listener
  *     (scope-null event, untagged listeners admitted).
@@ -80,6 +85,28 @@
  * record degrades the observation with one warn — the ledger row is already
  * appended, the run is never affected.
  *
+ * D4 session binding: every row is attributed to the lifecycle the CARRYING
+ * session is bound to — its durable picker record (`session.header.id` +
+ * exact cwd) folded into the structural hint the shared write resolver
+ * consumes — and the record's durable `excludedBeforeSeq` is an intentional
+ * EXCLUSION floor: rows the session observed while unbound (below a pick) are
+ * never replayed, including after a restart. Rows observed while unbound are
+ * not written anywhere; their next seq is persisted as the floor (with zero
+ * workflow-dir writes) so the later pick cannot backfill them. An unreadable
+ * binding record pauses attribution for that session (no write, no floor,
+ * row re-evaluated next scan) — an unverifiable record is never treated as
+ * "no pick".
+ *
+ * The hint ALSO carries the session's VERIFIED live lease holder, read at
+ * this edge from the `agents` service (`ctx.get('agents')` → `get(sessionId)`
+ * → the shared {@link verifiedLeaseHolderOf} check). The dispatch gate
+ * forwards the same identity, so a session whose lifecycle is only decidable
+ * by its lease (two active lifecycles sharing one `control_worktree_path`)
+ * records its rows under the lifecycle whose lease authorized the dispatch
+ * instead of resolving unbound and excluding them permanently. A cold/resumed
+ * session with no live Agent carries no holder — the hint then falls back to
+ * the picker identity, exactly as before.
+ *
  * Observe-only (plan Global Constraints: W3 / N5): ZERO gating — every read
  * and append is try/catch-contained; a throwing session read logs one warn
  * and the run is unaffected; all appends go through `recordWorkflowEvent`
@@ -184,7 +211,7 @@ export declare function advanceWatermark(workflowDir: string, sid: string, nextS
  * Register the workflow-ledger consumer: (1) a `session/created` backfill
  * listener (registered FIRST — — so no apply-time window exists
  * between the snapshot and the attach); (2) a bounded cold scan over
- * `ctx.sessions.list()` reading each session's `events` snapshot for
+ * `ctx.sessions.list()` walking each session's `seq` + `eventAt(seq)` log for
  * `tool-workflow/*` rows (covers pre-restart runs — constructor-seeded
  * events never hit the firehose, `firstLiveSeq`); (3) a live
  * `ctx.events.on('session/event', …)` listener filtering the four types.

package/dist/gates/workflow-selection.d.ts

@@ -1,6 +1,21 @@
 import type { WorkflowSelectionView } from '../types.ts';
-/** The active-set resolver result: the first active lifecycle or a clear error. */
+/** The active-set resolver result: the session's active lifecycle or a clear error. */
 export type ActiveWorkflowSelection = WorkflowSelectionView;
+/**
+ * What the carrying session can tell the resolver (structural — no
+ * dsh-session import, so cold/raw Session consumers can build one too).
+ * `sessionId` is the durable picker key (`session.header.id`), NEVER a
+ * holder fallback; `leaseHolder` is the dispatching dsh `Agent.id` when an
+ * Agent exists; `selectedWorkflowId` is the session's durable pick (loaded
+ * by the caller from the engine-status store). Every field is optional —
+ * an omitted hint just misses the corresponding rung.
+ */
+export interface SessionHint {
+    cwd?: string;
+    sessionId?: string;
+    leaseHolder?: string;
+    selectedWorkflowId?: string;
+}
 /**
  * Test-only observability hook :
  * whether a snapshot path is still cached. Production code never calls
@@ -9,30 +24,36 @@ export type ActiveWorkflowSelection = WorkflowSelectionView;
  */
 export declare function _terminalStatusCacheHas(snapshotPath: string): boolean;
 /**
- * Resolve the ACTIVE lifecycle set (root v2 `status.json` `workflows[]` —
- * the list holds non-terminal lifecycles only, removal-at-terminal). This
- * is the ONLY resolver the agent-flow writer / ledger may use: no active
- * entry → a clear error, never a terminal snapshot and never the root v1
- * file.
+ * Resolve the ACTIVE lifecycle this session writes under (root v2
+ * `status.json` `workflows[]` — the list holds non-terminal lifecycles
+ * only, removal-at-terminal). This is the ONLY resolver the agent-flow
+ * writer / ledger may use: no bound entry → a clear error, never a terminal
+ * snapshot, never the root v1 file, and never the registry's first entry.
  *
- * Active-set definition (explicit decision,
- * membership in `workflows[]` — the engine lifecycle enum's
- * non-terminal states are `running` AND `paused` (terminal lifecycles are
- * removed from the list at terminal). A PAUSED lifecycle therefore stays in
- * the active set and the agent-flow writer / ledger append to its workflow
- * dir (a paused lifecycle is still the operator's current lifecycle — its
- * ledger must keep recording; only a TERMINAL lifecycle is never a write
- * target).
+ * EVERY registry entry is validated before N or the candidates are exposed:
+ * the engine `validateWorkflowEntry` contract (`id`/`type`/`started_at` and a
+ * harness-relative `dir` with no absolute path or `..` segment) plus
+ * duplicate-id rejection. A bad row is an error, not a smaller active set —
+ * and never a path the resolver would read outside the harness. Only a real
+ * empty array is `workflow.selection.no-active`. Active-set definition:
+ * membership in `workflows[]` — the engine lifecycle enum's non-terminal
+ * states are `running` AND `paused`, so a PAUSED lifecycle stays in the
+ * active set (it is still the operator's current lifecycle; only a TERMINAL
+ * lifecycle is never a write target).
  * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param hint - the carrying session's structural identity, when it has one
+ *   (omitted ⇒ the automatic rungs and the durable pick miss; unique-active
+ *   still works).
  */
-export declare function resolveActiveWorkflow(harnessDir: string): ActiveWorkflowSelection;
+export declare function resolveActiveWorkflow(harnessDir: string, hint?: SessionHint): ActiveWorkflowSelection;
 /**
  * Resolve the workflow the catalog/panel READ path aggregates (compass
- * v3.0.0 § Catalog selection rule): active `workflows[]` first (multiple
- * active → first + a structured warning), else the latest terminal
- * snapshot by mtime (history view), else a clear error. Never reads the
+ * v3.0.0 § Catalog selection rule): the SAME binding order as the write
+ * path, else the latest terminal snapshot by mtime (history view — only
+ * when the active registry is EMPTY), else a clear error. Never reads the
  * root v1 `plans[]` / root `agent-flow.jsonl` as primary or as a quiet
- * fallback.
+ * fallback, and never substitutes history for an unbound active set.
  * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param hint - forwarded verbatim to the active-set resolver.
  */
-export declare function resolveReadWorkflow(harnessDir: string): WorkflowSelectionView;
+export declare function resolveReadWorkflow(harnessDir: string, hint?: SessionHint): WorkflowSelectionView;