@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/research/commands/mark.mjs

@@ -0,0 +1,97 @@
+// research mark <done|aborted> <sessionId> [--no-promote | --promote]
+//
+// Set a terminal status on a session: `done` (finalised) or `aborted` (abandoned,
+// e.g. the workflow's >10%-unsourced guardrail). The only verb that mutates an
+// existing session's status, and both transitions are one-way — a session already
+// terminal (done/aborted) is refused (exit 2).
+//
+// The status write goes through the store chokepoint (store.updateManifestStatus),
+// which reads → guards the terminal transition → validates → persists.
+//
+// On `mark done` for a NORMAL or DEEP session we then promote answer.md into the
+// operator knowledge library (w-021). Promotion NEVER fails the mark: the status
+// is already `done` on disk before we touch the library, and promotion skips (with
+// a note where relevant) rather than throwing on expected conditions. Light mode
+// is never promoted — `--promote` on light is a usage error (exit 1). `--no-promote`
+// skips promotion on normal/deep with a one-line note. `mark aborted` never promotes.
+import { parseArgs } from 'node:util';
+import { getDefaultStore } from '../store/index.mjs';
+import { decidePromotion, promoteSession, refreshHint } from '../promote.mjs';
+
+const SUBVERBS = ['done', 'aborted'];
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research mark <done|aborted> <sessionId> [--no-promote | --promote]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+
+export async function markCommand(argv, { store, now = Date.now, stdout = process.stdout, promote = promoteSession, knowledgeDir } = {}) {
+  if (!store) store = await getDefaultStore();
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        'no-promote': { type: 'boolean' },
+        promote: { type: 'boolean' },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const [subverb, id, ...extra] = parsed.positionals;
+  const noPromote = parsed.values['no-promote'] === true;
+  const forcePromote = parsed.values.promote === true;
+
+  if (!subverb) throw usage('a sub-verb is required (one of "done" or "aborted")');
+  if (!SUBVERBS.includes(subverb)) throw usage(`unknown sub-verb "${subverb}" (one of "done" or "aborted")`);
+  if (!id) throw usage('a <sessionId> is required');
+  if (extra.length) throw usage('too many arguments');
+  if (noPromote && forcePromote) throw usage('--no-promote and --promote are mutually exclusive');
+  if (!store.isValidSessionId(id)) throw usage(`"${id}" is not a valid sessionId`);
+
+  // The promotion decision reads the session's mode; peek at the manifest BEFORE
+  // mutating so that a `--promote` on a light session errors out (exit 1) WITHOUT
+  // having already flipped the status. Missing/malformed session → exit 2 here,
+  // same as updateManifestStatus would have surfaced.
+  if (subverb === 'done') {
+    const current = await store.readManifest(id);
+    // Throws exit 1 for the light + --promote hard-rule violation. `status` is
+    // the post-transition status (done) since that is what we are about to set.
+    decidePromotion({ mode: current.mode, status: 'done', noPromote, promote: forcePromote });
+  }
+
+  const nowIso = new Date(now()).toISOString();
+  // The sub-verb IS the target terminal status. Missing session → exit 2 (not
+  // found); already terminal → exit 2 (refused, one-way transition). This is the
+  // idempotency backstop: `mark done` on an already-done session is refused here,
+  // so promotion can never double-write.
+  const updated = await store.updateManifestStatus(id, subverb, nowIso);
+  stdout.write(`marked ${id} ${subverb} (updatedAt ${updated.updatedAt})\n`);
+
+  if (subverb !== 'done') return 0;
+
+  const decision = decidePromotion({ mode: updated.mode, status: updated.status, noPromote, promote: forcePromote });
+  if (decision.action === 'skip-silent') return 0; // light → silent by design
+  if (decision.action === 'skip-note') {
+    stdout.write(`  --no-promote set — skipped knowledge-library promotion\n`);
+    return 0;
+  }
+
+  // action === 'promote' (normal/deep). Never fatal: report skips/errors as a
+  // note and still return success, since the session is already `done`.
+  try {
+    const result = await promote(id, { store, knowledgeDir });
+    if (result.status === 'promoted') {
+      stdout.write(`  ${refreshHint(result.path)}\n`);
+    } else if (result.status === 'already-promoted') {
+      stdout.write(`  already promoted to ${result.path} — no change\n`);
+    } else if (result.status === 'skipped-no-answer') {
+      stdout.write(`  ${result.reason}\n`);
+    }
+  } catch (e) {
+    stdout.write(`  promotion failed (non-fatal): ${e && e.message ? e.message : e}\n`);
+  }
+  return 0;
+}

