@try-works/dsh-recursive-mode 0.3.1 → 0.4.0

package/lib/enforcement.d.ts

@@ -1,32 +1,121 @@
+import { builtInToolPolicyDefault, type ToolPolicy } from './policy-globs.ts';
+/**
+ * The BUILT-IN default rule list (T16) is defined in `src/policy-globs.ts`,
+ * beside the evaluator and the loader that use it as the ABSENT-file fallback,
+ * and re-exported here because it is part of the guard's documented behaviour.
+ * (It cannot live in a module of its own: the list needs the loader's predicate
+ * contract and the loader needs the list, which as two modules is a value-level
+ * import cycle — the very thing that made a top-level wiring call throw.)
+ */
+export declare const builtInToolPolicy: typeof builtInToolPolicyDefault;
 export type EnforcementMode = 'strict' | 'advisory';
+/**
+ * T28 — the budgets. Every unbounded loop and every unbounded result gets a named,
+ * configurable cap, because a bound that is not named cannot be reviewed and a bound
+ * that is not configurable gets hardcoded per call site (which is exactly what
+ * happened to `maxDepth`).
+ */
+export interface BudgetConfig {
+    /** Rounds ONE phase's audit loop may run, even when every round makes progress. */
+    maxAuditRounds: number;
+    /**
+     * How many times a phase may be sent back for repair. Distinct from T20's
+     * no-progress bound: that one stops a loop REPEATING a finding, this one bounds a
+     * loop that keeps finding genuinely NEW things — the case the no-progress bound
+     * deliberately lets run.
+     */
+    maxRepairAttempts: number;
+    /** The ceiling for the WHOLE recursion, not a fresh allowance at each level. */
+    maxDelegationDepth: number;
+    /** Delegated children one phase may start. */
+    maxChildrenPerPhase: number;
+    /** Byte ceiling for one tool result. T24's caps bound the COUNT of findings; a few enormous findings need this. */
+    maxResultBytes: number;
+}
+export declare const DEFAULT_BUDGETS: BudgetConfig;
 export interface EnforcementConfig {
     preStep: EnforcementMode;
     toolGuards: EnforcementMode;
     tamper: EnforcementMode;
+    /** T28: the caps. Always present, so a caller never has to guess a default. */
+    budgets: BudgetConfig;
 }
-/** Validate the enforcement config shape (unknown keys fail at plugin load). */
+/**
+ * Validate the enforcement config shape (unknown keys fail at plugin load).
+ *
+ * A budget must be a POSITIVE INTEGER. Zero and negatives are rejected rather than
+ * coerced: `0` would mean "never allowed", which bricks the phase it was meant to
+ * bound, and a negative would read as already-exceeded everywhere it is compared.
+ * A config error is loud at load, not mysterious later.
+ */
 export declare function resolveEnforcementConfig(config: unknown): EnforcementConfig;
 export declare const DEFAULT_ENFORCEMENT: EnforcementConfig;
+/**
+ * T15: the rule that produced a guard decision (a machine-readable reason for
+ * every allow/deny/ask the guard hands back). `'none'` means no guard predicate
+ * fired; `'transition'` marks a decision whose only dissenting gate was the
+ * advisory transition gate (see consultTransitionGate).
+ */
+export type GuardRule = 'lock-order' | 'tdd-evidence' | 'locked-write' | 'transition' | 'none';
+/** T15: the transition gate's verdict as attached to a decision (advisory only). */
+export interface GuardTransition {
+    passed: boolean;
+    failures: string[];
+}
 /**
  * Layer 2 - tools/pre-execute guard decision.
  * Pure predicate: inspects the pending tool execution (name + args) against
  * the run tree under the given worktree root.
+ *
+ * T15: `rule` and `transition` are OPTIONAL and additive. They must stay
+ * optional — `coerceAskToDecision` is asserted with `toEqual({ kind: ... })`
+ * (an EXACT match) in tests/enforcement.spec.ts, so the coercion path may never
+ * grow extra keys. `evaluateToolGuard` itself always sets `rule`.
  */
 export type ToolGuardDecision = {
     kind: 'allow';
     warn?: string;
+    rule?: GuardRule;
+    transition?: GuardTransition;
 } | {
     kind: 'deny';
     reason: string;
+    rule?: GuardRule;
+    transition?: GuardTransition;
 } | {
     kind: 'ask';
     reason?: string;
+    rule?: GuardRule;
+    transition?: GuardTransition;
 };
 export interface ToolExecLike {
     name: string;
     arguments?: unknown;
     agent?: unknown;
 }
