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

package/lib/status.d.ts

@@ -1,4 +1,19 @@
-import type { ArtifactState, PhaseDef, RecursiveStatusResult } from './types.ts';
+import type { ArtifactState, PendingWorkItem, PhaseDef, PhasePosition, RecursiveStatusResult } from './types.ts';
+import { PHASE_POSITIONS } from './types.ts';
+export { PHASE_POSITIONS };
+export type { ArtifactState, PhasePosition };
+/**
+ * T21 — derive the ONE named position of a phase from the fields consumers
+ * currently recombine for themselves. Total and disjoint: every reachable shape
+ * returns exactly one member of {@link PHASE_POSITIONS}, so two consumers cannot
+ * read the same phase and disagree.
+ *
+ * Order is the whole design. `tampered` outranks every other lock problem
+ * because a content/hash divergence is the more serious fact — a locked artifact
+ * whose bytes changed invalidates everything that cited it, whereas a failed gate
+ * on an otherwise-intact artifact is a fixable omission.
+ */
+export declare function phasePosition(state: ArtifactState): PhasePosition;
 export declare const RUN_ARTIFACT_SEQUENCE: string[];
 export declare const PHASES: PhaseDef[];
 export declare function escapeRegExp(value: string): string;
@@ -15,5 +30,42 @@ export declare function lockHashFromContent(content: string): string;
 export declare function getWorkflowProfile(runDir: string): string;
 export { getLatestRunDirectory, discoverRuns, resolveRunDir } from './run.ts';
 export type { RunDiscoveryResult } from './run.ts';
+/**
+ * T18 — unresolved in-flight work, DERIVED from the run directory.
+ *
+ * There is no ledger, no queue and no stored flag: this reads what is already on
+ * disk, which is what makes the quiescence rule in `lockArtifact` cheap enough to
+ * run on every lock. Plan §4.0: derived beats stored wherever derivation is
+ * cheap, and losing a derived fact costs nothing because it cannot be lost.
+ *
+ * WHY THIS IS THE ONLY CASE IMPLEMENTED. The pairing is created early in the
+ * happy path — `runtime.ts` writes `subagents/<id>/handoff.md` BEFORE the bundle
+ * and before the child starts — so the exposure is exactly the window between
+ * the handoff and the reply. The plan also names "a reopen plan without a
+ * completion marker" and "a closeout phase scaffolded without a receipt"; neither
+ * exists on disk (`reopenArtifact` reverts the artifact in place and invalidates
+ * receipts; a scaffolded-but-unlocked closeout artifact is the normal pre-lock
+ * state of every phase), and enforcing either would make locking impossible.
+ * That omission is deliberate and recorded on the item.
+ *
+ * A reply that exists but is empty is NOT a submission, so it stays pending —
+ * a child that created the file and wrote nothing has not answered.
+ *
+ * Total: a missing or unreadable run directory yields an empty set, never a throw.
+ */
+export declare function pendingWork(runDir: string): PendingWorkItem[];
 export declare function getArtifactState(artifactPath: string, workflowProfile: string): ArtifactState;
+/**
+ * Fold-cache diagnostics. Read-only observation, kept in the shipped API because
+ * "is the frame hitting?" is the first question when the board feels slow, and a
+ * counter is cheaper than guessing. `reparsed` counts EXISTING artifacts re-read
+ * (an absent one costs only an existsSync).
+ */
+export declare function foldDiagnostics(): {
+    folds: number;
+    reuses: number;
+    reparsed: number;
+};
+/** Drop every frame and counter. For tests, and for a caller that knows the tree changed underneath. */
+export declare function resetFoldCache(): void;
 export declare function foldRun(runDir: string, runId: string): RecursiveStatusResult;

package/lib/teams-loop.d.ts

@@ -3,8 +3,7 @@
  *
  * The recursion concept's core state machine, expressed over the native
  * `agentTeams` service: ONE durable task per phase carries the loop —