package/dist/engineering-pa-cli/src/research/commands/paths.mjs

@@ -0,0 +1,69 @@
+// research paths [--json]
+//
+// Emit the absolute paths the /research skill and the workflow scripts
+// consume, resolved against the operator repo root and this package's install
+// location:
+//
+//   sessionsDir   — where session dirs live (default: <repoRoot>/.cache/research/sessions)
+//   briefsDir     — dispatch briefs the workflow feeds to searcher/extractor/…
+//   workflowsDir  — the workflow scripts themselves (research-normal.js et al.)
+//   schemaDir     — JSON schemas for manifest/plan/finding/sources/gates
+//   cli           — the invocation prefix the workflow uses to run this CLI
+//                    from a subagent (`pnpm exec research`)
+//
+// The /research skill calls this once at the top of a session and interpolates
+// the values into the Workflow dispatch args, so nothing on the skill side has
+// to know where the package is installed. `pa knowledge`-style JSON contract.
+//
+// Exit codes: 0 ok, 1 usage, 3 transport/IO (repo-root resolution failure surfaces
+// with its own exitCode via getRepoRoot()).
+import { parseArgs } from 'node:util';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultSessionsDir } from '../store/index.mjs';
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research paths [--json]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+
+// The research package's own root — briefs/ and workflows/ ship inside it.
+// commands/paths.mjs → ../ = src/research/. Resolved from import.meta.url so
+// the answer is right whether the tool is running from the source tree, from
+// dist/ under a published package, or from a symlinked pnpm workspace.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+
+export async function resolvePaths() {
+  return {
+    sessionsDir: await defaultSessionsDir(),
+    briefsDir: join(PACKAGE_ROOT, 'briefs'),
+    workflowsDir: join(PACKAGE_ROOT, 'workflows'),
+    schemaDir: join(PACKAGE_ROOT, 'schema'),
+    cli: 'pnpm exec research',
+  };
+}
+
+export async function pathsCommand(argv, { stdout = process.stdout } = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: { json: { type: 'boolean' } },
+      allowPositionals: false,
+      strict: true,
+    });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const paths = await resolvePaths();
+  if (parsed.values.json) {
+    stdout.write(JSON.stringify(paths, null, 2) + '\n');
+    return 0;
+  }
+  stdout.write(`sessionsDir:  ${paths.sessionsDir}\n`);
+  stdout.write(`briefsDir:    ${paths.briefsDir}\n`);
+  stdout.write(`workflowsDir: ${paths.workflowsDir}\n`);
+  stdout.write(`schemaDir:    ${paths.schemaDir}\n`);
+  stdout.write(`cli:          ${paths.cli}\n`);
+  return 0;
+}

package/dist/engineering-pa-cli/src/research/commands/prune.mjs