+/**
+ * The BUILT-IN default rule list (T16) is defined in `src/policy-globs.ts`,
+ * beside the evaluator and the loader that use it as the ABSENT-file fallback,
+ * and re-exported here because it is part of the guard's documented behaviour.
+ * (It cannot live in a module of its own: the list needs the loader's predicate
+ * contract and the loader needs the list, which as two modules is a value-level
+ * import cycle — the very thing that made a top-level wiring call throw.)
+ */
+/**
+ * The policy in force for one guard call: the worktree's policy file when
+ * present (a broken file fails closed), the built-in list when absent, plus the
+ * current phase's narrowing baseline. Exported so a reviewer — and
+ * `recursive:policy` later — can read the effective rules instead of inferring
+ * them from a code path.
+ */
+export declare function resolveToolPolicyForGuard(worktreeRoot: string, runId: string): ToolPolicy;
+/**
+ * The artifact whose phase baseline applies: the HIGHEST-numbered phase artifact
+ * present in the run (a run at phase 3 has `00`-`03` on disk). Read from the
+ * filesystem on every call — the same no-cache discipline the active run id
+ * needs, because a cached phase would apply yesterday's baseline to today's lock.
+ */
+export declare function currentPhaseArtifact(worktreeRoot: string, runId: string): string;
 export declare function evaluateToolGuard(exec: ToolExecLike, worktreeRoot: string, activeRunId: string, mode?: EnforcementMode): ToolGuardDecision;
 /**
  * T6 (approval ask→policy bridge): an `ask` decision must never be a silent

package/lib/errors.d.ts

@@ -0,0 +1,168 @@
+/**
+ * T24 — stable, greppable, self-sufficient tool errors.
+ *
+ * WHY PROSE AND NOT A JSON ENVELOPE. A structured error envelope reaches the
+ * model double-escaped and is materially harder to read than a sentence, and a
+ * model that cannot read a refusal cannot correct it. So every error here
+ * renders as ONE sentence:
+ *
+ *     <code> <class>: <problem>[ - <detail>]. Next: <the exact call that resolves it>.
+ *
+ * The leading `<code> <class>` pair is STABLE and greppable, so a consumer that
+ * is not an LLM — a test, a board badge, a log grep — can branch on it without
+ * parsing prose. The `Next:` clause names a real tool call, because "invalid
+ * input" without a route is a refusal the caller can only guess at.
+ *
+ * Codes are `RM<group><serial>` where the THIRD character is the class group:
+ * 1 input, 2 value, 3 workspace, 4 state, 5 runtime, 6 capability. Because the
+ * group is embedded in the code, a log grep for `RM1` finds every input-shaped
+ * failure without knowing this registry — and `tests/errors.spec.ts` asserts the
+ * third character matches the entry's own class, so the grouping cannot drift.
+ */
+/** What kind of thing went wrong. Stable vocabulary — consumers branch on it. */
+export type ToolErrorClass = 'input' | 'value' | 'workspace' | 'state' | 'runtime' | 'capability';
+export interface ToolErrorSpec {
+    /** Stable `RM<group><serial>` code. Never reuse one for a different problem. */
+    code: string;
+    klass: ToolErrorClass;
+    /** The fixed problem statement, no trailing punctuation. */
+    problem: string;
+    /** What resolves it, naming the exact call. No trailing punctuation. */
+    next: string;
+}
+/**
+ * The registry. Every `recursive_*` tool error must come from here: a tool that
+ * invents its own sentence is a tool whose refusals cannot be grepped, and
+ * `tests/errors.spec.ts` asserts the codes are unique and well formed so the
+ * registry cannot rot into duplicates.
+ */
+export declare const TOOL_ERRORS: {
+    readonly BAD_PROBE_ARGUMENTS: {
+        readonly code: "RM1144";
+        readonly klass: "input";
+        readonly problem: "probeArguments is not a JSON object";
+        readonly next: "pass a JSON object such as {\"artifact\":\"01-as-is.md\"} so the preview can evaluate the guard against real arguments";
+    };
+    readonly BAD_ASK_GATE: {
+        readonly code: "RM1141";
+        readonly klass: "input";
+        readonly problem: "the requested human gate is not one of tdd-mode, qa-signoff or gate-block";
+        readonly next: "call recursive_ask with gate: tdd-mode | qa-signoff | gate-block";
+    };
+    readonly BAD_ASK_ANSWER: {
+        readonly code: "RM1142";
+        readonly klass: "input";
+        readonly problem: "the answer is not one of the labels the gate offered";
+        readonly next: "use one of the labels the ask returned; an unoffered answer reads as a decision while being a transcription error";
+    };
+    readonly MISSING_ASK_ARTIFACT: {
+        readonly code: "RM1143";
+        readonly klass: "input";
+        readonly problem: "this gate has no default artifact, so one must be named";
+        readonly next: "pass artifact: <file> so the answer has somewhere durable to land";
+    };
+    readonly MISSING_RUN_ID: {
+        readonly code: "RM1101";
+        readonly klass: "input";
+        readonly problem: "runId is required";
+        readonly next: "call recursive_status with no runId to see the latest run id in this workspace";
+    };
+    readonly MISSING_ARTIFACT: {
+        readonly code: "RM1102";
+        readonly klass: "input";
+        readonly problem: "artifact is required";
+        readonly next: "call recursive_phase to see which artifact the run is currently on";
+    };
+    readonly MISSING_PHASE_AND_RUN: {
+        readonly code: "RM1103";
+        readonly klass: "input";
+        readonly problem: "phase and runId are required";
+        readonly next: "call recursive_status to read the run id, then pass phase as 04|05|06|07|08";
+    };
+    readonly MISSING_SCRATCH_ARGS: {
+        readonly code: "RM1104";
+        readonly klass: "input";
+        readonly problem: "action, runId and target are all required";
+        readonly next: "call recursive_scratch with action=read|write|append, a runId, and target=md|ts";
+    };
+    readonly MISSING_CREATE_RUN_ID: {
+        readonly code: "RM1105";
+        readonly klass: "input";
+        readonly problem: "runId is required for create";
+        readonly next: "call recursive_init with a runId to scaffold the run first";
+    };
+    readonly MISSING_PROMOTE_BRANCHES: {
+        readonly code: "RM1106";
+        readonly klass: "input";
+        readonly problem: "fromBranch and toBranch are required for promote";
+        readonly next: "call recursive_worktree with action=promote plus fromBranch and toBranch";
+    };
+    readonly BAD_TARGET: {
+        readonly code: "RM2201";
+        readonly klass: "value";
+        readonly problem: "target must be md or ts";
+        readonly next: "pass target=md for /.recursive/run/<id>/scratch/scratch.md or target=ts for scratch.ts";
+    };
+    readonly BAD_ACTION: {
+        readonly code: "RM2202";
+        readonly klass: "value";
+        readonly problem: "action must be create | promote | status";
+        readonly next: "pass action=create, action=promote or action=status";
+    };
+    readonly NO_WORKSPACE: {
+        readonly code: "RM3301";
+        readonly klass: "workspace";
+        readonly problem: "this session is not attached to a registered workspace";
+        readonly next: "open the session inside a workspace directory; the control-plane root is resolved from the session cwd";
+    };
+    readonly NO_RUN: {
+        readonly code: "RM4401";
+        readonly klass: "state";
+        readonly problem: "no recursive run exists in this workspace";
+        readonly next: "call recursive_init with a runId to scaffold the first run";
+    };
+    readonly NO_PHASE: {
+        readonly code: "RM4402";
+        readonly klass: "state";
+        readonly problem: "no current recursive phase could be determined";
+        readonly next: "call recursive_init to scaffold the run, or recursive_status to inspect why every phase is locked";
+    };
+    readonly PENDING_WORK: {
+        readonly code: "RM4403";
+        readonly klass: "state";
+        readonly problem: "the run has unresolved delegated work, so this phase cannot lock yet";
+        readonly next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again";
+    };
+    readonly RUNTIME_REFUSED: {
+        readonly code: "RM5501";
+        readonly klass: "runtime";
+        readonly problem: "the recursive runtime refused the operation";
+        readonly next: "fix the cause named in the detail and retry; a gate refusal names the artifact and its status";
+    };
+    readonly TEAM_SERVICE_UNAVAILABLE: {
+        readonly code: "RM6601";
+        readonly klass: "capability";
+        readonly problem: "the agent-teams service is not available in this composition";
+        readonly next: "use recursive_lock and recursive_lint directly, or mount a composition that provides ctx.agentTeams";
+    };
+};
+export type ToolErrorName = keyof typeof TOOL_ERRORS;
+/**
+ * Render one registry entry as the single sentence a tool returns.
+ * `detail` carries the run-specific part (a run id, an artifact, a gate).
+ */
+export declare function toolError(name: ToolErrorName, detail?: string): string;
+/** True when a string already carries a registry code — used to avoid double-wrapping. */
+export declare function hasToolErrorCode(message: string): boolean;
+/**
+ * Give a thrown runtime message a stable code WITHOUT nesting one that is
+ * already there.
+ *
+ * A refusal the runtime already expressed in this registry's vocabulary (for
+ * example `RM4403` pending work) is passed through untouched: wrapping it would
+ * bury the real code inside `RM5501`'s detail and make the greppable handle
+ * useless, which is the whole reason the registry exists. A bare thrown message
+ * has no code to branch on, so it is wrapped and its sentence survives as the
+ * detail.
+ */
+export declare function codeRuntimeRefusal(message: string): string;

