@mstar-harness/dsh 3.8.0 → 3.8.2

package/dist/engine-status-endpoint.d.ts

@@ -20,8 +20,9 @@
  * HARD constraint — headless boot safety: this module is reachable from
  * `apply`, and it must never make the host row statically inject `connection`
  * or `webServer`. Everything web-only is inside the optional inject child; the
- * endpoint's own reads (`ctx.get('sessions')`, `ctx.get('sessionController')`)
- * are structural and degrade when the service is absent.
+ * endpoint's own reads (`ctx.get('sessions')`, `ctx.get('agents')`,
+ * `ctx.get('sessionController')`) are structural and degrade when the service
+ * is absent.
  *
  * VALIDATION CHAIN — the endpoint serves ONE session's snapshot and answers
  * otherwise. In order:
@@ -37,14 +38,33 @@
  * another session's data, never a silently-close match, never a path built from
  * unvalidated input.
  *
+ * The response additionally carries the session's CURRENT control-state
+ * selection (`binding.selection`, D4) — server-resolved from the durable
+ * picker record + the verified live Agent — so the panel can show the chosen
+ * active id while `payload` / `at` / `turn` keep naming the LAST MODEL
+ * EMISSION. The `selectWorkflow` UI control (D4) is the write half: a LIVE
+ * session, an exact cwd, an ACTIVE workflow id, automatic-binding compatibility
+ * and a bounded session sequence are mandatory before the durable pick is
+ * committed.
+ *
  * @module @mstar-harness/dsh/engine-status-endpoint
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { HarnessResolver } from './gates/_shared.ts';
-import { MSTAR_ENGINE_STATUS_METHOD, MSTAR_ENGINE_STATUS_NAMESPACE } from './engine-status-wire.ts';
-export { MSTAR_ENGINE_STATUS_METHOD, MSTAR_ENGINE_STATUS_NAMESPACE };
+import type { WorkflowSelectionView } from './types.ts';
+import { type HarnessResolver } from './gates/_shared.ts';
+import { MSTAR_ENGINE_STATUS_METHOD, MSTAR_ENGINE_STATUS_NAMESPACE, MSTAR_SELECT_WORKFLOW_METHOD } from './engine-status-wire.ts';
+export { MSTAR_ENGINE_STATUS_METHOD, MSTAR_ENGINE_STATUS_NAMESPACE, MSTAR_SELECT_WORKFLOW_METHOD };
+/**
+ * The session's CURRENT control state (D4): the selection the server resolves
+ * for the session it just validated — the durable picker record folded with
+ * the verified live Agent's lease holder. Deliberately SEPARATE from
+ * `payload` / `at` / `turn`, which keep naming the last model emission.
+ */
+export interface MstarEngineStatusBinding {
+    readonly selection: WorkflowSelectionView;
+}
 /** The served snapshot (the stored emission, echoed back with its identity). */
 export interface MstarEngineStatusOk {
     readonly status: 'ok';
@@ -56,6 +76,8 @@ export interface MstarEngineStatusOk {
     readonly turn: number;
     /** The exact catalog payload emitted to that session's model. */
     readonly payload: Record<string, unknown>;
+    /** Current control-state selection for this session (never the last emission's). */
+    readonly binding?: MstarEngineStatusBinding;
 }
 /**
  * The explicit "no answer" result. `reason` is machine-readable and always
@@ -67,12 +89,27 @@ export interface MstarEngineStatusUnavailableResult {
 }
 /** The endpoint's wire result. */
 export type MstarEngineStatusResult = MstarEngineStatusOk | MstarEngineStatusUnavailableResult;
+/** The picker commit result: the durable preference was acknowledged. */
+export interface MstarSelectWorkflowOk {
+    readonly status: 'selected';
+    readonly sessionId: string;
+    readonly workflowId: string;
+}
+/** The `selectWorkflow` UI control's wire result. */
+export type MstarSelectWorkflowResult = MstarSelectWorkflowOk | MstarEngineStatusUnavailableResult;
 /** Options the endpoint needs from the plugin's apply scope. */
 export interface MstarEngineStatusEndpointOptions {
     /** The per-workspace `{HARNESS_DIR}` resolver (the same one the gates use). */
     readonly resolver: HarnessResolver;
     /** The boot-resolved config root when an explicit `harnessDir` is configured. */
     readonly bootHarnessDir: string | null;
+    /**
+     * A picker commit landed for `(harnessDir, sessionId)`: drop that session's
+     * cached catalog payload + re-emission digest so the next pre-step rebuilds
+     * from the acknowledged binding. Optional (a host without the catalog wiring
+     * still serves the control method); a throwing hook is contained.
+     */
+    readonly invalidateSelection?: (harnessDir: string, sessionId: string) => void;
 }
 /**
  * Host-side `mstar/engineStatus` service: `/api/mstar/engineStatus` serves the
@@ -81,9 +118,10 @@ export interface MstarEngineStatusEndpointOptions {
 export declare class MstarEngineStatusGateway extends TypertRemoteService {
     private readonly resolver;
     private readonly bootHarnessDir;
+    private readonly invalidateSelection;
     /**
      * @param ctx - owning Cordis context.
-     * @param options - the apply-scoped resolver + boot root.
+     * @param options - the apply-scoped resolver + boot root (+ pick invalidation hook).
      */
     constructor(ctx: Context, options: MstarEngineStatusEndpointOptions);
     /**
@@ -91,11 +129,48 @@ export declare class MstarEngineStatusGateway extends TypertRemoteService {
      * chain documented in the module header.
      * @param sessionId - the session whose snapshot is requested (client-asserted).
      * @param cwd - the session workspace the client believes it is reading (client-asserted).
-     * @returns the stored emission, or the explicit unavailable state with a reason.
+     * @returns the stored emission plus the session's current control-state
+     *   selection, or the explicit unavailable state with a reason.
      */
     engineStatus(sessionId: string, cwd: string): Promise<MstarEngineStatusResult>;
+    /**
+     * Commit one session's durable workflow selection (the panel's picker).
+     *
+     * Mandatory before the commit: the LIVE Session (a cold/persisted-only
+     * target answers `session-not-live`), an exact cwd match, a bounded integer
+     * session sequence, an ACTIVE workflow id from the freshly resolved
+     * registry, and no conflicting higher-priority automatic (lease/cwd)
+     * binding. The exclusion floor commits as `max(stored, seq)`. An identical
+     * already-stored active pick is acknowledged WITHOUT advancing the floor.
+     * No client-supplied directory, holder or sequence is accepted.
+     * @param sessionId - the session whose selection is committed (client-asserted).
+     * @param cwd - the session workspace the client asserts (must match the live session).
+     * @param workflowId - the chosen ACTIVE lifecycle id.
+     * @returns the acknowledgement, or the explicit unavailable state with a reason.
+     */
+    selectWorkflow(sessionId: string, cwd: string, workflowId: string): Promise<MstarSelectWorkflowResult>;
     /** The validation chain itself (contained by {@link engineStatus}). */
     private serve;
+    /** The picker commit chain itself (contained by {@link selectWorkflow}). */
+    private pick;
+    /**
+     * The session's CURRENT selection: the durable picker record folded with the
+     * session's structural identity and — for a LIVE session — the verified live
+     * Agent's opaque id as the lease holder. An unreadable binding record keeps
+     * the structural hint only (the pick is unknown, never invented), and the
+     * request's `sessionId` is NEVER substituted for the holder.
+     */
+    private currentSelection;
+    /**
+     * The opaque lease-holder `Agent.id` of the session's live Agent, when the
+     * public agents service resolves one whose own session header identifies the
+     * resolved Session (id AND cwd). Absent/mismatching Agent ⇒ undefined — the
+     * request's `sessionId` is never used as a holder shortcut. The verification
+     * itself is SHARED ({@link verifiedLeaseHolderOf}) with the other
+     * session-level hint builders (the workflow ledger), so a lease-bound
+     * session resolves the same lifecycle on every path.
+     */
+    private leaseHolderOf;
     /**
      * Resolve the authoritative cwd of one session: the LIVE session first
      * (`ctx.sessions.get(id)`), then the session controller's persisted
@@ -106,7 +181,9 @@ export declare class MstarEngineStatusGateway extends TypertRemoteService {
     private resolveSessionCwd;
 }
 /**
- * The generated-style invocation descriptor for `/api/mstar/engineStatus`.
+ * The generated-style invocation descriptors for the shared `/api` gateway:
+ * `/api/mstar/engineStatus` (the stored snapshot + current binding) and
+ * `/api/mstar/selectWorkflow` (the panel's durable pick).
  *
  * Registered EXPLICITLY (not through `@Remote` SRC markers): the host gateway
  * checks its own `ctx.typert.local` table FIRST, while SRC discovery reads a

package/dist/engine-status-store.d.ts

@@ -16,10 +16,18 @@
  * ```json
  * {
  *   "sv": 1,
- *   "entries": { "<session id>": [ { "rv": 1, "cwd": "/proj", "at": "…", "turn": 3, "payload": { … } } ] }
+ *   "entries": { "<session id>": [ { "rv": 1, "cwd": "/proj", "at": "…", "turn": 3, "payload": { … } } ] },
+ *   "bindings": { "<session id>": { "cwd": "/proj", "selectedWorkflowId": "wf-2", "excludedBeforeSeq": 12 } }
  * }
  * ```
  *
+ * `entries` is the emission history (what the model saw); `bindings` is the
+ * session-scoped workflow-selection CONTROL state (D4: the picked active
+ * workflow + the durable no-backfill floor). The control map is additive and
+ * optional — a missing map means "no pick / floor 0" — and is never part of an
+ * emitted payload: each writer preserves the other's field verbatim, and the
+ * binding writer never touches `payload` / `at` / `turn`.
+ *
  * `sv` is the envelope schema version and `rv` the per-entry record version:
  * a reader that does not recognize EITHER must answer "unavailable" rather
  * than parse a shape it does not understand — and (write rule below) a writer
@@ -156,6 +164,52 @@ export interface EngineStatusSnapshotWriteInput {
     /** Global byte ceiling override (test seam; production uses the constant). */
     readonly maxBytes?: number;
 }