@@ -0,0 +1,86 @@
+// research prune [--older-than <days>] [--status <status>] [--dry-run]
+//
+// Deletes sessions older than N days AND/OR matching a status (filters AND
+// together). At least one filter is required — a bare `prune` is a usage error
+// so a fat-fingered command can never wipe every session. --dry-run previews.
+// An explicit filter that matches nothing exits 2 (operational).
+import { parseArgs } from 'node:util';
+import { getDefaultStore } from '../store/index.mjs';
+import { STATUSES } from '../store/manifest.mjs';
+import { table, truncate } from '../format.mjs';
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research prune [--older-than <days>] [--status <${STATUSES.join('|')}>] [--dry-run]  (at least one filter required)${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+
+const DAY_MS = 86_400_000;
+
+// PURE: choose which sessions to prune. `sessions` is the listSessions() shape
+// (each { id, manifest, error }). A session matches only if it satisfies EVERY
+// provided filter. Malformed sessions (no manifest) are never matched — we won't
+// delete what we can't evaluate. `nowMs` is injected for testability.
+export function selectPruneTargets(sessions, { olderThanDays, status, nowMs }) {
+  const cutoff = olderThanDays != null ? nowMs - olderThanDays * DAY_MS : null;
+  return sessions.filter((s) => {
+    if (!s.manifest) return false;
+    if (status != null && s.manifest.status !== status) return false;
+    if (cutoff != null) {
+      const created = Date.parse(s.manifest.createdAt);
+      if (Number.isNaN(created) || created >= cutoff) return false;
+    }
+    return true;
+  });
+}
+
+export async function pruneCommand(argv, { store, now = Date.now, stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (!store) store = await getDefaultStore();
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        'older-than': { type: 'string' },
+        status: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      allowPositionals: false,
+      strict: true,
+    });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const v = parsed.values;
+
+  const hasAge = v['older-than'] != null;
+  const hasStatus = v.status != null;
+  if (!hasAge && !hasStatus) throw usage('provide --older-than and/or --status');
+
+  let olderThanDays;
+  if (hasAge) {
+    olderThanDays = Number(v['older-than']);
+    if (!Number.isInteger(olderThanDays) || olderThanDays < 0) throw usage('--older-than must be a non-negative integer (days)');
+  }
+  if (hasStatus && !STATUSES.includes(v.status)) throw usage(`--status must be one of ${STATUSES.join(' | ')}`);
+
+  const sessions = await store.listSessions();
+  const targets = selectPruneTargets(sessions, { olderThanDays, status: v.status, nowMs: now() });
+
+  if (targets.length === 0) {
+    // Explicit filter matched nothing → operational failure (exit 2).
+    stderr.write('prune: no sessions matched the filter\n');
+    return 2;
+  }
+
+  const rows = targets.map((s) => [s.id, s.manifest.mode, s.manifest.status, s.manifest.createdAt, truncate(s.manifest.question, 40)]);
+
+  if (v['dry-run']) {
+    stdout.write(`DRY RUN — ${targets.length} session(s) would be deleted:\n`);
+    stdout.write(table(['SESSION', 'MODE', 'STATUS', 'CREATED', 'QUESTION'], rows));
+    return 0;
+  }
+
+  for (const s of targets) await store.deleteSession(s.id);
+  stdout.write(`deleted ${targets.length} session(s):\n`);
+  stdout.write(table(['SESSION', 'MODE', 'STATUS', 'CREATED', 'QUESTION'], rows));
+  return 0;
+}

package/dist/engineering-pa-cli/src/research/commands/run.mjs

@@ -0,0 +1,94 @@
+// research run — create a session (dir + manifest + skeleton plan), validate
+// inputs, print the plan, return. Does NOT orchestrate research (build-spec §3).
+// --dry-run validates + prints without persisting; it is the ONLY branch that
+// does not write.
+import { parseArgs } from 'node:util';
+import { getDefaultStore } from '../store/index.mjs';
+import { MODES, GATE_POLICIES, OUTPUT_MODES } from '../store/manifest.mjs';
+import { skeletonPlan } from '../store/plan.mjs';
+import { emptySources } from '../store/sources.mjs';
+import { emptyGates } from '../store/gates.mjs';
+import { manifestLine, planBlock } from '../format.mjs';
+
+// Mode-derived scope recorded in the manifest budget (build-spec §4). Not
+// enforced by the CLI — it records what the run was scoped to.
+export const MODE_BUDGETS = {
+  light: { maxSubQuestions: 0, maxDeepeningRounds: 0, wallClockMinutes: 2 },
+  normal: { maxSubQuestions: 4, maxDeepeningRounds: 1, wallClockMinutes: 10 },
+  deep: { maxSubQuestions: 12, maxDeepeningRounds: 3, wallClockMinutes: 45 },
+};
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research run --mode <light|normal|deep> --question "..." [--gate <operatorPresent|background|worker>] [--intent "..."] [--output <shortAnswer|article|structured>] [--dry-run]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+
+// Build a fresh manifest from validated inputs. Pure given a clock + id.
+export function buildManifest({ sessionId, mode, question, intent, gatePolicy, outputMode, nowIso }) {
+  const m = {
+    sessionId,
+    mode,
+    question,
+    gatePolicy,
+    status: 'draft',
+    outputMode,
+    budget: { ...MODE_BUDGETS[mode] },
+    assumptions: [],
+    createdAt: nowIso,
+    updatedAt: nowIso,
+  };
+  if (intent) m.intent = intent;
+  return m;
+}
+
+export async function runCommand(argv, { store, now = Date.now, stdout = process.stdout } = {}) {
+  if (!store) store = await getDefaultStore();
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        mode: { type: 'string' },
+        question: { type: 'string' },
+        gate: { type: 'string' },
+        intent: { type: 'string' },
+        output: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      allowPositionals: false,
+      strict: true,
+    });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const v = parsed.values;
+
+  if (!v.mode) throw usage('--mode is required');
+  if (!MODES.includes(v.mode)) throw usage(`--mode must be one of ${MODES.join(' | ')}`);
+  if (!v.question || v.question.trim() === '') throw usage('--question is required and must be non-empty');
+
+  const gatePolicy = v.gate ?? 'worker';
+  if (!GATE_POLICIES.includes(gatePolicy)) throw usage(`--gate must be one of ${GATE_POLICIES.join(' | ')}`);
+
+  const outputMode = v.output ?? 'shortAnswer';
+  if (!OUTPUT_MODES.includes(outputMode)) throw usage(`--output must be one of ${OUTPUT_MODES.join(' | ')}`);
+
+  const nowIso = new Date(now()).toISOString();
+  const sessionId = store.newSessionId(now());
+  const manifest = buildManifest({ sessionId, mode: v.mode, question: v.question, intent: v.intent, gatePolicy, outputMode, nowIso });
+  const plan = skeletonPlan(v.mode);
+
+  if (v['dry-run']) {
+    stdout.write('DRY RUN — nothing persisted.\n\n');
+    stdout.write(manifestLine(manifest));
+    stdout.write('\n');
+    stdout.write(planBlock(plan));
+    return 0;
+  }
+
+  await store.createSession({ manifest, plan, sources: emptySources(), gates: emptyGates() });
+  stdout.write(`created ${sessionId}\n\n`);
+  stdout.write(manifestLine(manifest));
+  stdout.write('\n');
+  stdout.write(planBlock(plan));
+  return 0;
+}