package/lib/git-context.d.ts

@@ -51,3 +51,20 @@ export declare function verifyWorktreeBranch(repoRoot: string, recordedBranch: s
     ok: boolean;
     reason: string | null;
 };
+/**
+ * FU-4 — the paths this checkout has actually changed, for the memory loader's path weighting.
+ *
+ * WHY IT EXISTS. T29's selection weights a shard that names a path the run has changed **above** one that
+ * merely shares wording with the query — but nothing computed those paths, so the weighting was exercised
+ * by tests and never by a run. A weighting that is never fed is a rule that does not exist in production.
+ *
+ * ⚠ IT REUSES `gitRun` AND THE SAME TWO QUERIES `ts-lint.ts` ALREADY USES (`diff --name-only` for tracked
+ * changes, `ls-files --others` for new files). A second way of asking git the same question is a second
+ * thing to get subtly wrong — and the lint path is the one with a parity golden behind it.
+ *
+ * ⚠ IT IS CAPPED, AND IT IS BEST-EFFORT. Uncapped, a large checkout would let path matches swamp the
+ * query score entirely, so the list is capped; and a repo where git fails returns `[]` rather than
+ * throwing, because a memory hint must never be the reason a phase call fails.
+ */
+export declare const MAX_CHANGED_PATHS = 50;
+export declare function changedPaths(repoRoot: string, limit?: number): string[];