+/**
+ * One session's durable workflow-selection CONTROL record (D4): the active
+ * workflow this session picked plus the durable no-backfill floor. It lives in
+ * the envelope's optional top-level `bindings` map — never inside an emitted
+ * payload — and is keyed by the durable `session.header.id`.
+ */
+export interface WorkflowSessionBinding {
+    /** The authoritative session cwd the record was written for (exact-match anchor). */
+    readonly cwd: string;
+    /** The session's chosen ACTIVE workflow id; absent = no explicit pick yet. */
+    readonly selectedWorkflowId?: string;
+    /**
+     * Durable exclusion floor: ledger rows at or below this sequence were
+     * intentionally skipped while the session was unbound and must never be
+     * backfilled. An absent record means floor 0 (no exclusion history).
+     */
+    readonly excludedBeforeSeq: number;
+}
+/**
+ * Binding read outcome: the stored record (or its absence as `ok` WITHOUT a
+ * `binding`), or why attribution is unavailable — absent and corrupt are
+ * distinct answers, never a silent empty record.
+ */
+export type WorkflowSessionBindingRead = {
+    readonly kind: 'ok';
+    readonly binding?: WorkflowSessionBinding;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+/** One binding read-modify-write request (a picker commit or a floor advance). */
+export interface WorkflowSessionBindingUpdate {
+    /** The chosen active workflow id; omitted preserves the stored preference. */
+    readonly selectedWorkflowId?: string;
+    /** The exclusion floor to merge (by max) into the stored record. */
+    readonly excludedBeforeSeq: number;
+    /** Global byte ceiling override (test seam; production uses the constant). */
+    readonly maxBytes?: number;
+}
+/** Binding write outcome: written, or the degraded reason (never throws for I/O faults). */
+export type WorkflowSessionBindingWrite = {
+    readonly kind: 'written';
+} | {
+    readonly kind: 'degraded';
+    readonly reason: string;
+};
 /** Absolute snapshot file path for one `{HARNESS_DIR}`. */
 export declare function engineStatusSnapshotPath(harnessDir: string): string;
 /** The explicit unavailable result (single constructor — one shape everywhere). */
@@ -188,3 +242,39 @@ export declare function readEngineStatusSnapshot(harnessDir: string | null, sess
  *   per store — the oversize warning) or the degraded reason.
  */
 export declare function writeEngineStatusSnapshot(harnessDir: string | null, input: EngineStatusSnapshotWriteInput): EngineStatusSnapshotWrite;
+/**
+ * Read one session's durable workflow-selection binding.
+ *
+ * The answers are deliberately distinct: `{kind:'ok'}` WITHOUT a `binding`
+ * means there is nothing recorded for this session (no store yet, an sv=1
+ * envelope without the control map, no key for the session) — the caller
+ * proceeds unbound. `{kind:'unavailable', reason}` means the record cannot be
+ * trusted (`store-unreadable`, `store-invalid-json`, `store-envelope-schema`,
+ * `store-bindings-schema`, `cwd-mismatch`) — the caller must NOT treat that as
+ * "no pick" and attribute the session anywhere.
+ *
+ * The file read + parse is memoized by the file's identity (see
+ * {@link readBindingStoreSnapshot}); only this session's key is re-checked per
+ * call, so the per-tool-call / per-step cost does not scale with the store.
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param sessionId - the durable `session.header.id` (the picker key).
+ * @param cwd - the authoritative session cwd (exact match against the record).
+ */
+export declare function readWorkflowSessionBinding(harnessDir: string, sessionId: string, cwd: string): WorkflowSessionBindingRead;
+/**
+ * Durably record one session's workflow-selection binding (the D4 picker
+ * commit / exclusion-floor advance) — the same read-modify-write discipline as
+ * {@link writeEngineStatusSnapshot}: the snapshot-dir lock, a writer-unique
+ * temp file, an atomic rename, and the refusal rule for a store this build
+ * cannot understand. The emission records (`payload` / `at` / `turn` /
+ * `rv` / `cwd`) are preserved EXACTLY: this write only sets
+ * `bindings[sessionId]`, merges the floor by max, and keeps the stored
+ * preference when the update omits one. A binding that cannot fit the ceiling
+ * is refused rather than paid for by dropping another session's record.
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param sessionId - the durable `session.header.id`.
+ * @param cwd - the authoritative session cwd (must match any stored record).
+ * @param update - the preference (optional) and the exclusion floor.
+ * @returns written, or the degraded reason (never throws for I/O faults).
+ */
+export declare function updateWorkflowSessionBinding(harnessDir: string, sessionId: string, cwd: string, update: WorkflowSessionBindingUpdate): WorkflowSessionBindingWrite;

package/dist/engine-status-wire.d.ts

@@ -27,3 +27,12 @@ export declare const ENGINE_STATUS_ENDPOINT = "mstar/engineStatus";
 export declare const MSTAR_ENGINE_STATUS_NAMESPACE = "mstar";
 /** Wire method of the invocation → `/api/mstar/engineStatus`. */
 export declare const MSTAR_ENGINE_STATUS_METHOD = "engineStatus";
+/**
+ * Wire method of the panel's workflow-selection control → `/api/mstar/selectWorkflow`.
+ * A session-scoped UI control (never a model workflow-execution tool): the
+ * host acknowledges the pick durably and the next `ensure()` reads the
+ * current binding back.
+ */
+export declare const MSTAR_SELECT_WORKFLOW_METHOD = "selectWorkflow";
+/** The endpoint path the client calls for a workflow pick. */
+export declare const SELECT_WORKFLOW_ENDPOINT = "mstar/selectWorkflow";

package/dist/gates/_shared.d.ts

@@ -2,6 +2,7 @@ import z from 'schemastery';
 import type { GateResult, ValidationResult } from '@mstar-harness/engine';
 import type { Config as SkillLocalConfig } from '@deepseek-ai/dsh-skill-filesystem';
 import type { IterationGateListView, IterationGateViolationView } from '../types.ts';
+import type { SessionHint } from './workflow-selection.ts';
 /** Canonical harness status file name (mstar-artifacts status.json). */
 export declare const STATUS_FILE = "status.json";
 /** Plugin configuration. */
@@ -128,15 +129,6 @@ export interface Config {
      * so P-a never applies to them.
      */
     workflowNames?: string[];
-    /**
-     * Goal-bridge round cap : the
-     * flat `maxGoalRounds` the goal bridge passes to the goals service when it
-     * mirrors the active iteration objective (bounds autonomous Phase 2
-     * loops — the service itself throws on resume past the cap). Absent →
-     * 256 (aligned with the GoalService default and ralph `maxRounds` —
-     * architect decision; see the plan).
-     */
-    maxGoalRounds?: number;
 }
 /**
  * dsh system-prompt strict `{{variable}}` interpolation hazard: the renderer
@@ -314,6 +306,66 @@ export declare function sessionCwdOf(agent: unknown): string | undefined;
  * skips the persist instead of inventing a key.
  */
 export declare function sessionHeaderIdOf(agent: unknown): string | undefined;
+/**
+ * The opaque id of one agent — the LEASE-holder identity (`Agent.id`,
+ * structural read). Deliberately distinct from {@link sessionHeaderIdOf}:
+ * the durable picker key is `session.header.id` while a lease's `holder` is
+ * the dispatching agent's own id, and the two are never substituted for one
+ * another (no host-prefix coercion — the resolver compares them opaquely).
+ */
+export declare function agentIdOf(agent: unknown): string | undefined;
+/**
+ * The VERIFIED live lease-holder identity of one session's Agent — the id the
+ * dispatch gate forwards to the shared resolvers for the SAME dispatch
+ * (`sessionHintOf(exec.agent)` → `agentIdOf`). Every consumer of a
+ * session-level hint (the host endpoint's control-state read, the workflow
+ * ledger's attribution) must forward the SAME identity, or a session whose
+ * lifecycle is only decidable by its lease (two active lifecycles sharing one
+ * `control_worktree_path`) resolves differently per call site.
+ *
+ * The handle must BE that session's agent — its own `session.header.id` names
+ * the session, and (when the caller has an authoritative cwd) its workspace
+ * must equal it. Anything else answers `undefined`: the session id is never
+ * substituted for a holder (they are opaque and distinct).
+ * @param agent - the live agent the host resolves for the session (structural read).
+ * @param sessionId - the session the hint is built for.
+ * @param cwd - the session's workspace; `undefined` skips the workspace check
+ *   (a caller with no authoritative cwd cannot verify one).
+ */
+export declare function verifiedLeaseHolderOf(agent: unknown, sessionId: string, cwd: string | undefined): string | undefined;
+/**
+ * The structural session hint one event's agent supplies to the workflow
+ * resolvers (no dsh-session import — cold/raw Session consumers read the same
+ * `header.cwd` / `header.id` directly). `selectedWorkflowId` is deliberately
+ * ABSENT: it is the session's durable binding record, loaded by the
+ * composition edge that owns the store (adapter / catalog / workflow-ledger /
+ * plan-mode bridge) — the pure structural read never fabricates it.
+ * @param agent - the agent an event carries (structural read).
+ * @returns the hint, or `undefined` when the agent carries no session
+ *   identity and no id at all (an exec-less hook) — an OMITTED hint, never a
+ *   fabricated empty one.
+ */
+export declare function sessionHintOf(agent: unknown): SessionHint | undefined;
+/**
+ * One carrying session's selection-hint read: the hint the resolvers consume,
+ * plus whether the session's DURABLE binding could be trusted.
+ *
+ * `ok` without a `hint` = the event carries no session (an exec-less hook) —
+ * the automatic rungs miss and the registry's unique-active case still
+ * resolves. `unavailable` = the binding store could not be read
+ * (corrupt/unreadable/cwd-mismatch), so the caller must NOT attribute a
+ * durable write to this session — an unverifiable record is NOT "no pick",
+ * and must never be replaced by an empty hint that would silently attribute
+ * the write to whichever lifecycle happens to resolve.
+ */
+export type SessionHintRead = {
+    readonly kind: 'ok';
+    readonly hint?: SessionHint;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+    readonly hint?: SessionHint;
+};
 /** The tool-execution actor of one fs-intent event, when it carries an agent. */
 export declare function actorAgentOf(actor: object | undefined): unknown;
 /**

package/dist/gates/adapter.d.ts

@@ -1,7 +1,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import type { AssignmentFields, GateResult, HostAdapter, IntegrationMergeLease, ValidationResult } from '@mstar-harness/engine';
 import type { ToolExecution } from '@deepseek-ai/dsh-tools';
-import type { HarnessResolver, Config } from './_shared.ts';
+import type { HarnessResolver, Config, SessionHintRead } from './_shared.ts';
 import { type HarnessDocKind } from './status.ts';
 import type { AgentFlowPairing, WorkflowVerdictInput } from './agent-flow.ts';
 import { WorkflowAskCache } from './workflow-policy.ts';
@@ -109,6 +109,33 @@ export declare class DshHostAdapter extends Service implements HostAdapter {
      * cleanup extension needs it to locate the project registers).
      */
     statusGate(path: string, kind: HarnessDocKind, harnessDir: string | null): GateResult;
+    /**
+     * Derive the carrying session's workflow-selection hint for one event
+     * (D4): the structural identity read off the agent (`session.header.cwd` /
+     * `session.header.id` plus the agent's own opaque id as the lease holder)
+     * folded with this session's DURABLE binding preference from the
+     * engine-status store. Both gate reads and ledger writes route through
+     * this ONE derivation, so a session is attributed consistently within a
+     * single decision.
+     *
+     * The store is the plugin's only durable picker state, and it is read at
+     * THIS composition edge: `dispatch.ts` (and the writers in `agent-flow.ts`)
+     * receive plain hints and never touch the store — no circular
+     * `agent-flow → store → agent-flow` import.
+     *
+     * Degrades honestly, never with a fabricated hint:
+     * - no session at all (exec-less hook / agent stub) → `ok` without a hint,
+     *   so the automatic rungs miss and only a unique active lifecycle
+     *   resolves;
+     * - a session without both id AND cwd → `ok` with what IS known (the
+     *   lease/cwd rungs and the unique-active case still work — only the
+     *   durable pick needs the session key);
+     * - an unreadable/refused/cwd-mismatched binding record → `unavailable`
+     *   (reported once through the adapter's log), so the callers keep the
+     *   structural evidence for GATE validation but write no ledger row.
+     * @param agent - the event's agent (`exec.agent`), structural read.
+     */
+    sessionHintFor(agent: unknown): SessionHintRead;
     /**
      * Shared dispatch-gate core (plugin-internal): the `tools/pre-execute`
      * listener and `beforeDispatch` route through this method — ONE
@@ -122,8 +149,11 @@ export declare class DshHostAdapter extends Service implements HostAdapter {
      * @param hard - the caller's ONE `resolveDispatchHard` resolution): passed in so the record block and
      * the caller's enforcement decision share a single compass resolution;
      * when omitted (external callers) the adapter resolves it itself.
+     * @param hintRead - the caller's already-derived hint read (the
+     * `tools/pre-execute` listener derives it once and shares it with the
+     * workflow branch); omitted → derived here from `exec.agent`.
      */
-    dispatchGate(prompt: string, exec?: ToolExecution, hard?: boolean): GateResult;
+    dispatchGate(prompt: string, exec?: ToolExecution, hard?: boolean, hintRead?: SessionHintRead): GateResult;
     /**
      * Record one workflow/ralph gate verdict row (plan
      *   Task 4 — the durable ledger row for every