package/dist/engineering-pa-cli/src/research/commands/show.mjs

@@ -0,0 +1,43 @@
+// research show <sessionId> — dump one session: manifest, plan, findings summary,
+// gate summary, source count. --json emits the full assembled object.
+import { parseArgs } from 'node:util';
+import { existsSync } from 'node:fs';
+import { getDefaultStore } from '../store/index.mjs';
+import { manifestLine, planBlock, findingsSummary, gatesSummary } from '../format.mjs';
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research show <sessionId> [--json]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+
+export async function showCommand(argv, { store, stdout = process.stdout } = {}) {
+  if (!store) store = await getDefaultStore();
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { json: { type: 'boolean' } }, allowPositionals: true, strict: true });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const id = parsed.positionals[0];
+  if (parsed.positionals.length !== 1) throw usage('exactly one <sessionId> is required');
+  if (!store.isValidSessionId(id)) throw usage(`"${id}" is not a valid sessionId`);
+
+  const manifest = await store.readManifest(id); // exit 2 if not found / malformed
+  const plan = existsSync(store.paths(id).plan) ? await store.readPlan(id) : null;
+  const sources = await store.readSources(id);
+  const gates = await store.readGates(id);
+  const findings = await store.listFindings(id);
+
+  if (parsed.values.json) {
+    stdout.write(JSON.stringify({ manifest, plan, sources, gates, findings }, null, 2) + '\n');
+    return 0;
+  }
+
+  stdout.write(manifestLine(manifest));
+  stdout.write('\n');
+  stdout.write(plan ? planBlock(plan) : 'plan: none\n');
+  stdout.write('\n');
+  stdout.write(findingsSummary(findings));
+  stdout.write(`sources: ${sources.items.length}\n`);
+  stdout.write(gatesSummary(gates));
+  return 0;
+}

package/dist/engineering-pa-cli/src/research/docs/operator-present-flow.md

