@stravica-ai/digital-operator-pa 0.1.54 → 0.1.56

package/dist/engineering-pa-cli/src/coordinator-hook/config.mjs

@@ -20,7 +20,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
+import { resolveHome } from '../../../engineering-pa-core/src/home/resolve.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CORE_CONFIG_PATH = resolve(__dirname, '..', '..', 'config', 'coordinator-allowlist.json');
@@ -98,7 +98,7 @@ export function mergeOverlay(config, overlay, warnings = []) {
  * lives at `.claude/coordinator-overlay.json` under that directory.
  */
 export function overlayPaths({ repoRoot, cwd, env = process.env }) {
-  const home = env.HOME || homedir();
+  const home = resolveHome({ env });
   const workspaceBase = repoRoot || cwd;
   return {
     home: home ? join(home, '.claude', 'coordinator-overlay.json') : null,

package/dist/engineering-pa-cli/src/environment/probes.mjs

@@ -6,7 +6,7 @@
 import { execFile } from 'node:child_process';
 import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
 import { promisify } from 'node:util';
-import { arch, platform, release, homedir } from 'node:os';
+import { arch, platform, release } from 'node:os';
 import { basename, join, resolve, dirname } from 'node:path';
 import { resolve4 } from 'node:dns/promises';
 import { fileURLToPath } from 'node:url';

package/dist/engineering-pa-cli/src/pa/cli.mjs

@@ -67,6 +67,34 @@ export async function main(argv) {
     return 0;
   }
 
+  // 0.1.55 item 4 (w-2026-09-21-dave-004): `pa --version` / `pa -v`
+  // prints the installed package version. Before this landing there
+  // was no way to ask an installed CLI which version it was, so the
+  // 0.1.54 sweep had to `cat node_modules/.../package.json` by hand.
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    const { readFile } = await import('node:fs/promises');
+    const { fileURLToPath } = await import('node:url');
+    const { dirname: dn, join: jn } = await import('node:path');
+    try {
+      // packages/cli/src/pa/cli.mjs -> ../../..(three-up)/package.json
+      // works in-repo. The installed tarball layout resolves the
+      // package.json via the exports map added in this same release.
+      let pkgJson;
+      try {
+        pkgJson = await import('@stravica-ai/digital-operator-pa/package.json', { with: { type: 'json' } });
+      } catch {
+        const here = dn(fileURLToPath(import.meta.url));
+        const local = jn(here, '..', '..', '..', 'engineering-pa', 'package.json');
+        pkgJson = { default: JSON.parse(await readFile(local, 'utf8')) };
+      }
+      process.stdout.write((pkgJson.default?.version || 'unknown') + '\n');
+      return 0;
+    } catch (e) {
+      process.stderr.write(`[pa] failed to resolve version: ${e?.message || e}\n`);
+      return 1;
+    }
+  }
+
   const verb = argv[0];
   const rest = argv.slice(1);
 

package/dist/engineering-pa-cli/src/pa/projects.mjs

@@ -17,6 +17,7 @@ import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { getRepoRoot } from './repo-root.mjs';
+import { findRepoRootSync } from '../../../engineering-pa-core/src/instance-root/find.mjs';
 import { readJson, writeJson, ensureDir, listSubdirs, today } from './io.mjs';
 import { addDoc, removeDocByPath, setDocStatus, DEFAULT_GROUP, VALID_DOC_STATUSES } from './doc-groups.mjs';
 import { normaliseDocPath } from './doc-path.mjs';
@@ -111,6 +112,12 @@ export async function createProject(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  // 0.1.55 F1: refuse a project create from outside any operator instance
+  // with the strict findRepoRootSync error (exit 2, message naming the
+  // start directory and the markers walked). Keeps the failure shape
+  // aligned with pa work create and the scaffold write paths.
+  findRepoRootSync({ strict: true });
+
   const repoRoot = await getRepoRoot();
   const projDir = join(repoRoot, 'projects', opts.id);
   const projectJsonPath = join(projDir, 'project.json');

package/dist/engineering-pa-cli/src/pa/work-cli.mjs

@@ -19,10 +19,14 @@
 // fall-back-to-default case. Full rationale + tests in
 // `@stravica-ai/engineering-pa-core/src/workItemId/index.mjs`.
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
 import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
 
 import { createWork, setWorkStatus, listWork } from './work.mjs';
 import { getRepoRoot } from './repo-root.mjs';
+import { listSubdirs } from './io.mjs';
 
 const USAGE = `pa work — manage operator-repo work items
 
@@ -126,8 +130,49 @@ async function readPreferencesPaName() {
   }
 }
 
+// 0.1.55 item 4 (w-2026-09-21-dave-004): refuse unknown flags loudly.
+// The pre-0.1.55 parser silently dropped anything not consumed downstream,
+// so a typo like `--status` (only valid on `work status`) or an assumed
+// `--description` (there is no such flag; the field is `summary`) went
+// unnoticed and the created record was missing the value the operator
+// meant to set. Recorded as an incident in w-2026-09-21-dave-002's
+// summary.
+const CREATE_ALLOWED_FLAGS = new Set([
+  'project',
+  'title',
+  'category',
+  'priority',
+  'summary',
+  'owner',
+  'assignee',
+  'author',
+]);
+
 async function doCreate(args) {
   const { flags } = parseFlags(args);
+  const unknown = Object.keys(flags).filter((k) => !CREATE_ALLOWED_FLAGS.has(k));
+  if (unknown.length > 0) {
+    const list = unknown.map((k) => `--${k}`).join(', ');
+    const known = Array.from(CREATE_ALLOWED_FLAGS).map((k) => `--${k}`).sort().join(', ');
+    process.stderr.write(`[pa work create] unknown flag(s): ${list}\n`);
+    process.stderr.write(`  accepted flags: ${known}\n`);
+    return 1;
+  }
+  // Project existence gate (w-2026-09-30-dave-005 estate chore). Before this gate,
+  // `pa work create --project <nonexistent>` silently minted a work item pointing at
+  // a project that did not exist; the mistake surfaced later as an orphan in listings.
+  // Refuse loudly with the nearest matches so a typo is a fast fix, not a silent
+  // corruption. Only the CLI enforces this — programmatic callers of createWork()
+  // stay permissive (test fixtures use --project 'proj-a' without a real project on
+  // disk); wider grep found no CLI caller depending on the old behaviour, so no
+  // escape hatch is exposed.
+  if (typeof flags.project === 'string') {
+    const projectErr = await validateProjectExists(flags.project);
+    if (projectErr) {
+      process.stderr.write(projectErr);
+      return 1;
+    }
+  }
   const priority = flags.priority != null && flags.priority !== true
     ? Number(flags.priority)
     : null;
@@ -200,3 +245,100 @@ async function doList(args) {
   for (const r of rows) process.stdout.write(cols.map((c) => pad(r[c], widths[c])).join('  ') + '\n');
   return 0;
 }
+
+// ── project-existence validation (w-2026-09-30-dave-005 estate chore) ──────────
+
+/**
+ * Levenshtein distance between two short strings. Used to rank nearest project ids
+ * for a typo; not exported.
+ */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  const prev = new Array(b.length + 1);
+  const curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j += 1) prev[j] = j;
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    for (let j = 0; j <= b.length; j += 1) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}
+
+/**
+ * List every projects/<id>/ whose project.json exists on disk. Names only, sorted
+ * lexicographically. Empty when the projects/ dir is absent (accepted by listSubdirs).
+ */
+async function listExistingProjectIds() {
+  const repoRoot = await getRepoRoot();
+  const projectsDir = join(repoRoot, 'projects');
+  const subdirs = await listSubdirs(projectsDir);
+  const ids = [];
+  for (const name of subdirs) {
+    if (existsSync(join(projectsDir, name, 'project.json'))) ids.push(name);
+  }
+  ids.sort();
+  return ids;
+}
+
+/**
+ * Nearest candidates for a missing project id: substring matches first (both
+ * directions), then the closest by Levenshtein distance (up to length/2 + 1). At
+ * most 5 suggestions; sorted deterministically.
+ */
+function nearestProjectMatches(target, candidates, max = 5) {
+  const seen = new Set();
+  const out = [];
+  const push = (id) => { if (!seen.has(id)) { seen.add(id); out.push(id); } };
+  for (const id of candidates) {
+    if (id.toLowerCase().includes(target.toLowerCase()) || target.toLowerCase().includes(id.toLowerCase())) {
+      push(id);
+    }
+    if (out.length >= max) break;
+  }
+  if (out.length < max) {
+    const threshold = Math.max(1, Math.floor(target.length / 2) + 1);
+    const scored = candidates
+      .filter((id) => !seen.has(id))
+      .map((id) => ({ id, d: levenshtein(target.toLowerCase(), id.toLowerCase()) }))
+      .filter((r) => r.d <= threshold)
+      .sort((a, b) => a.d - b.d || a.id.localeCompare(b.id));
+    for (const { id } of scored) {
+      push(id);
+      if (out.length >= max) break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Returns null when the project id resolves to an existing project.json on disk, or
+ * a preformatted stderr message (with trailing newline) when it does not. Split so
+ * doCreate can print + return exit 1 without repeating the plumbing.
+ */
+async function validateProjectExists(projectId) {
+  const repoRoot = await getRepoRoot();
+  const path = join(repoRoot, 'projects', projectId, 'project.json');
+  if (existsSync(path)) return null;
+  let candidates = [];
+  try { candidates = await listExistingProjectIds(); } catch { candidates = []; }
+  const nearest = nearestProjectMatches(projectId, candidates);
+  const lines = [`[pa work create] unknown project: ${projectId}`];
+  lines.push(`  expected projects/${projectId}/project.json on disk (not found)`);
+  if (nearest.length) {
+    lines.push(`  did you mean: ${nearest.join(', ')}`);
+  } else if (candidates.length) {
+    lines.push(`  existing projects: ${candidates.slice(0, 10).join(', ')}${candidates.length > 10 ? ', ...' : ''}`);
+  } else {
+    lines.push('  no projects on disk yet — create one with `pa project create` first');
+  }
+  return lines.map((l) => `${l}\n`).join('');
+}
+
+// Exported for tests only — pure helpers, no filesystem side-effects.
+export const __testables = { levenshtein, nearestProjectMatches };

package/dist/engineering-pa-cli/src/pa/work.mjs

@@ -25,6 +25,7 @@ import {
   maxNForAuthorOnDate,
 } from '../../../engineering-pa-core/src/workItemId/index.mjs';
 
+import { findRepoRootSync } from '../../../engineering-pa-core/src/instance-root/find.mjs';
 import { getRepoRoot } from './repo-root.mjs';
 import {
   readJson,
@@ -128,6 +129,14 @@ export async function createWork(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  // 0.1.55 F1: refuse a mint from outside any operator instance BEFORE the
+  // author-token check. Pre-fix the flow bailed with the author-token error
+  // (exit 1), which read as a config problem in the caller's terminal; the
+  // real cause is that the cwd carries none of the instance markers. Strict
+  // findRepoRootSync throws with exit 2 and names both the start directory
+  // and the markers walked, matching the sibling rule in projects.mjs.
+  findRepoRootSync({ strict: true });
+
   let author;
   try {
     author = resolveAuthorToken({

package/dist/engineering-pa-cli/src/research/engine/finalise.mjs

@@ -134,9 +134,13 @@ export async function degradedSynthAgent(ctx, sq, reason) {
 
 // Pure coverage computation. Given the planner's sub-question ids and the synth
 // receipts, decide which SQs have a finding (any receipt with written=true), which ran
-// as a degraded write (empty finding, still counted as covered), and which are wholly
-// uncovered (no receipt at all — the failure this gate exists to catch). Used by the
-// wrapper to fail loudly instead of silently reporting status='done' on a partial run.
+// as a degraded write (empty finding, covered on disk but zero surviving claims), and
+// which are wholly uncovered (no receipt at all). `complete` is true only when every
+// planned SQ has a receipt AND every receipt carries at least one claim — a degraded
+// zero-claim finding is a coverage gap the wrapper must surface (status='partial'),
+// not silently mark done (w-2026-09-30-dave-005). The wrapper still distinguishes the
+// two failure modes: uncovered aborts finalise; degraded lets the answer.md be
+// written and returns status='partial' with the degraded[] list.
 export function coverageReport(subQuestionIds, synthReceipts) {
   const receiptsBySq = new Map();
   for (const r of synthReceipts || []) {
@@ -152,7 +156,13 @@ export function coverageReport(subQuestionIds, synthReceipts) {
     covered.push(id);
     if ((r.claimCount || 0) === 0) degraded.push(id);
   }
-  return { planned, covered, degraded, uncovered, complete: uncovered.length === 0 };
+  return {
+    planned,
+    covered,
+    degraded,
+    uncovered,
+    complete: uncovered.length === 0 && degraded.length === 0,
+  };
 }
 
 // -- Finalise (persist gate records, write sources.json + the session answer, round-trip, mark done) --

package/dist/engineering-pa-cli/src/research/workflows/research-deep.js

@@ -1,6 +1,6 @@
 // GENERATED by assemble.mjs — DO NOT EDIT. Edit wrappers/deep.mjs + engine/*.mjs and re-run `pnpm assemble`.
 // sources: wrappers/deep.mjs, engine/io.mjs, engine/plan.mjs, engine/agents.mjs, engine/finalise.mjs, engine/rank.mjs, engine/verify.mjs, engine/deepen.mjs, engine/deep.mjs
-// contentHash: sha256:cbdbff5d260df77a3b56a60d37bd75a58f0fa38968dbd0f0181c71fb6d8b3d29
+// contentHash: sha256:b7c50f3547c79b4c63bb54f14d1c0675a9af3a1c871d7866050cd22ff3d28fb5
 
 export const meta = {
   name: 'research-deep',
@@ -511,9 +511,13 @@ async function degradedSynthAgent(ctx, sq, reason) {
 
 // Pure coverage computation. Given the planner's sub-question ids and the synth
 // receipts, decide which SQs have a finding (any receipt with written=true), which ran
-// as a degraded write (empty finding, still counted as covered), and which are wholly
-// uncovered (no receipt at all — the failure this gate exists to catch). Used by the
-// wrapper to fail loudly instead of silently reporting status='done' on a partial run.
+// as a degraded write (empty finding, covered on disk but zero surviving claims), and
+// which are wholly uncovered (no receipt at all). `complete` is true only when every
+// planned SQ has a receipt AND every receipt carries at least one claim — a degraded
+// zero-claim finding is a coverage gap the wrapper must surface (status='partial'),
+// not silently mark done (w-2026-09-30-dave-005). The wrapper still distinguishes the
+// two failure modes: uncovered aborts finalise; degraded lets the answer.md be
+// written and returns status='partial' with the degraded[] list.
 function coverageReport(subQuestionIds, synthReceipts) {
   const receiptsBySq = new Map();
   for (const r of synthReceipts || []) {
@@ -529,7 +533,13 @@ function coverageReport(subQuestionIds, synthReceipts) {
     covered.push(id);
     if ((r.claimCount || 0) === 0) degraded.push(id);
   }
-  return { planned, covered, degraded, uncovered, complete: uncovered.length === 0 };
+  return {
+    planned,
+    covered,
+    degraded,
+    uncovered,
+    complete: uncovered.length === 0 && degraded.length === 0,
+  };
 }
 
 // -- Finalise (persist gate records, write sources.json + the session answer, round-trip, mark done) --

package/dist/engineering-pa-cli/src/research/workflows/research-normal.js

@@ -1,6 +1,6 @@
 // GENERATED by assemble.mjs — DO NOT EDIT. Edit wrappers/normal.mjs + engine/*.mjs and re-run `pnpm assemble`.
 // sources: wrappers/normal.mjs, engine/io.mjs, engine/plan.mjs, engine/agents.mjs, engine/finalise.mjs, engine/rank.mjs, engine/verify.mjs, engine/deepen.mjs
-// contentHash: sha256:579795fe41f91c096a6894492e6e0e0291b9ada32aff3ed81b5c31213c51335d
+// contentHash: sha256:9ea786a5296dd54d14bbc662d1d47a87f437829fc5d394c3a83dd64f65ff1236
 
 export const meta = {
   name: 'research-normal',
@@ -510,9 +510,13 @@ async function degradedSynthAgent(ctx, sq, reason) {
 
 // Pure coverage computation. Given the planner's sub-question ids and the synth
 // receipts, decide which SQs have a finding (any receipt with written=true), which ran
-// as a degraded write (empty finding, still counted as covered), and which are wholly
-// uncovered (no receipt at all — the failure this gate exists to catch). Used by the
-// wrapper to fail loudly instead of silently reporting status='done' on a partial run.
+// as a degraded write (empty finding, covered on disk but zero surviving claims), and
+// which are wholly uncovered (no receipt at all). `complete` is true only when every
+// planned SQ has a receipt AND every receipt carries at least one claim — a degraded
+// zero-claim finding is a coverage gap the wrapper must surface (status='partial'),
+// not silently mark done (w-2026-09-30-dave-005). The wrapper still distinguishes the
+// two failure modes: uncovered aborts finalise; degraded lets the answer.md be
+// written and returns status='partial' with the degraded[] list.
 function coverageReport(subQuestionIds, synthReceipts) {
   const receiptsBySq = new Map();
   for (const r of synthReceipts || []) {
@@ -528,7 +532,13 @@ function coverageReport(subQuestionIds, synthReceipts) {
     covered.push(id);
     if ((r.claimCount || 0) === 0) degraded.push(id);
   }
-  return { planned, covered, degraded, uncovered, complete: uncovered.length === 0 };
+  return {
+    planned,
+    covered,
+    degraded,
+    uncovered,
+    complete: uncovered.length === 0 && degraded.length === 0,
+  };
 }
 
 // -- Finalise (persist gate records, write sources.json + the session answer, round-trip, mark done) --
@@ -823,7 +833,14 @@ async function runDeepenRound(ctx, state, { lenses = VERIFY_LENSES, quorum = 2,
 // the parent session's 200/200 WebSearch budget — the tools shipped in agents.mjs are
 // the same tool surface the parent uses, so caps have to leave headroom).
 const NORMAL_SEARCH_TOOL_CAP = 12; // matches agents.searchAgent default
-const NORMAL_CLAIM_BUDGET = 25;    // matches rankAndCap call below
+const NORMAL_CLAIM_BUDGET = 25;    // matches rankAndCapPerSq call below
+// Per-sub-question retention floor for normal mode (w-2026-09-30-dave-005). Sessions
+// 01M3S5PXQTCZR70MGDQRZWN6ZM (4 SQs, sq-3/sq-4 zero-claim, budgetDropped 56, 5.47M
+// tokens) and 01M3S55WDKSYSC7Z7S8VRRJ9PC (6 SQs, sq-3/sq-4 zero-claim, budgetDropped
+// 75, 10.97M tokens) both had later sub-questions silently starved by the earlier
+// global rankAndCap cap while coverage.complete still reported true. Floor is the
+// same "top-1 per SQ" guarantee deep already uses (DEEP_RETAIN_FLOOR_PER_SQ).
+const NORMAL_RETAIN_FLOOR_PER_SQ = 1;
 function normalWebSearchCeiling(subQuestionCount, centralClaimCount) {
   const searchers = subQuestionCount * NORMAL_SEARCH_TOOL_CAP;
   const verifiers = centralClaimCount * VERIFY_LENSES.length * VERIFY_TOOL_CALL_CAP_DEFAULT;
@@ -847,10 +864,19 @@ phase('Search');
 const sqResults = await runSearchExtract(ctx, subQuestions);
 
 // -- Rank + budget cap (deterministic code — §4.1) --
+// Per-SQ floor applied BEFORE global trimming (w-2026-09-30-dave-005): reserve at
+// least NORMAL_RETAIN_FLOOR_PER_SQ retained claim(s) per sub-question that had any
+// claim extracted, then fill the remainder by global rank. A pure global cap starves
+// later sub-questions silently (they end with zero retained claims, hence a degraded
+// finding) while the wrapper still marks done.
 const urlBySourceId = new Map();
 const allClaims = flattenClaims(sqResults, urlBySourceId);
-const { retained, extractedCount, budgetDropped } = rankAndCap(allClaims, NORMAL_CLAIM_BUDGET); // CLAIM_BUDGET 25 (harness-skill cap)
-log(`extracted ${extractedCount} claims; retained ${retained.length} (budgetDropped ${budgetDropped})`);
+const { retained, extractedCount, budgetDropped } = rankAndCapPerSq(
+  allClaims,
+  NORMAL_CLAIM_BUDGET, // 25 (harness-skill cap)
+  { floorPerSq: NORMAL_RETAIN_FLOOR_PER_SQ },
+);
+log(`extracted ${extractedCount} claims; retained ${retained.length} (budgetDropped ${budgetDropped}, floorPerSq ${NORMAL_RETAIN_FLOOR_PER_SQ})`);
 
 // -- Verify (3-vote adversarial on central claims only — §4 normal row) --
 phase('Verify');
@@ -877,10 +903,16 @@ phase('Synthesize');
 const synthReceipts = await runSynth(ctx, subQuestions, retained, verdictByClaimId);
 
 // -- Coverage gate --
-// Fail loudly when a planned sub-question has no findings receipt. Before this gate
-// normal returned status='done' on 4-SQ plans that only synthesised 2 of them.
+// Two failure modes, handled separately (w-2026-09-30-dave-005):
+//   1. UNCOVERED — a planned SQ has no findings receipt at all. Abort finalise; no
+//      answer.md written; status='partial'. This is the original gate.
+//   2. DEGRADED — every SQ has a receipt but one or more carry zero surviving claims
+//      (the per-SQ floor kicks in for the extractor pool, but verify/dedupe may still
+//      leave an SQ empty). Let finalise run so answer.md is written, then override the
+//      returned status to 'partial' and surface the degraded[] list. Do NOT mark done
+//      — a partial run is not a done run.
 const coverage = coverageReport(subQuestions.map((s) => s.id), synthReceipts);
-if (!coverage.complete) {
+if (coverage.uncovered.length) {
   log(`ABORT: coverage gap — ${coverage.uncovered.length} of ${coverage.planned} sub-question(s) have no findings receipt: [${coverage.uncovered.join(', ')}]. Not marking done.`);
   return {
     sessionId: ctx.sessionId,
@@ -891,7 +923,7 @@ if (!coverage.complete) {
   };
 }
 if (coverage.degraded.length) {
-  log(`coverage: ${coverage.covered.length}/${coverage.planned} covered, ${coverage.degraded.length} degraded (zero-claim finding): [${coverage.degraded.join(', ')}]`);
+  log(`coverage: ${coverage.covered.length}/${coverage.planned} covered, ${coverage.degraded.length} degraded (zero-claim finding): [${coverage.degraded.join(', ')}] — run will return status='partial'`);
 } else {
   log(`coverage: ${coverage.covered.length}/${coverage.planned} covered, all with substantive findings`);
 }
@@ -905,6 +937,12 @@ const unsourcedRatio = totalClaimCount ? totalUnsourced / totalClaimCount : 0;
 const sourcesJson = buildSourcesJson(sqResults);
 const gateRecords = buildGateRecords(sqResults);
 
+// Subagent token cost — surfaced in runStats + the returned summary so an operator can
+// see what a normal-mode session actually spent, without opening the harness manifest
+// (w-2026-09-30-dave-005). Same shape deep uses.
+const outputTokensSpent = (typeof budget !== 'undefined' && budget && budget.spent) ? budget.spent() : 0;
+const budgetTotal = (typeof budget !== 'undefined' && budget && budget.total != null) ? budget.total : null;
+
 const runStats = {
   extracted: extractedCount, central: centralClaims.length,
   confirmed: confirmedN, refuted: refutedN, unverifiedInfra: infraN,
@@ -913,6 +951,8 @@ const runStats = {
   gatedDropped: gateRecords.length,
   coverage,
   webSearchCeiling: ceilingUpperBound,
+  outputTokensSpent,
+  budgetTotal,
 };
 
 if (unsourcedRatio > UNSOURCED_ABORT_RATIO) {
@@ -924,12 +964,18 @@ if (unsourcedRatio > UNSOURCED_ABORT_RATIO) {
 phase('Finalise');
 const finalise = await runFinalise(ctx, { gateRecords, sourcesJson, runStats });
 
-const status = finalise.markedDone ? 'done' : 'in-progress';
-log(`finalise: sources=${finalise.wroteSources} answer=${finalise.wroteAnswer} roundTrip=${finalise.roundTripOk} markedDone=${finalise.markedDone} gatesAppended=${finalise.gatesAppended ?? 0}/${gateRecords.length}`);
+// A degraded run reports 'partial' regardless of the finaliser's markedDone flag —
+// the answer.md is written and the session may be marked done in the store, but the
+// returned summary tells the caller a sub-question was not answered
+// (w-2026-09-30-dave-005). coverage.complete is already false in that case.
+const baseStatus = finalise.markedDone ? 'done' : 'in-progress';
+const status = coverage.degraded.length ? 'partial' : baseStatus;
+log(`finalise: sources=${finalise.wroteSources} answer=${finalise.wroteAnswer} roundTrip=${finalise.roundTripOk} markedDone=${finalise.markedDone} gatesAppended=${finalise.gatesAppended ?? 0}/${gateRecords.length} status=${status}`);
 
 return {
   sessionId: ctx.sessionId,
   status,
+  ...(coverage.degraded.length ? { reason: `${coverage.degraded.length} sub-question(s) with zero surviving claims`, degraded: coverage.degraded } : {}),
   question: ctx.baseQuestion,
   outputMode: ctx.baseOutputMode,
   subQuestions: subQuestions.map((s) => ({ id: s.id, text: s.text, kind: s.kind })),

package/dist/engineering-pa-cli/src/research/wrappers/normal.mjs

@@ -4,7 +4,7 @@
 import { deriveContext } from '../engine/io.mjs';
 import { runPlan } from '../engine/plan.mjs';
 import { runSearchExtract } from '../engine/agents.mjs';
-import { flattenClaims, rankAndCap } from '../engine/rank.mjs';
+import { flattenClaims, rankAndCapPerSq } from '../engine/rank.mjs';
 import { runVerify, VERIFY_LENSES, VERIFY_TOOL_CALL_CAP_DEFAULT } from '../engine/verify.mjs';
 import { runDeepenRound } from '../engine/deepen.mjs';
 import { UNSOURCED_ABORT_RATIO, buildSourcesJson, buildGateRecords, runSynth, runFinalise, coverageReport } from '../engine/finalise.mjs';
@@ -16,7 +16,14 @@ import { UNSOURCED_ABORT_RATIO, buildSourcesJson, buildGateRecords, runSynth, ru
 // the parent session's 200/200 WebSearch budget — the tools shipped in agents.mjs are
 // the same tool surface the parent uses, so caps have to leave headroom).
 const NORMAL_SEARCH_TOOL_CAP = 12; // matches agents.searchAgent default
-const NORMAL_CLAIM_BUDGET = 25;    // matches rankAndCap call below
+const NORMAL_CLAIM_BUDGET = 25;    // matches rankAndCapPerSq call below
+// Per-sub-question retention floor for normal mode (w-2026-09-30-dave-005). Sessions
+// 01M3S5PXQTCZR70MGDQRZWN6ZM (4 SQs, sq-3/sq-4 zero-claim, budgetDropped 56, 5.47M
+// tokens) and 01M3S55WDKSYSC7Z7S8VRRJ9PC (6 SQs, sq-3/sq-4 zero-claim, budgetDropped
+// 75, 10.97M tokens) both had later sub-questions silently starved by the earlier
+// global rankAndCap cap while coverage.complete still reported true. Floor is the
+// same "top-1 per SQ" guarantee deep already uses (DEEP_RETAIN_FLOOR_PER_SQ).
+const NORMAL_RETAIN_FLOOR_PER_SQ = 1;
 function normalWebSearchCeiling(subQuestionCount, centralClaimCount) {
   const searchers = subQuestionCount * NORMAL_SEARCH_TOOL_CAP;
   const verifiers = centralClaimCount * VERIFY_LENSES.length * VERIFY_TOOL_CALL_CAP_DEFAULT;
@@ -54,10 +61,19 @@ phase('Search');
 const sqResults = await runSearchExtract(ctx, subQuestions);
 
 // -- Rank + budget cap (deterministic code — §4.1) --
+// Per-SQ floor applied BEFORE global trimming (w-2026-09-30-dave-005): reserve at
+// least NORMAL_RETAIN_FLOOR_PER_SQ retained claim(s) per sub-question that had any
+// claim extracted, then fill the remainder by global rank. A pure global cap starves
+// later sub-questions silently (they end with zero retained claims, hence a degraded
+// finding) while the wrapper still marks done.
 const urlBySourceId = new Map();
 const allClaims = flattenClaims(sqResults, urlBySourceId);
-const { retained, extractedCount, budgetDropped } = rankAndCap(allClaims, NORMAL_CLAIM_BUDGET); // CLAIM_BUDGET 25 (harness-skill cap)
-log(`extracted ${extractedCount} claims; retained ${retained.length} (budgetDropped ${budgetDropped})`);
+const { retained, extractedCount, budgetDropped } = rankAndCapPerSq(
+  allClaims,
+  NORMAL_CLAIM_BUDGET, // 25 (harness-skill cap)
+  { floorPerSq: NORMAL_RETAIN_FLOOR_PER_SQ },
+);
+log(`extracted ${extractedCount} claims; retained ${retained.length} (budgetDropped ${budgetDropped}, floorPerSq ${NORMAL_RETAIN_FLOOR_PER_SQ})`);
 
 // -- Verify (3-vote adversarial on central claims only — §4 normal row) --
 phase('Verify');
@@ -84,10 +100,16 @@ phase('Synthesize');
 const synthReceipts = await runSynth(ctx, subQuestions, retained, verdictByClaimId);
 
 // -- Coverage gate --
-// Fail loudly when a planned sub-question has no findings receipt. Before this gate
-// normal returned status='done' on 4-SQ plans that only synthesised 2 of them.
+// Two failure modes, handled separately (w-2026-09-30-dave-005):
+//   1. UNCOVERED — a planned SQ has no findings receipt at all. Abort finalise; no
+//      answer.md written; status='partial'. This is the original gate.
+//   2. DEGRADED — every SQ has a receipt but one or more carry zero surviving claims
+//      (the per-SQ floor kicks in for the extractor pool, but verify/dedupe may still
+//      leave an SQ empty). Let finalise run so answer.md is written, then override the
+//      returned status to 'partial' and surface the degraded[] list. Do NOT mark done
+//      — a partial run is not a done run.
 const coverage = coverageReport(subQuestions.map((s) => s.id), synthReceipts);
-if (!coverage.complete) {
+if (coverage.uncovered.length) {
   log(`ABORT: coverage gap — ${coverage.uncovered.length} of ${coverage.planned} sub-question(s) have no findings receipt: [${coverage.uncovered.join(', ')}]. Not marking done.`);
   return {
     sessionId: ctx.sessionId,
@@ -98,7 +120,7 @@ if (!coverage.complete) {
   };
 }
 if (coverage.degraded.length) {
-  log(`coverage: ${coverage.covered.length}/${coverage.planned} covered, ${coverage.degraded.length} degraded (zero-claim finding): [${coverage.degraded.join(', ')}]`);
+  log(`coverage: ${coverage.covered.length}/${coverage.planned} covered, ${coverage.degraded.length} degraded (zero-claim finding): [${coverage.degraded.join(', ')}] — run will return status='partial'`);
 } else {
   log(`coverage: ${coverage.covered.length}/${coverage.planned} covered, all with substantive findings`);
 }
@@ -112,6 +134,12 @@ const unsourcedRatio = totalClaimCount ? totalUnsourced / totalClaimCount : 0;
 const sourcesJson = buildSourcesJson(sqResults);
 const gateRecords = buildGateRecords(sqResults);
 
+// Subagent token cost — surfaced in runStats + the returned summary so an operator can
+// see what a normal-mode session actually spent, without opening the harness manifest
+// (w-2026-09-30-dave-005). Same shape deep uses.
+const outputTokensSpent = (typeof budget !== 'undefined' && budget && budget.spent) ? budget.spent() : 0;
+const budgetTotal = (typeof budget !== 'undefined' && budget && budget.total != null) ? budget.total : null;
+
 const runStats = {
   extracted: extractedCount, central: centralClaims.length,
   confirmed: confirmedN, refuted: refutedN, unverifiedInfra: infraN,
@@ -120,6 +148,8 @@ const runStats = {
   gatedDropped: gateRecords.length,
   coverage,
   webSearchCeiling: ceilingUpperBound,
+  outputTokensSpent,
+  budgetTotal,
 };
 
 if (unsourcedRatio > UNSOURCED_ABORT_RATIO) {
@@ -131,12 +161,18 @@ if (unsourcedRatio > UNSOURCED_ABORT_RATIO) {
 phase('Finalise');
 const finalise = await runFinalise(ctx, { gateRecords, sourcesJson, runStats });
 
-const status = finalise.markedDone ? 'done' : 'in-progress';
-log(`finalise: sources=${finalise.wroteSources} answer=${finalise.wroteAnswer} roundTrip=${finalise.roundTripOk} markedDone=${finalise.markedDone} gatesAppended=${finalise.gatesAppended ?? 0}/${gateRecords.length}`);
+// A degraded run reports 'partial' regardless of the finaliser's markedDone flag —
+// the answer.md is written and the session may be marked done in the store, but the
+// returned summary tells the caller a sub-question was not answered
+// (w-2026-09-30-dave-005). coverage.complete is already false in that case.
+const baseStatus = finalise.markedDone ? 'done' : 'in-progress';
+const status = coverage.degraded.length ? 'partial' : baseStatus;
+log(`finalise: sources=${finalise.wroteSources} answer=${finalise.wroteAnswer} roundTrip=${finalise.roundTripOk} markedDone=${finalise.markedDone} gatesAppended=${finalise.gatesAppended ?? 0}/${gateRecords.length} status=${status}`);
 
 return {
   sessionId: ctx.sessionId,
   status,
+  ...(coverage.degraded.length ? { reason: `${coverage.degraded.length} sub-question(s) with zero surviving claims`, degraded: coverage.degraded } : {}),
   question: ctx.baseQuestion,
   outputMode: ctx.baseOutputMode,
   subQuestions: subQuestions.map((s) => ({ id: s.id, text: s.text, kind: s.kind })),