- * createTask (pending) → claim (in_progress) → audit round → on REVISE
- * updateTask(edit, repair instruction) → re-audit the SAME task → on APPROVE
+ * createTask (pending) → claim (in_progress) → audit round → on REVISE* updateTask(edit, repair instruction) → re-audit the SAME task → on APPROVE
  * updateTask(complete) → lock. A stuck reviewer is interrupted through the
  * team's own kill switch; a REJECT or round-cap releases the task and fails
  * loud — a lock NEVER happens before an APPROVE verdict.
@@ -104,6 +103,11 @@ export interface AuditLoopRound {
     readonly verdict: AuditVerdict;
     readonly repair?: string;
     readonly taskRevision: number;
+    /**
+     * T20: true when this round produced the SAME progress cursor as its predecessor —
+     * the same finding, restated. Rendered so the board shows a loop as a loop.
+     */
+    readonly noProgress?: boolean;
 }
 /** The auditToPass result. */
 export interface AuditToPassResult {
@@ -116,6 +120,52 @@ export interface AuditToPassResult {
     readonly locked: boolean;
     /** Latest task view (board-facing per-phase history). */
     readonly taskView?: TeamTaskViewLike;
+    /**
+     * T19: true when this call was recognised as a repeat of an audit-to-pass that had
+     * already completed for this run and phase, so no second task was created. The
+     * caller must read the PHASE's lock state itself — this result cannot claim the
+     * artifact is locked, because a recognised repeat performs no locking.
+     */
+    readonly recognisedRepeat?: boolean;
+    /**
+     * T20: how many rounds ran. The absolute backstop, reported so a caller can see how
+     * close the loop came to its cap.
+     */
+    readonly attempts?: number;
+    /** T20: consecutive rounds that produced the SAME progress cursor. */
+    readonly consecutiveNoProgress?: number;
+    /** T20: the last round's progress cursor — what the round said was wrong. */
+    readonly progressCursor?: string;
+    /** T28: how many repairs were requested before the loop stopped. */
+    readonly repairAttempts?: number;
+    /**
+     * T20: true when the loop stopped in a state that must NOT be retried
+     * automatically — no progress, or the attempt cap. The caller has to decide to
+     * resume, deliberately, rather than a loop quietly grinding on or quietly giving up.
+     */
+    readonly resumeRequired?: boolean;
+}
+/**
+ * T19: the operation-index seam.
+ *
+ * INJECTED, not imported. `auditToPass` is pure over its seams — it has no `runDir`
+ * and no filesystem access, which is exactly what lets the whole loop be driven by
+ * fakes in tests. Reaching for `recordOperation` directly would have traded that away
+ * for one line of convenience, so the caller supplies persistence instead.
+ */
+export interface AuditOperationsSeamLike {
+    /** The previously recorded attempt for an id, or null when it is new. */
+    find?: (id: string) => {
+        id: string;
+        outcome?: string;
+    } | null;
+    /** Record one attempt. Best-effort: a failed write must not change the loop's outcome. */
+    record?: (record: {
+        id: string;
+        act: string;
+        at: string;
+        outcome?: string;
+    }) => void;
 }
 /** Inputs for one audit-to-pass loop. */
 export interface AuditToPassInput {
@@ -130,6 +180,11 @@ export interface AuditToPassInput {
     readonly blockedBy?: readonly TeamTaskIdLike[];
     /** Write scopes for the phase artifact (advisory, overlap-warned). */
     readonly writeScopes?: readonly string[];
+    /**
+     * T19: the operation index, injected. Absent it, the loop runs exactly as before —
+     * no pre-check, no records, no behaviour change.
+     */
+    readonly operations?: AuditOperationsSeamLike;
     /** Run ONE audit round for the current task; live usage delegates (T4). */
     readonly runAuditRound: (round: number, task: TeamTaskViewLike) => Promise<AuditRoundOutcome>;
     /** Lock the phase artifact — called ONLY after an APPROVE verdict. */
@@ -138,6 +193,25 @@ export interface AuditToPassInput {
     readonly reviewerName?: string;
     /** Round cap (fail loud past it; no lock). */
     readonly maxRounds?: number;
+    /**
+     * T20: how many CONSECUTIVE rounds may repeat the same progress cursor before the
+     * loop stops and demands a resume. Default 2, so three identical rounds terminate:
+     * the first sets the cursor and the next two repeat it. Absent the bound, a phase
+     * could restate one unfixed finding until the attempt cap, which is the wrong
+     * budget — a round count indulges a loop while cutting off genuine progress.
+     */
+    readonly maxNoProgress?: number;
+    /**
+     * T28: the configurable caps. `maxAuditRounds` is the absolute round ceiling and
+     * `maxRepairAttempts` bounds how many times a phase may be sent back for repair
+     * even when every round finds something NEW — the case T20's no-progress bound
+     * deliberately lets run. Both are optional so an existing caller keeps its
+     * behaviour, with the round cap falling back to `maxRounds ?? 3`.
+     */
+    readonly budgets?: {
+        readonly maxAuditRounds?: number;
+        readonly maxRepairAttempts?: number;
+    };
     /** Per-round wait timeout before the audit round runs (skipped without the seam). */
     readonly waitTimeoutMs?: number;
 }
@@ -155,6 +229,21 @@ export declare function renderTaskHistory(task: TeamTaskViewLike | undefined, ro
  *   → APPROVE: updateTask(complete) → lockPhase()
  *   → REJECT / cap / stuck: updateTask(release) + interrupt, NO lock.
  */
+/**
+ * T19 wrapper: recognise a repeat, then record what happened.
+ *
+ * The identity covers this run and phase. A call whose operation was already recorded
+ * as APPLIED returns immediately without creating a second task — the acceptance's
+ * "recognised no-op rather than a second execution". Every other outcome (rejected,
+ * capped, errored) records as `unaccepted`, so a retry still runs: a failed audit must
+ * stay retryable, and only a COMPLETED one is a repeat.
+ *
+ * Per-round entries are recorded after the loop from the result's own round trail.
+ * That is one write per call instead of one per round, and it keeps the loop body
+ * free of persistence — but it does mean a crash MID-loop leaves the whole operation
+ * unrecorded, which is the honest trade for not threading a writer through every
+ * branch.
+ */
 export declare function auditToPass(input: AuditToPassInput): Promise<AuditToPassResult>;
 /** Whether a task view is currently claimed by the named owner (board-facing). */
 export declare function isTaskClaimedBy(task: TeamTaskViewLike, ownerName: string): boolean;

package/lib/training.d.ts

@@ -0,0 +1,211 @@
+/** The artifact whose lock marks a run as complete enough to learn from. */
+export declare const PHASE8_ARTIFACT = "08-memory-impact.md";
+/** The parent's exit codes, kept as names so a caller cannot mistake one failure for the other. */
+export declare const TRAINING_EXIT: {
+    /** The extractor could not be reached or run. */
+    readonly EXTRACTOR_UNAVAILABLE: 2;
+    /** There was not enough evidence to extract anything. */
+    readonly INSUFFICIENT_EVIDENCE: 3;
+};
+export type TrainingCode = 'OK' | 'EXTRACTOR_UNAVAILABLE' | 'INSUFFICIENT_EVIDENCE';
+export interface TrainingResult {
+    code: TrainingCode;
+    /** The parent's exit code: 0 on success, otherwise 2 or 3. Never a silent success. */
+    exit: number;
+    reason: string;
+    /** Files written. EMPTY on every failure path — asserted, not promised. */
+    writes: string[];
+}
+/** How many runs have a LOCKED phase-8 artifact. The gate's only input. */
+export declare function countPhase8LockedRuns(root: string, readText?: (path: string) => string | null): number;
+/**
+ * The gate: extraction needs MORE THAN ONE locked run.
+ *
+ * ⚠ ONE RUN IS NOT EVIDENCE — it is an anecdote, and a memory file written from a single run would
+ * teach the next run that one run's accidents are rules. The parent skips with an explanation rather
+ * than extracting from what it has, and this returns the explanation as part of the result.
+ */
+export declare function trainingGate(lockedRuns: number): TrainingResult;
+/** A learning candidate, before grouping. */
+export interface TrainingItem {
+    runId: string;
+    /** Changed paths or cited files — the stronger signal of which subsystem this belongs to. */
+    paths: string[];
+    text: string;
+}
+/**
+ * Infer the subsystem from changed paths.
+ *
+ * ⚠ PATHS BEAT PROSE. The parent is explicit that changed paths are the stronger signal, so this
+ * prefers them and falls back to a stable `unclassified` bucket rather than guessing from wording —
+ * a wrong subsystem files a learning where nobody will look for it.
+ */
+export declare function inferSubsystem(item: TrainingItem): string;
+export interface TrainingGroup {
+    subsystem: string;
+    items: TrainingItem[];
+    /** How many DISTINCT runs contributed. A single-run group must not train on its own. */
+    runs: number;
+    mode: 'contrastive' | 'winner-only';
+}
+/**
+ * Group items by subsystem and decide each group's mode.
+ *
+ * ⚠ REFUSE TO TRAIN ON A SINGLE-RUN GROUP ALONE. Two items from one run are one observation written
+ * twice, so such a group is DROPPED rather than trained on — the parent's rule, and the reason a
+ * group reports its distinct-run count. Winners and losers in one group support a CONTRASTIVE
+ * learning; otherwise the group is winner-only.
+ */
+export declare function groupLearnings(items: readonly TrainingItem[], isWinner: (item: TrainingItem) => boolean): TrainingGroup[];
+/**
+ * The trigger, run at the **RE-RUN** of closeout phase 08.
+ *
+ * ⚠ NOT AT THE FIRST LOCK, deliberately and per the parent: a run that has just locked would be
+ * training on itself, and its own conclusions would be promoted to memory before anything else had a
+ * chance to contradict them. The caller says `rerun: true` to mean "phase 08 has been through closeout
+ * more than once"; the first lock reports `OK` with an empty `writes` and a reason that says why.
+ */
+export declare function runPhase8Trigger(root: string, runId: string, options?: {
+    rerun?: boolean;
+    extractorAvailable?: boolean;
+    items?: readonly TrainingItem[];
+    isWinner?: (item: TrainingItem) => boolean;
+    /**
+     * The write seam. ABSENT IS NOT SUCCESS: with no writer the groups are planned and reported, and
+     * the reason SAYS the writes did not happen — because a result that looked successful while
+     * writing nothing is precisely the failure the parent's contract forbids ("do not claim memory
+     * updates").
+     */
+    write?: (relativePath: string, content: string) => string;
+    /**
+     * The registry read seam. WITHOUT IT THE REGISTRY IS NOT REFRESHED and the result SAYS SO, because
+     * a silent half-write would leave `MEMORY.md` describing a plane that has changed underneath it.
+     */
+    readText?: (relativePath: string) => string | null;
+    /**
+     * FU-5: THE PRODUCTION SPAWN, injected. When the caller supplies no `items`, the trigger RUNS the
+     * extractor through this runner — which is the link that was missing entirely: `extractAndGroup` was
+     * referenced only by its own definition, so the round trip existed and nothing invoked it.
+     */
+    runner?: (cmd: string) => ExtractorRun;
+}): TrainingResult;
+/**
+ * Render a group's shard.
+ *
+ * ⚠ ONE ITEM PER RUN IS NAMED, so a reader can trace a learning back to the run that produced it —
+ * and the group is never presented as more evidence than it is.
+ */
+export declare function renderGroupShard(group: TrainingGroup): string;
+/**
+ * T30 — the extractor, resolved from the environment.
+ *
+ * ⚠ THE EXTRACTOR IS NEVER EMBEDDED. The parent delegates through a command
+ * (`RECURSIVE_TRAINING_EXTRACTOR_CMD`) or a response file rather than shipping an LLM client, and this
+ * keeps that: the plugin resolves a command and hands it to a runner it is given.
+ *
+ * ⚠ WHY THE RUNNER IS INJECTED RATHER THAN SPAWNED HERE. This harness's file sandbox denies a child
+ * process the PIPED stdio a capture needs, so a module that spawned directly would be untestable in the
+ * environment it runs in — and a rule that cannot be tested is a rule that will rot. The DECISION lives
+ * here and is asserted with a fake runner; the SPAWN lives at the caller.
+ */
+export declare const TRAINING_EXTRACTOR_ENV = "RECURSIVE_TRAINING_EXTRACTOR_CMD";
+/**
+ * FU-5 — the RESPONSE FILE, which is what makes the spawn possible in a confined sandbox.
+ *
+ * ⚠ WHY A FILE AND NOT A PIPE. This harness's sandbox denies a child process the piped stdio a capture
+ * needs, so a spawn that read the extractor's stdout would fail with EPERM **in the environment it runs
+ * in**. The parent's own interface already solves this: it delegates through `--response-file`, i.e. the
+ * extractor WRITES ITS ANSWER TO A PATH. The plugin spawns with `stdio: 'ignore'` (which the sandbox
+ * allows), hands the path over in an environment variable, and reads the file afterwards.
+ */
+export declare const TRAINING_RESPONSE_FILE_ENV = "RECURSIVE_TRAINING_RESPONSE_FILE";
+/**
+ * Build the production runner: spawn the command, then read the file it was asked to write.
+ *
+ * ⚠ IT NEVER THROWS. A missing binary, a non-zero exit and a missing response file all come back as a
+ * non-zero `status` with an explanatory `stdout`, so `runExtractor` maps them to a TYPED failure — the
+ * closeout must not die because an extractor is misconfigured.
+ */
+export declare function spawnExtractorRunner(options: {
+    cwd: string;
+    responseFile: string;
+    /** Injected for tests; defaults to `node:child_process.spawnSync`. */
+    spawn?: (cmd: string, args: string[], opts: Record<string, unknown>) => {
+        status: number | null;
+        error?: Error;
+    };
+}): (cmd: string) => ExtractorRun;
+export declare function resolveExtractor(env: Record<string, string | undefined>): string | null;
+/** What a runner reports back. `status` is the process exit code; `stdout` its captured output. */
+export interface ExtractorRun {
+    status: number;
+    stdout: string;
+}
+export interface ExtractorOutcome {
+    ok: boolean;
+    /** Present only when `ok`; the raw JSON the extractor produced. */
+    payload?: unknown;
+    /** Present only when not `ok` — why, in the parent's terms. */
+    failure?: 'EXTRACTOR_UNAVAILABLE' | 'MALFORMED_OUTPUT';
+    reason: string;
+}
+/**
+ * Run the extractor and interpret its answer.
+ *
+ * ⚠ A NON-ZERO STATUS AND MALFORMED OUTPUT ARE BOTH FAILURES, and neither is "no items" — a malformed
+ * answer is a broken extractor, not a run with nothing to learn, and collapsing the two would report
+ * exit 3 (insufficient evidence) for a bug that deserves exit 2.
+ */
+export declare function runExtractor(runner: (cmd: string) => ExtractorRun, cmd: string | null): ExtractorOutcome;
+/**
+ * T30 — the registry line for a shard, and the registry update.
+ *
+ * ⚠ THE REGISTRY IS REFRESHED BY REPLACING A SHARD'S LINE, NOT BY APPENDING. Two lines for one shard
+ * would make `MEMORY.md` claim the plane holds something twice, and the loader reads the registry
+ * first — so a duplicated marker is not cosmetic, it is a wrong answer about what exists.
+ *
+ * ⚠ AND A SHARD IS NEVER REMOVED HERE. Per the memory-worker discipline this borrows: **supersede,
+ * never delete.** A shard that stops being written keeps its line and its history; removing it is a
+ * tombstone decision, not a side effect of training.
+ */
+export declare function registryLine(shardPath: string, taskType: string): string;
+export declare function updateMemoryRegistry(existing: string, entries: ReadonlyArray<{
+    path: string;
+    taskType: string;
+}>): string;
+/**
+ * T30 — the task-type shard.
+ *
+ * ⚠ `task-type` IS READ FROM THE GROUP'S MODE, and that is an INTERPRETATION rather than a measured
+ * fact: the parent writes `memory/training/<task-type>.md` without defining the key in the material I
+ * have, so the mode a group was extracted under (`contrastive` / `winner-only`) is what distinguishes
+ * one training shard from another here. Named so a reader can disagree with it instead of discovering it.
+ */
+export declare function taskTypeShardPath(mode: TrainingGroup['mode']): string;
+export declare function renderTaskTypeShard(groups: readonly TrainingGroup[]): string;
+/**
+ * T30 — turn the extractor's payload into items the grouping can use.
+ *
+ * ⚠ A MALFORMED PAYLOAD IS NOT A BROKEN EXTRACTOR. By the time this runs the extractor has exited 0 and
+ * produced parseable JSON, so the transport is fine; a payload carrying no items is an extractor that
+ * found nothing, which is **exit 3, not exit 2**. Keeping those apart is why `runExtractor` answers
+ * first and this second.
+ *
+ * ⚠ A PARTIAL ANSWER NEITHER LOSES THE BATCH NOR INVENTS EVIDENCE: an entry missing its text is
+ * SKIPPED rather than defaulted, because an item with invented text would be taught as a learning
+ * nobody extracted. An entry with no `runId` is skipped too — the grouping counts DISTINCT runs, so an
+ * unattributed observation would be pooled into a run it did not come from.
+ */
+export declare function parseExtractorItems(payload: unknown): TrainingItem[];
+/**
+ * T30 — the whole round trip, in the order the failure codes demand: resolve the command, run it,
+ * parse the payload, then group. Each stage keeps its own meaning — no command or a non-zero exit is
+ * **exit 2**; a payload with nothing usable in it is **exit 3**.
+ */
+export declare function extractAndGroup(runner: (cmd: string) => ExtractorRun, env: Record<string, string | undefined>, options?: {
+    isWinner?: (item: TrainingItem) => boolean;
+}): {
+    outcome: ExtractorOutcome;
+    items: TrainingItem[];
+    groups: TrainingGroup[];
+};

package/lib/ts-lint.d.ts

@@ -123,6 +123,21 @@ export declare function getPhaseOwnedActualChangedFiles(fileName: string, actual
 export declare function getRelatedAddendaPaths(runDir: string, artifactName: string): string[];
 /** get_stage_local_addenda_paths: run_dir/addenda/<base>.addendum-*.md. */
 export declare function getStageLocalAddendaPaths(runDir: string, artifactName: string): string[];
+/**
+ * get_run_tree_addenda: EVERY addendum in the run, wherever it was filed.
+ *
+ * ⚠ WHY THIS EXISTS BESIDE THE TWO ABOVE: both scan `run_dir/addenda/` and nothing else, and flatly. But an
+ * addendum is written BESIDE THE ARTIFACT IT CLOSES — the run ROOT is where the real ones live, e.g.
+ * `02-to-be-plan.addendum-r4-r2-mount-resolution.md`, which the comments elsewhere in this file cite by name
+ * — and a stage may file one in a subfolder. A reader that consults only `addenda/` therefore misses
+ * exactly the addenda that closed an upstream gap, which are the ones a closeout most needs to see.
+ *
+ * Returns run-relative POSIX paths, sorted, so a caller can join them onto the run directory and cite them
+ * verbatim. Matching uses {@link isAddendumArtifact} — the SAME predicate the rest of the plugin uses — so a
+ * name can never count as an addendum in one place and not another. `upstream-gap` names are matched too:
+ * they are the back-edge form of an addendum, and {@link getRelatedAddendaPaths} already treats them as one.
+ */
+export declare function getRunTreeAddenda(runDir: string): string[];
 /** get_current_phase_upstream_gap_addenda_paths: run_dir/addenda/<base>.upstream-gap.*.addendum-*.md. */
 export declare function getCurrentPhaseUpstreamGapAddendaPaths(runDir: string, artifactName: string): string[];
 /** get_header_field_block: lines under `Field:` until a stop field. */

package/lib/types.d.ts

@@ -20,6 +20,25 @@ export interface ArtifactState {
     todoHasSection: boolean;
     todoUnchecked: number;
 }
+/**
+ * T21 — ONE named position per phase, derived from the fields every consumer
+ * currently recombines for itself (`status`, `lockValid`, `lockProblems`,
+ * `blockers`). Two consumers recombining those independently is exactly how two
+ * consumers come to disagree about a phase's state; a single derived value gives
+ * them nothing to disagree about.
+ *
+ * Closed vocabulary, total and disjoint (see `phasePosition`):
+ *   `absent`       the artifact does not exist
+ *   `skipped`      an optional (or legacy-profile late) phase that is not present
+ *   `draft`        present and unlocked, with no blockers
+ *   `blocked`      present and unlocked, with at least one blocker
+ *   `invalid-lock` LOCKED but failing a condition other than its hash
+ *   `locked`       LOCKED and lock-valid
+ *   `tampered`     LOCKED with a hash mismatch — the more serious fact, so it wins
+ *                  over any other lock problem
+ */
+export type PhasePosition = 'absent' | 'skipped' | 'draft' | 'blocked' | 'invalid-lock' | 'locked' | 'tampered';
+export declare const PHASE_POSITIONS: readonly PhasePosition[];
 export interface PhaseState {
     key: string;
     label: string;
@@ -30,6 +49,8 @@ export interface PhaseState {
     lockValid: boolean;
     lockProblems: string[];
     blockers: string[];
+    /** T21: the single derived state of this phase. */
+    position: PhasePosition;
 }
 export interface RecursiveStatusResult {
     runId: string;
@@ -59,6 +80,21 @@ export interface RecursiveTamper {
     path: string;
     reason: string;
 }
+/**
+ * T18 — one piece of unresolved in-flight work, DERIVED from the run directory
+ * (there is no ledger). `unanswered-delegation` is a `handoff.md` with no reply
+ * yet; `empty-reply` is a reply file that exists but carries nothing, which is
+ * not a submission.
+ */
+export interface PendingWorkItem {
+    kind: 'unanswered-delegation' | 'empty-reply';
+    /** The delegation directory name, so a refusal can name what is blocking. */
+    delegationId: string;
+    /** Repo-relative path of the file that would settle it, or of the handoff. */
+    path: string;
+    /** One sentence for a human, naming the delegation and what is missing. */
+    detail: string;
+}
 /** One subagent activity fact (start or end). */
 export interface RecursiveSubagent {
     childId: string;
@@ -72,6 +108,12 @@ export interface RecursivePhaseRow {
     status: string;
     lockedAt?: string;
     lockHash?: string;
+    /**
+     * T21: the same single derived position `foldRun` publishes, carried onto the
+     * wire so the board and the tooling cannot disagree about a phase's state.
+     * Optional so a row produced before this field existed stays readable.
+     */
+    position?: PhasePosition;
 }
 /**
  * The per-run wire card the recursive projection folds: the board, inspector,
@@ -93,6 +135,12 @@ export interface RecursiveRunCard {
     tampers: Record<string, RecursiveTamper>;
     /** Subagent activity (latest status wins per childId). */
     subagents: Record<string, RecursiveSubagent>;
+    /**
+     * T18: unresolved in-flight work, DERIVED from the run directory on every fold
+     * (never stored). Optional so an older producer's card stays readable; the
+     * folder always sets it. A non-empty array explains why a lock will be refused.
+     */
+    pendingWork?: PendingWorkItem[];
     /** Set on recursive/run-merged; the run re-keys to this root. */
     mergedToRepoRoot?: string;
 }