@@ -0,0 +1,120 @@
+# Operator-present gate flow
+
+How Dave clears human gates **live** during a research run, and how the same
+in-session presence sweeps the queue of gates that earlier `background`-posture runs
+left behind. This is the runbook for the `operatorPresent` gate policy (build-spec
+§6). It is a **flow doc, not a code path** — the Playwright-MCP integration in the
+skill body is a later concern; here we describe what the operator and Dave actually do.
+**Baz** is the operator (the human in the session); **Dave** is the operator's model; a
+**gate** is any fetch blocked by a login wall, paywall, Cloudflare/Turnstile challenge,
+or captcha.
+
+---
+
+## 1. When to use `operatorPresent`
+
+Reach for `--gate operatorPresent` when all three hold:
+
+- **Baz is in-session with Dave** — a live, interactive run, not a cron/scheduled one.
+- **The research will touch gated sources** — the answer depends on paywalled docs, a
+  logged-in dashboard, or a Cloudflare-fronted site that a headless fetch can't pass.
+- **The answer is worth Baz's attention** — clearing a gate costs a few seconds of the
+  operator's time per gate; only spend it when getting the real source materially
+  improves the answer over dropping-with-caveat.
+
+If Baz is not present, or the run is scheduled, use `background` (queue the gates) or
+`worker` (the default for dispatched agents; park/resume is v2). A worker **never**
+self-upgrades to headed browsing.
+
+## 2. The mechanics
+
+Dave invokes the run, declaring the posture:
+
+```
+/research <question> --mode <light|normal> --gate operatorPresent
+```
+
+On a gate hit, Dave does **not** drop the source. Instead:
+
+1. Dave escalates to Baz in plain language, naming the URL and the obstacle — e.g.
+   *"Cloudflare check on docs.example.com — can you clear it?"*
+2. Baz acts in the **shared headed browser** (a real Playwright MCP session Dave
+   drives): Dave calls the Playwright MCP browser (in prose: `browser_navigate` to the
+   URL, then `browser_snapshot` so Baz sees the page; Baz solves the challenge or signs
+   in; Dave re-snapshots to confirm the content is now reachable).
+3. Dave reads the now-ungated content and continues the fetch as normal — the source is
+   cited like any other.
+
+**The MCP browser is shared parent state.** There is exactly **one** headed consumer at
+a time, and it is Dave (the parent). Subagents — the `research-normal.js` workflow's
+searchers — run headless and **never** touch it. That has a hard consequence:
+
+> **Do not run a normal-mode workflow under `operatorPresent`.** The workflow's searcher
+> subagents cannot attach to Dave's headed Playwright session, so they can't benefit from
+> a live clearance. Operator-present runs are effectively **light mode** (Dave does the
+> fetching inline, on the shared browser) or a single-worker fetch that Dave supervises.
+> A normal-mode run that expects gated sources should use `background` and be swept later
+> (§3).
+
+## 3. Sweeping the queued `background` gates
+
+`background`-posture runs don't block on gates: each searcher drops the source and the
+workflow's Finalise phase persists the record via `research gates --append`, so the
+gate lands in `sessions/<id>/gates.json` with `status: pending`. Those records
+accumulate across runs. A later operator-present session drains them:
+
+1. **See what's queued** — across all sessions, or one:
+
+   ```sh
+   research gates --list            # every session's pending/retrying gates
+   research gates --list <id>       # just one session
+   ```
+
+2. **Clear each gate Baz wants** — for a chosen row, Dave drives the shared Playwright
+   MCP browser to the `url` (in prose: `browser_navigate` + `browser_snapshot`), Baz
+   clears the challenge/login, and Dave captures the page. Because browser sessions
+   don't transfer between processes, **clearance produces an artifact, not a cleared
+   path**: Dave saves the fetched content to `sessions/<id>/gated/<hash>.md` so it can be
+   re-read exactly like a fetch.
+
+3. **Mark the swept items** — flag the session's eligible gates for follow-up:
+
+   ```sh
+   research gates --retry <id>      # marks pending/retrying items as `retrying`
+   ```
+
+   In v1, `--retry` **only marks** — it does not re-run the pipeline. `retrying` means
+   *"queued for the operator to hand-run the fetch"*; Dave (or Baz) reads the saved
+   `gated/<hash>.md` artifact and folds it into the answer by hand. The automated
+   re-run of just the parked sub-questions is v2 (§4).
+
+## 4. What v1 covers vs what v2 adds
+
+**v1 (this and w-018):**
+- `background`-posture gates queue automatically via `research gates --append` (workflow
+  Finalise phase).
+- `operatorPresent` runs skip gates live: Dave escalates, Baz clears in the shared headed
+  Playwright browser, the fetch continues.
+- `research gates --list` aggregates the queue; `research gates --retry` marks items for
+  operator follow-up; clearance content is saved to `sessions/<id>/gated/<hash>.md`.
+
+**v2 (deferred):**
+- Worker-posture **park → escalate → resume** automation: a dispatched worker parks the
+  gated sub-question, checkpoints `GATE: {...}` up its channel, continues its remaining
+  queue, and is resumed from the clearance artifact.
+- A `research resume <sessionId>` verb that re-runs extract+verify for just the parked
+  sub-questions against `gated/<hash>.md`.
+- `research gates --retry` triggering that automated re-run rather than only marking.
+
+## 5. Anti-patterns
+
+- **Do not try to defeat a gate from a worker.** Spec §6: a worker never self-upgrades to
+  headed browsing. Background workers drop-and-log; that is correct, not a failure.
+- **Do not run headed Playwright from a subagent.** The MCP browser is shared parent
+  state with one headed consumer. Only Dave (the parent) drives it; searchers stay
+  headless.
+- **Do not auto-approve gate clearances.** The entire point of `operatorPresent` is live
+  consent — Baz decides which gates to clear. Never script past a login/paywall on Baz's
+  behalf without the explicit ask.
+- **Do not run `operatorPresent` for a normal-mode workflow.** Its searchers can't attach
+  to the shared browser (§2). Use `background` + a later sweep instead.

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

