@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/orchestrator.js

@@ -12,8 +12,9 @@
  *   /task-cancel           cancel the running task (soft-terminal — still resumable)
  *
  * The orchestrator persists after every phase boundary to
- * <cwd>/.pi-tasks/TASK_NNNN.md. All user interaction during phases runs through
- * ctx.ui dialogs; the main pi chat only receives the final spec.
+ * <cwd>/.pi-tasks/TASK_NNNN.md. User interaction during phases runs through the
+ * SessionUI bridge — a local ctx.ui dialog raced against a remote browser card —
+ * never through the main conversation, which only receives the final spec.
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -61,11 +62,12 @@ let piApi = null;
 /**
  * The live session's thinking level, as a {@link ThinkingControl}.
  *
- * Goes through `piApi` rather than the command ctx because
- * `ExtensionCommandContext` exposes `thinkingLevel` READ-ONLY; the setter lives
- * on the extension API. Before `registerTask(pi)` has run there is nothing to
- * control, so this degrades to a no-op pair rather than throwing — a task that
- * cannot move the level should still run.
+ * Goes through `piApi` rather than the command ctx because `ExtensionContext`
+ * (which the command ctx extends) carries `thinkingLevel` as a plain optional
+ * VALUE with no setter; `setThinkingLevel` lives on `ExtensionAPI`. Before
+ * `registerTask(pi)` has run there is nothing to control, so this degrades to a
+ * no-op pair rather than throwing — a task that cannot move the level should
+ * still run.
  */
 function piThinkingControl() {
     const api = piApi;
@@ -93,9 +95,9 @@ export class TaskRunner {
     _deps;
     _pc;
     /**
-     * Per-phase wall-clock durations collected during the run. Written to the
-     * `## phase timings` section on successful completion so we can spot
-     * regressions and target future speed work. Each top-level entry is a
+     * Per-phase wall-clock durations collected during the run, written to the
+     * `## phase timings` section — on completion, and again from the catch so a
+     * failed run still records what it got through. Each top-level entry is a
      * phase (refine/research/grill/compose/critique); children are optional
      * sub-step splits the phase chose to record via deps.recordSubStep.
      */
@@ -113,8 +115,8 @@ export class TaskRunner {
         this._fixInstruction = opts.fixInstruction;
         this._implAwaited = opts.implAwaited ?? false;
         this._startedAt = Date.now();
-        // We'll populate id/title/phase lazily in run().
-        // Placeholder — real values set in run().
+        // Placeholder: id/title/phase are only known once run() has allocated or
+        // read the task file.
         this._widgetState = {
             taskId: '',
             title: '',
@@ -137,7 +139,7 @@ export class TaskRunner {
             },
             // Handed DOWN so the child's own snapshot carries a window and the
             // StallDetector's churn rule can arm; resolveContextUsage below stays
-            // as the fallback for a child that still reports none (issue #16).
+            // as the fallback for a child that still reports none.
             contextWindow: parentContextWindow,
             onContextUsage: snapshot => {
                 this._widgetState.contextUsage = resolveContextUsage(snapshot, this._widgetState.contextUsage, parentContextWindow);
@@ -175,16 +177,15 @@ export class TaskRunner {
     cancel() {
         this._abort.abort();
     }
-    /** Execute the full task lifecycle. Mid-run input holds instead of starting
-     *  a competing turn for the whole of it, and the terminal interception is
-     *  armed for the same window (`withRun`); nested inside `runGatedTask` or
-     *  the `/task-auto` loop the bracket refcounts, so this changes nothing there
-     *  and covers the fire-and-forget `runSingleTask` path on its own. */
     /**
-     * Run the task and NAME how it ended.
+     * Run the task and NAME how it ended (`RunEnd`), so no caller has to re-read
+     * the task file to find out.
      *
-     * This returned `void`, so the caller re-read the task file to learn what had
-     * just happened here — see run-end.ts for the report that got wrong.
+     * Mid-run input holds instead of starting a competing turn for the whole of
+     * it, and the terminal interception is armed for the same window (`withRun`);
+     * nested inside `runGatedTask` or the `/task-auto` loop the bracket refcounts,
+     * so this changes nothing there and covers the fire-and-forget
+     * `runSingleTask` path on its own.
      */
     async run() {
         return withRun(this._ctx, {}, () => this._run());
@@ -226,11 +227,12 @@ export class TaskRunner {
             await this._onStart(id);
         // Wire up per-task debug log (<cwd>/.pi-tasks/TASK_XXXX-debug.log).
         const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
-        // Left UNSET at level `off`, so the ~39 `logDebug?.(…)` sites downstream
-        // short-circuit before they format a string and the file is never created.
-        // A caller-supplied `logDebug` seam WINS: it is the only way to observe
-        // the ~39 trail decisions from a runner-driven test, and production never
-        // sets one, so the file writer is unaffected.
+        // `gateDebugWriter` returns undefined at level `off`, so every
+        // `logDebug?.(…)` site downstream short-circuits before it formats a string
+        // and the file is never created. A caller-supplied `logDebug` seam WINS
+        // (`??=`): it is the only way to observe the trail decisions from a
+        // runner-driven test, and production never sets one, so the file writer is
+        // unaffected.
         this._deps.logDebug ??= gateDebugWriter((msg) => {
             const line = `${new Date().toISOString()} ${msg}\n`;
             fsp.appendFile(debugLogPath, line).catch(() => {
@@ -295,9 +297,9 @@ export class TaskRunner {
                 await postCommitPhase(phase, this._deps, this._pc, out);
                 // SAFE CHECKPOINT (phase boundary): this phase's output is on disk
                 // and the next `advance()` has not moved front-matter forward, so a
-                // resume re-enters at exactly this phase. Without this the whole
-                // spec pipeline (refine→critique, ~4.5 min on the mx5 run, research
-                // alone ~3 min) runs to completion after a cancel is requested.
+                // resume re-enters at exactly this phase. Without a checkpoint here
+                // the whole refine→critique pipeline runs to completion after a
+                // cancel is requested.
                 // Throwing USER_CANCELLED reuses the existing cancellation path:
                 // handleFailure leaves the task resumable and /task-auto's catch
                 // announces the resume hint.
@@ -375,10 +377,11 @@ export class TaskRunner {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
         armImplWidget(meta, { oneShot: true });
-        // Always name a delivery mode. pi ignores it when the session is idle and
-        // uses it when something else is streaming — so this one call is correct
-        // in both cases, where an isIdle() check is a check-then-act race that
-        // loses to any turn starting in between (issue #8).
+        // Always name a delivery mode. pi's `prompt()` consults `streamingBehavior`
+        // only inside `if (this.isStreaming)`, so naming one is inert on an idle
+        // session and queues on a busy one — correct in both cases, where an
+        // isIdle() check is a check-then-act race that loses to any turn starting
+        // in between.
         piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
     }
     /**
@@ -418,9 +421,8 @@ export class TaskRunner {
  * deliver its spec. With waitForImplementation, block until the agent finishes
  * implementing the delivered spec.
  *
- * The ending comes from `TaskRunner.run`. It used to be read back off the task
- * file's front matter — a disk round-trip this process made to learn what it had
- * just done, and one that could not tell a cancel from a failure.
+ * The ending in the result comes from `TaskRunner.run` itself, not from re-reading
+ * the task file's front matter — which cannot tell a cancel from a failure.
  */
 export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     let taskId = '';
@@ -441,10 +443,12 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
         withSession: async (newCtx) => {
             freshCtx = newCtx;
             getBridge().currentCtx = newCtx; // keep remote dispatch ctx fresh across session replacement
-            // Same reason, for the terminal: pi clears every extension terminal
-            // input listener when the old session is invalidated, and that
-            // happens at the START of each task — precisely the window a typed
-            // /task-auto-cancel has to survive. No-op unless a run armed one.
+            // Same reason, for the terminal: pi wires
+            // `setBeforeSessionInvalidate(() => this.resetExtensionUI())`, and
+            // `resetExtensionUI` calls `clearExtensionTerminalInputListeners()`.
+            // Every extension listener dies at the START of each task — precisely
+            // the window a typed /task-auto-cancel has to survive. No-op unless a
+            // run armed one.
             rearmCancelListener(newCtx);
             const runner = new TaskRunner({
                 ctx: newCtx,
@@ -460,7 +464,8 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                     // here rather than at either call site.
                     const release = holdImplementationThinking(opts.thinkingControl ?? piThinkingControl());
                     try {
-                        // Queue-or-run: never throws, whatever else is on the session (issue #8).
+                        // Queue-or-run: naming a delivery mode means pi's
+                        // "Agent is already processing" throw is unreachable here.
                         await newCtx.sendUserMessage(spec, { deliverAs: 'followUp' });
                         if (opts.waitForImplementation) {
                             await newCtx.waitForIdle();
@@ -502,12 +507,9 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     // delivered and the task file already reads `completed`:
     //
     //   • the user interrupted and declined to steer — a pause, not a fault;
-    //   • the implementation turn died with stopReason "error" (a context-overflow
-    //     400, say), which must stop /task-auto here rather than let it commit and
-    //     advance on a file that says `completed`.
-    //
-    // Both used to reach the caller as extra fields beside a boolean, and both are
-    // endings.
+    //   • the implementation turn died with stopReason "error", which must stop
+    //     /task-auto here rather than let it commit and advance on a file that
+    //     says `completed`.
     let end = runEnd;
     if (end.kind === 'completed' && interrupted)
         end = { kind: 'interrupted' };
@@ -536,9 +538,9 @@ export const gateRunTask = (c, cwd, t, opts) => runSingleTask(c, cwd, t, {
     // NO `seams` here, deliberately. Threading them would need a field on
     // `GateParams` and another on `GateDeps`, and nothing — production or
     // test — would set either: the gate is reached through two orchestrators
-    // that build their params from a task file. An unused field on a seam
-    // roster is the `WorkerOutcome.reason` shape (written twelve times, read
-    // by nothing), so this stays unplumbed until a test actually needs it.
+    // that build their params from a task file. `WorkerOutcome.reason` is what
+    // that costs: written at every `workerUnavailable` call site and read
+    // nowhere. So this stays unplumbed until a test actually needs it.
 });
 /**
  * Demote a task file to a resumable state after a gate (or its implementation)
@@ -567,15 +569,13 @@ export async function markResumable(cwd, taskId) {
 export async function runGatedTask(ctx, cwd, raw, opts = {}) {
     // The GATES are part of the run, and they are child processes with the host
     // session idle — the same hold window as the spec phases. Bracketing only
-    // TaskRunner would leave verify/enforce looking like "no run", which a live
-    // run on pi 0.82.1 showed as runActive=false while the widget still read
-    // "verifying work" (issue #8). The body has many early returns, so the
-    // bracket lives in this wrapper rather than in a dozen places. The same
-    // bracket arms the raw-stdin interception for the WHOLE run: without it a
-    // plain /task had no terminal path at all — only /task-auto armed one — so a
-    // line typed during it went into pi's queue and fired after the run (seen
-    // live). No onCancel: a typed /task-auto-cancel goes through the generic
-    // bridge dispatch here.
+    // TaskRunner would leave verify/enforce reading as "no run" while the widget
+    // still says "verifying work". The body has many early returns, so the bracket
+    // lives in this wrapper rather than in a dozen places. The same bracket arms
+    // the raw-stdin interception for the WHOLE run: without it a line typed during
+    // a plain /task lands in pi's `pendingUserInputs` and fires after the run. No
+    // onCancel: a typed /task-auto-cancel goes through the generic bridge dispatch
+    // here.
     await withRun(ctx, {}, () => runGatedTaskInner(ctx, cwd, raw, opts));
 }
 async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
@@ -595,10 +595,8 @@ async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
     const res = await deps.runTask(active, cwd, raw, { resumeId: opts.resumeId });
     active = res.ctx ?? active;
     const tag = res.taskId || 'Task';
-    // One dispatch over the named ending. The four-branch ladder this replaces put
-    // a CANCELLED run into the `!ok` arm, so `/task-cancel` overwrote the file's
-    // `cancelled` with `failed` and told the user their task had stopped and needed
-    // fixing. Resumability comes from RUN_END_POLICY; the wording stays here,
+    // One dispatch over the named ending, so a cancel can never be reported as a
+    // failure. Resumability comes from RUN_END_POLICY; the wording stays here,
     // because `/task-auto` says `/task-auto-resume` where this says `/task-resume`.
     if (!runSucceeded(res.end)) {
         const policy = RUN_END_POLICY[res.end.kind];
@@ -656,7 +654,7 @@ async function handleTask(args, ctx) {
     // When a gate is enabled, /task awaits the implementation and runs the same
     // verify + enforce gates a /task-auto sub-task does. With both gates off
     // (the default), /task stays fire-and-forget: hand the spec to the main
-    // conversation and return immediately, exactly as before.
+    // conversation and return immediately.
     const cfg = getConfig();
     if (cfg.verifyWork || cfg.enforceGuidelines) {
         await runGatedTask(ctx, cwd, raw);

package/dist/task/orientation.d.ts

@@ -1,17 +1,16 @@
 /**
- * Project orientation core — a bounded snapshot of the few files every research
- * worker re-reads cold to learn "what is this project" (manifest, config, domain
- * types, schema, entrypoints, API surface). The four workers run as separate
- * child processes with no shared memory, so today each one independently
- * `read()`s the same hot files: across the recorded mx5 run package.json was
- * read 87×, src/types/index.ts 82×, and 55% of all worker reads were repeats of
- * a file another worker in the same task had already read.
+ * Project orientation core — a bounded snapshot of the few files a research worker
+ * re-reads cold to learn "what is this project" (manifest, config, domain types,
+ * schema, entrypoints, API surface). The four research workers are separate child
+ * processes with no shared memory, so without this each one reads the same hot
+ * files for itself.
  *
- * This module picks that orientation core from the file inventory (repo-agnostic,
- * by path convention), reads it ONCE in the parent, and the caller folds it into
- * the shared prompt header — so every worker already has those files and skips
- * the cold read. It is purely additive: nothing is blocked, so a worker can still
- * read anything it wants; orientation only removes the need to.
+ * This module picks that core from the file inventory (repo-agnostic, by path
+ * convention) and reads it ONCE in the parent. The caller folds the block into a
+ * prompt: refine gets a tier-0/1 subset, and phases.ts prepends the full block to
+ * the two READ-HEAVY research workers (`worker:files`, `worker:apis`) — not to all
+ * four. It is purely additive: nothing is blocked, so a worker can still read
+ * anything it wants; orientation only removes the need to.
  *
  * Bounded by design — the snapshot can never overflow the prompt regardless of
  * repo size: a hard total byte budget, a per-file cap (one huge file can't eat
@@ -20,23 +19,19 @@
  * core; reading takes an injectable reader so it can be exercised without a repo.
  */
 /**
- * Total bytes of file content the orientation block may contain (~10k tokens).
- * This is the real overflow guard: it bounds the block regardless of repo size,
- * and because the snapshot is prepended to each read-heavy worker it also caps
- * the prefill those workers pay. Selection stops as soon as adding a file would
- * exceed it.
+ * Total bytes the emitted orientation block may occupy. This is the real overflow
+ * guard: it bounds the block regardless of repo size, and because the snapshot is
+ * prepended to each read-heavy worker it also caps the prefill those workers pay.
+ * Selection stops as soon as adding a file would exceed it.
  */
 export declare const ORIENTATION_BYTE_BUDGET: number;
 /** A single file larger than this is skipped (read by the worker as before). */
 export declare const ORIENTATION_PER_FILE_MAX: number;
 /**
  * Backstop file-count cap — a guard against a pathological repo with hundreds of
- * tiny core files packing the byte budget into noise, NOT a normal-case limit.
- * It is deliberately set high enough that the byte budget binds first on real
- * repos (verified: mx5/aiz-server hit the budget at ~16 files; a 5000-file repo
- * yields only ~6 orientation candidates because leaf source is filtered out). An
- * earlier cap of 16 wrongly bound before the budget — e.g. it dropped 5 core
- * files on a 165-file repo while leaving 17KB of budget unused.
+ * tiny core files packing the byte budget into noise, NOT a normal-case limit. Set
+ * high enough that the byte budget binds first: whenever this cap is what stops
+ * selection, budget is left unspent and core files are dropped for no reason.
  */
 export declare const ORIENTATION_MAX_FILES = 40;
 /**

package/dist/task/orientation.js

@@ -1,17 +1,16 @@
 /**
- * Project orientation core — a bounded snapshot of the few files every research
- * worker re-reads cold to learn "what is this project" (manifest, config, domain
- * types, schema, entrypoints, API surface). The four workers run as separate
- * child processes with no shared memory, so today each one independently
- * `read()`s the same hot files: across the recorded mx5 run package.json was
- * read 87×, src/types/index.ts 82×, and 55% of all worker reads were repeats of
- * a file another worker in the same task had already read.
+ * Project orientation core — a bounded snapshot of the few files a research worker
+ * re-reads cold to learn "what is this project" (manifest, config, domain types,
+ * schema, entrypoints, API surface). The four research workers are separate child
+ * processes with no shared memory, so without this each one reads the same hot
+ * files for itself.
  *
- * This module picks that orientation core from the file inventory (repo-agnostic,
- * by path convention), reads it ONCE in the parent, and the caller folds it into
- * the shared prompt header — so every worker already has those files and skips
- * the cold read. It is purely additive: nothing is blocked, so a worker can still
- * read anything it wants; orientation only removes the need to.
+ * This module picks that core from the file inventory (repo-agnostic, by path
+ * convention) and reads it ONCE in the parent. The caller folds the block into a
+ * prompt: refine gets a tier-0/1 subset, and phases.ts prepends the full block to
+ * the two READ-HEAVY research workers (`worker:files`, `worker:apis`) — not to all
+ * four. It is purely additive: nothing is blocked, so a worker can still read
+ * anything it wants; orientation only removes the need to.
  *
  * Bounded by design — the snapshot can never overflow the prompt regardless of
  * repo size: a hard total byte budget, a per-file cap (one huge file can't eat
@@ -20,23 +19,19 @@
  * core; reading takes an injectable reader so it can be exercised without a repo.
  */
 /**
- * Total bytes of file content the orientation block may contain (~10k tokens).
- * This is the real overflow guard: it bounds the block regardless of repo size,
- * and because the snapshot is prepended to each read-heavy worker it also caps
- * the prefill those workers pay. Selection stops as soon as adding a file would
- * exceed it.
+ * Total bytes the emitted orientation block may occupy. This is the real overflow
+ * guard: it bounds the block regardless of repo size, and because the snapshot is
+ * prepended to each read-heavy worker it also caps the prefill those workers pay.
+ * Selection stops as soon as adding a file would exceed it.
  */
 export const ORIENTATION_BYTE_BUDGET = 40 * 1024;
 /** A single file larger than this is skipped (read by the worker as before). */
 export const ORIENTATION_PER_FILE_MAX = 12 * 1024;
 /**
  * Backstop file-count cap — a guard against a pathological repo with hundreds of
- * tiny core files packing the byte budget into noise, NOT a normal-case limit.
- * It is deliberately set high enough that the byte budget binds first on real
- * repos (verified: mx5/aiz-server hit the budget at ~16 files; a 5000-file repo
- * yields only ~6 orientation candidates because leaf source is filtered out). An
- * earlier cap of 16 wrongly bound before the budget — e.g. it dropped 5 core
- * files on a 165-file repo while leaving 17KB of budget unused.
+ * tiny core files packing the byte budget into noise, NOT a normal-case limit. Set
+ * high enough that the byte budget binds first: whenever this cap is what stops
+ * selection, budget is left unspent and core files are dropped for no reason.
  */
 export const ORIENTATION_MAX_FILES = 40;
 /** Code/config/doc extensions worth pre-reading; everything else is ignored. */
@@ -100,10 +95,9 @@ function depth(p) {
  */
 export function orientationTier(path) {
     const lower = path.toLowerCase();
-    // Never orient on vendored/build output or tests: a dependency's manifest or
-    // a big *.test.ts would otherwise outrank the project's own files and eat the
-    // budget (validated against the mx5 traces — node_modules/hono/package.json
-    // and zod-schemas.test.ts both crowded out genuinely hot project files). A
+    // Never orient on vendored/build output or tests: a dependency's package.json
+    // is tier 0 by basename and a `*.test.ts` under `src/types/` is tier 2, so
+    // either would outrank the project's own files and eat the budget. A
     // git-ls-files inventory won't list these anyway; this is belt-and-braces.
     if (/(^|\/)(node_modules|dist|build|out|vendor|\.git|coverage)\//.test(lower))
         return null;
@@ -167,10 +161,9 @@ export async function buildOrientation(inventoryPaths, readFile, opts = {}) {
     const supplied = new Set();
     const parts = [];
     // Budget the *emitted* block, not just the raw content: the per-file fence
-    // (`--- path ---\n` + the `\n\n` join) and the fixed wrapper add up across
-    // many files and would otherwise let the block overrun the budget (a 27-file
-    // repo overran a content-only budget by >1KB). Seed `used` with the wrapper
-    // so the final block is guaranteed ≤ byteBudget.
+    // (`--- path ---\n` + the `\n\n` join) and the fixed wrapper add up across many
+    // files, so a content-only budget lets the block overrun. Seeding `used` with
+    // the wrapper makes `Buffer.byteLength(block) <= byteBudget` an invariant.
     const HEADER = `PROJECT ORIENTATION (full contents of the project's core files — `
         + `already provided, do not re-read these)\n`;
     const TRAILER = '\n\n';

package/dist/task/owned-freeze-conflict.d.ts

@@ -9,13 +9,11 @@ export interface CategoryFreeze {
 /**
  * One unsatisfiable pair, keyed by the REQUIREMENT rather than by the path.
  *
- * Grouping matters for the resolution's size. mx5 run 18's TASK_0023 carries
- * two owned build-contract clauses that between them name three frozen paths;
- * per-path findings would demand three separate ownership grants (and the same
- * pair twice over, because that spec states its freeze in CONSTRAINTS and again
- * in ACCEPTANCE). Per requirement, the rewrite is told which files that one
- * obligation names and grants only what it needs — which is what keeps
- * `inv-no-spec-inflation` satisfiable at all.
+ * Grouping this way bounds the resolution. A requirement naming several frozen
+ * files would otherwise yield one finding per file, and a spec that states its
+ * freeze in CONSTRAINTS and again in ACCEPTANCE would yield each of those twice.
+ * Per requirement, the resolution is told which files that ONE obligation names
+ * and grants only what it needs.
  */
 export interface OwnedFreezeConflict {
     /** The owned requirement line, verbatim. */
@@ -55,14 +53,13 @@ export interface OwnedFreezeOptions {
     /**
      * Is this repo-relative token an existing SOURCE file of the tree the spec
      * will run against? Supplied by the caller (compose knows its cwd; the
-     * measured implementation is "tracked by git" — see `trackedSourceOracle`).
+     * usual implementation is "tracked by git" — see `trackedSourceOracle`).
      *
-     * Two false-positive classes die here, both observed at STEP 0 on the real
-     * TASK_0023 spec: route literals and build outputs (`/api`, `dist/`,
-     * `dist/app.css` — named by the very clause that is the true positive, but
-     * not files anyone can edit), and files a task is about to CREATE, which a
-     * freeze on the existing tree does not block. Omitted → every path-shaped
-     * token counts (the broad reading, reported alongside at STEP 0).
+     * Two false-positive classes die here: build outputs (`dist/app.css` — named
+     * by the same clause that names the real file, but not something anyone
+     * edits), and files a task is about to CREATE, which a freeze on the existing
+     * tree does not block. Omitted → every path-shaped token counts, which is the
+     * broad reading.
      */
     isSource?: (p: string) => boolean;
 }
@@ -75,7 +72,7 @@ export interface OwnedFreezeOptions {
  */
 export declare function findOwnedFreezeConflicts(spec: string | null | undefined, opts?: OwnedFreezeOptions): OwnedFreezeConflict[];
 /**
- * The measured `isSource` oracle: a token counts only when git tracks it in
+ * The production `isSource` oracle: a token counts only when git tracks it in
  * `cwd`. Tracked ⇒ it exists, it is not a build output, and it is not ignored —
  * exactly the "source file" the category freezes talk about. `git` missing or
  * the tree not a repo ⇒ every token counts (the broad reading), so the detector
@@ -86,10 +83,14 @@ export declare function trackedSourceOracle(lsFiles: (p: string) => {
     exitCode: number;
 }): (p: string) => boolean;
 /**
- * The forced critique-rewrite defect text, in the shape the existing four
- * families use: MANDATORY, self-contained, naming the exact resolutions. Prose
- * surrender and silently dropping the requirement are called out as
- * non-resolutions because narrowing the clause is precisely what run 16 did and
- * freezing its file is precisely what run 18 did.
+ * A forced-rewrite defect block in the shape the CRITIQUE_PROBES entries use:
+ * MANDATORY, self-contained, naming the exact resolutions. Prose surrender and
+ * silently dropping the requirement are called out as non-resolutions — narrowing
+ * the clause and freezing its file are both ways a rewrite makes the
+ * contradiction disappear without satisfying the requirement.
+ *
+ * UNWIRED. Nothing in src/ or test/ calls this. The shipped resolution is the
+ * DETACH in `owned-freeze-reassign.ts`, which needs no model rewrite; this text
+ * is what a rewrite-based resolution would say if one were ever added.
  */
 export declare function ownedFreezeConflictProbeText(conflicts: OwnedFreezeConflict[]): string;