package/lib/guard-log.d.ts

@@ -0,0 +1,39 @@
+import type { GuardRule } from './enforcement.ts';
+/**
+ * One logged guard decision (the JSONL record shape the board/tests read).
+ * `rule` is always set (the guard's own machine-readable reason for the
+ * verdict); `transition` is present whenever the transition gate was consulted.
+ */
+export interface GuardDecisionRecord {
+    at: string;
+    runId: string;
+    tool: string;
+    kind: 'allow' | 'deny' | 'ask';
+    rule: GuardRule;
+    reason?: string;
+    transition?: {
+        passed: boolean;
+        failures: string[];
+    };
+}
+/** One logged observed-write tamper (a LOCKED artifact whose hash no longer matches). */
+export interface ObservedTamperRecord {
+    at: string;
+    runId: string;
+    path: string;
+    reason: string;
+}
+/** Newest-N retention cap for both logs (rewrite-on-exceed, never unbounded). */
+export declare const GUARD_LOG_MAX_RECORDS = 500;
+/** The rolling decision log path under the control-plane root. */
+export declare function guardDecisionLogPath(root: string): string;
+/** The rolling observed-tamper log path under the control-plane root. */
+export declare function observedTamperLogPath(root: string): string;
+/** Log one guard decision (allows included — the trace shows what, and why). */
+export declare function appendGuardDecision(root: string, record: GuardDecisionRecord): void;
+/** Log one observed-write tamper. */
+export declare function appendObservedTamper(root: string, record: ObservedTamperRecord): void;
+/** The newest `limit` guard decisions for `root`, newest first. Never throws. */
+export declare function readGuardDecisions(root: string, limit?: number): GuardDecisionRecord[];
+/** The newest `limit` observed tampers for `root`, newest first. Never throws. */
+export declare function readObservedTampers(root: string, limit?: number): ObservedTamperRecord[];