@@ -0,0 +1,59 @@
+// Pure presentation helpers. No I/O — every function returns a string. Commands
+// write these to their injected out/err streams. Keeps rendering testable and
+// keeps the exit-code/side-effect logic out of the formatting layer.
+
+export function truncate(s, n) {
+  const one = String(s ?? '').replace(/\s+/g, ' ').trim();
+  return one.length > n ? one.slice(0, n - 1) + '…' : one;
+}
+
+// A compact fixed-width table. rows is an array of arrays of strings.
+export function table(headers, rows) {
+  const all = [headers, ...rows];
+  const widths = headers.map((_, c) => Math.max(...all.map((r) => String(r[c] ?? '').length)));
+  const line = (r) => r.map((cell, c) => String(cell ?? '').padEnd(widths[c])).join('  ').trimEnd();
+  const out = [line(headers), widths.map((w) => '-'.repeat(w)).join('  ').trimEnd()];
+  for (const r of rows) out.push(line(r));
+  return out.join('\n') + '\n';
+}
+
+export function manifestLine(m) {
+  return [
+    `session ${m.sessionId}`,
+    `  mode:       ${m.mode}`,
+    `  status:     ${m.status}`,
+    `  gatePolicy: ${m.gatePolicy}`,
+    `  outputMode: ${m.outputMode}`,
+    `  question:   ${m.question}`,
+    m.intent ? `  intent:     ${m.intent}` : null,
+    `  budget:     subQ=${m.budget.maxSubQuestions} rounds=${m.budget.maxDeepeningRounds} wallMin=${m.budget.wallClockMinutes}`,
+    m.assumptions.length ? `  assumptions: ${m.assumptions.join('; ')}` : null,
+    `  created:    ${m.createdAt}`,
+    `  updated:    ${m.updatedAt}`,
+  ].filter((x) => x != null).join('\n') + '\n';
+}
+
+export function planBlock(p) {
+  const lines = [`plan: ${p.subQuestions.length} sub-question(s), deepeningRounds=${p.deepeningRounds}, verificationTier=${p.verificationTier}`];
+  for (const sq of p.subQuestions) {
+    const dep = sq.dependsOn.length ? ` (depends on ${sq.dependsOn.join(', ')})` : '';
+    lines.push(`  [${sq.id}] ${sq.kind}${dep}: ${sq.text}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+export function findingsSummary(findings) {
+  if (findings.length === 0) return 'findings: none yet\n';
+  const lines = [`findings: ${findings.length}`];
+  for (const f of findings) {
+    const votes = f.verificationVotes.length ? ` votes=${f.verificationVotes.map((v) => v.outcome).join('/')}` : '';
+    lines.push(`  [${f.subQuestionId}] confidence=${f.confidence}${f.unsourced ? ' UNSOURCED' : ''}${votes}: ${truncate(f.summary, 60)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+export function gatesSummary(gates) {
+  const counts = { pending: 0, retrying: 0, resolved: 0, failed: 0 };
+  for (const g of gates.queue) counts[g.status]++;
+  return `gates: ${gates.queue.length} total (pending=${counts.pending}, retrying=${counts.retrying}, resolved=${counts.resolved}, failed=${counts.failed})\n`;
+}