package/lib/handoff.d.ts

@@ -30,6 +30,35 @@ export declare function replyPath(input: {
     delegationId: string;
     childId: string;
 }): string;
+/**
+ * ⚠ FU-17 — THE WORK BRIEF'S SLICE: what a child is told when it is delegated the phase's ACTUAL WORK rather
+ * than a review of it.
+ *
+ * WHY THIS IS SEPARATE FROM THE REVIEWER'S SLICE, and the reason is not tidiness. A reviewer is told what to
+ * look FOR — anti-patterns, a verdict vocabulary, "do not be satisfied by prose". A worker must be told what to
+ * PRODUCE, and above all **the standard its output will be judged against**, because the phase artifact is
+ * linted for required sections and a child that was never told them cannot meet them. That standard already
+ * exists in one place (`getArtifactRequiredSections`), so this composes it rather than restating it — a second
+ * copy would drift from the linter, which is the defect this project has fixed more than once.
+ *
+ * ⚠ IT ALSO TELLS THE CHILD WHO DECIDES. The main agent verifies and records what it accepted
+ * (`## Subagent Contribution Verification`: reviewed action records, main-agent verification performed, an
+ * acceptance decision, refresh handling, repair performed). Saying so up front is not politeness: a child that
+ * believes its own output is final writes a different, worse submission than one that knows a parent will
+ * check it against named sections.
+ */
+export declare function buildWorkSlice(input: {
+    /** The main agent's task for this child, verbatim. */
+    instruction: string;
+    /** The run-relative artifact the work contributes to, e.g. `03-implementation-summary.md`. */
+    artifactFile: string;
+    /** The phase key, for the brief's own traceability back to the run. */
+    phase: string;
+    /** Required sections for that artifact — pass `getArtifactRequiredSections(artifactFile, profile)`. */
+    requiredSections: readonly string[];
+    /** Optional: the phase's lint rules, so the child sees the gate fields too. */
+    lintNotes?: readonly string[];
+}): string;
 /** Child-scoped disposable scratch (Phase B R5, PROPOSAL 10.7). */
 export declare function childScratchPath(input: {
     root: string;

package/lib/hooks.d.ts

@@ -0,0 +1,103 @@
+/** The five named points, mapped onto DSH seams (see the module comment). */
+export declare const HOOK_POINTS: readonly ["pre_turn", "pre_generate", "post_generate", "pre_trigger", "post_trigger"];
+export type HookPoint = (typeof HOOK_POINTS)[number];
+/** What a hook decided. `hold` means "stop and wait", distinct from a refusal. */
+export type HookDecision = 'continue' | 'deny' | 'hold';
+/**
+ * Points that may STOP the work, versus points that only observe it. A deny from an
+ * observing point is downgraded, because the thing it would veto has already happened.
+ */
+export declare const GATING_POINTS: readonly HookPoint[];
+export declare const OBSERVING_POINTS: readonly HookPoint[];
+export declare function isGating(point: HookPoint): boolean;
+export declare function isObserving(point: HookPoint): boolean;
+/** What a hook returns. `void` means "no opinion", i.e. continue. */
+export interface HookOutcome {
+    decision: HookDecision;
+    /** Why — required in spirit for a deny or a hold, and carried verbatim. */
+    reason?: string;
+    /**
+     * What the hook CHANGED or learned, returned rather than mutated in place. Silent
+     * mutation leaves the next reader nothing to find.
+     */
+    annotations?: Record<string, unknown>;
+}
+export interface HookRunContext {
+    readonly point: HookPoint;
+    /** The binding's own deadline in ms, so a hook can bail before it is cut off. */
+    readonly timeoutMs: number;
+    /** Monotonic-ish clock from the registry, for a hook that wants to time itself. */
+    readonly now: () => number;
+}
+export interface Hook<I = unknown> {
+    /** Stable name: it is what the audit trail and the board show. */
+    readonly name: string;
+    /**
+     * Higher runs FIRST. Ties break by REGISTRATION ORDER, which is what makes the
+     * chain reproducible — an ordering that depends on object key order or on
+     * scheduling is an ordering nobody can reason about.
+     */
+    readonly priority: number;
+    /** Per-binding deadline; falls back to the point's default. */
+    readonly timeoutMs?: number;
+    /**
+     * What to do when this hook throws or times out. Defaults by POINT: fail_closed on
+     * a gating point, fail_open on an observing one.
+     */
+    readonly onError?: 'fail_closed' | 'fail_open';
+    readonly run: (input: I, context: HookRunContext) => HookOutcome | void | Promise<HookOutcome | void>;
+}
+/** One hook's contribution to a chain run — the audit trail. */
+export interface HookRunRecord {
+    name: string;
+    decision: HookDecision;
+    durationMs: number;
+    /** Present when the hook failed or timed out; the chain's policy decided what next. */
+    error?: string;
+    annotations?: Record<string, unknown>;
+    /** True when the hook's own decision was overridden (an observing point denying). */
+    downgraded?: boolean;
+}
+export interface HookChainResult {
+    point: HookPoint;
+    decision: HookDecision;
+    reason?: string;
+    /** Every hook that ran, in order; hooks after a short-circuit are absent by design. */
+    ran: HookRunRecord[];
+}
+/** Registry configuration: per-point deadlines. */
+export interface HookRegistryOptions {
+    /** Default deadline per point when a binding does not set one. */
+    timeoutMs?: Partial<Record<HookPoint, number>>;
+    /** Clock injection, so a test can drive timeouts without sleeping. */
+    now?: () => number;
+}
+export interface HookRegistry {
+    readonly points: readonly HookPoint[];
+    /** Register one hook. Returns a disposer, so a sibling can withdraw cleanly. */
+    register<I>(point: HookPoint, hook: Hook<I>): () => void;
+    /** Run the chain for a point. Never throws: failure policy decides the outcome. */
+    run<I>(point: HookPoint, input: I): Promise<HookChainResult>;
+    /** The registered chain, in execution order — what the board would show. */
+    list(point?: HookPoint): Array<{
+        point: HookPoint;
+        name: string;
+        priority: number;
+        onError: 'fail_closed' | 'fail_open';
+        timeoutMs: number;
+    }>;
+    clear(point?: HookPoint): void;
+}
+/**
+ * Build a registry. `now` is injectable so a timeout is testable without waiting for
+ * one: real deadlines in a test are a flake waiting to happen, which this codebase has
+ * already paid for once.
+ */
+export declare function createHookRegistry(options?: HookRegistryOptions): HookRegistry;
+/** A stable fingerprint of one hook binding, for a board that lists the chain. */
+export declare function hookFingerprint(entry: {
+    point: HookPoint;
+    name: string;
+    priority: number;
+    onError: string;
+}): string;

package/lib/identity.d.ts

@@ -0,0 +1,61 @@
+/** Canonical forms at or below this size are inlined into the key; larger ones are digested. */
+export declare const INLINE_LIMIT_BYTES = 2048;
+/**
+ * Canonical JSON for an input: object keys sorted at every depth, arrays in order.
+ * Throws for input with no honest canonical form (a lone surrogate, a non-finite
+ * number, `undefined`) rather than silently substituting something hashable.
+ */
+export declare function canonicalInput(value: unknown): string;
+/**
+ * The bounded key for one input: the canonical form inline when it is small, and a
+ * digest plus byte length when it is not. The length is kept so a truncated input
+ * cannot collide with a genuinely different one of the same digest.
+ */
+export declare function idempotencyKey(input: unknown): string;
+/**
+ * The deterministic id of an operation: same act and same input give the same id,
+ * whatever the key order, and a materially different operation never does.
+ */
+export declare function operationId(input: {
+    act: string;
+    input: unknown;
+}): string;
+/** One recorded attempt. The index holds only what makes a retry recognisable. */
+export interface OperationRecord {
+    id: string;
+    act: string;
+    /** When the attempt was recorded (caller-supplied, so a test can be deterministic). */
+    at: string;
+    /** What happened, when the caller knows: e.g. `applied`, `refused`, `interrupted`. */
+    outcome?: string;
+    /**
+     * T28: the phase this operation belongs to, when it has one.
+     *
+     * Recorded so a budget can be counted FROM the index rather than tracked
+     * separately — the children-per-phase cap is `readOperations(...)` filtered by
+     * phase, which needs no new state and cannot drift from the operations it counts.
+     */
+    phase?: string;
+}
+/** The run-scoped, append-only operation index. Bounded by use, git-ignored with the run. */
+export declare function operationsPath(runDir: string): string;
+/** Every recorded attempt, oldest first. Never throws; a corrupt line is skipped. */
+export declare function readOperations(runDir: string): OperationRecord[];
+/** The LATEST record for an id, or null when the operation has never been attempted. */
+export declare function findOperation(runDir: string, id: string): OperationRecord | null;
+/** Append one attempt. Best-effort: a failed write must never change an operation's outcome. */
+export declare function recordOperation(runDir: string, record: OperationRecord): boolean;
+/** True when this exact operation has already been attempted in this run. */
+export declare function wasAttempted(runDir: string, id: string): boolean;
+/** True when the index exists at all — lets a caller distinguish "no retry" from "no index". */
+export declare function hasIndex(runDir: string): boolean;
+/**
+ * T28: how many DISTINCT operations of one act have been recorded for one phase.
+ *
+ * Counted from the index rather than tracked in parallel, so a budget cannot drift
+ * away from the operations it bounds. DISTINCT ids, not records, because a resumed
+ * turn re-records the SAME operation: counting records would make a long review look
+ * like many children and fire the cap on legitimate work, while a genuine new
+ * operation (a repaired artifact changes the body, hence the id) still counts.
+ */
+export declare function countOperations(runDir: string, act: string, phase: string): number;

package/lib/index.d.ts

@@ -1,5 +1,36 @@
 import { type Context } from '@deepseek-ai/cordis';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { RecursiveModeConfig } from './config.ts';
+/**
+ * rc.2 rebase (T31a) — the message-source vocabulary changed under us.
+ *
+ * At `dsh-v0.1.1-rc.2` `MessageSourceMap` carried a shared catch-all
+ * `plugin: { kind: 'plugin'; plugin: string }` entry, which this file used for
+ * its injected phase-lint reminder. At `dsh-v0.2.0-rc.2` that entry is GONE:
+ * the map is merge-extensible and, in its own words, "each producer declares
+ * its own `kind` in its own module; there is no shared catch-all `plugin`
+ * kind". This was invisible in the old checkout because its `node_modules`
+ * still held a stale `dsh-llm`.
+ *
+ * The idiom below is copied from the shipped `@deepseek-ai/dsh-repeat-tool-reminder`,
+ * whose pre-step reminder is the closest analogue to ours: a user-role message
+ * whose source declares its own kind and a `form: 'notice'` one-line account.
+ */
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'recursive-mode': {
+            kind: 'recursive-mode';
+        } & ContextFormed;
+    }
+}
 export declare const name = "@try-works/dsh-recursive-mode";
+/**
+ * T7: the plugin's Config schema, which the settings service DISCOVERS (see `src/config.ts`
+ * for why declaring it is the registration). Re-exported from the entry because the Loader
+ * reads it from the plugin module.
+ */
+export { Config } from './config.ts';
+export type { RecursiveModeConfig } from './config.ts';
 export { RecursiveRuntime } from './runtime.ts';
 export { createRecursiveStatusTool } from './recursive_status.tool.ts';
 export { createRecursiveInitTool } from './recursive_init.tool.ts';
@@ -31,15 +62,4 @@ export * from './skills.ts';
  * read-path tools (status/init/lock/lint) are registered through it (R2/R4).
  */
 export declare const inject: string[];
-/**
- * Plugin entry (SP2 R1). Stage A (mount-time, this apply): register the
- * isolated ctx.recursive service + the recursive_* tools + the /recursive
- * command + the recursive:policy prompt section + the LIVE board/strip route
- * (HTTP state + SSE), served per-workspace from the filesystem fold. No
- * repo/run work and NO session-event emission here: zero recursive/* events
- * are ever appended (resume-crash fix), and the board reads the live fs route.
- */
-export declare function apply(ctx: Context, config?: {
-    shellOnly?: boolean;
-    repoRoot?: string;
-}): void;
+export declare function apply(ctx: Context, config?: RecursiveModeConfig): void;