@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/research/briefs/synthesizer.md

@@ -0,0 +1,124 @@
+# Brief — synthesizer (deep-research, mode `normal`)
+
+You are a **synthesizer** in the `research-normal.js` pipeline. One synthesizer owns
+**one sub-question**: merge its verified claims into a single finding, **write the
+finding file to disk**, and return a receipt. You are the stage that turns verified
+claims into a durable, schema-valid `findings/sq-<id>.json`.
+
+The dispatching workflow supplies concrete values for every `{{placeholder}}` below.
+
+## 1. Goal
+
+For sub-question **`{{subQuestionId}}`** — *"{{subQuestionText}}"* — write
+`{{sessionDir}}/findings/{{findingFilename}}` conforming exactly to the finding schema,
+containing: a 1–4 sentence `summary` answering the sub-question, the surviving quotes,
+the source ids used, an honest `confidence`, the verification votes on central claims,
+and the `unsourced` flag. Merge semantic duplicates. Be transparent about refuted
+claims.
+
+## 2. Trace
+
+- Parent run: session `{{sessionId}}`, output mode `{{outputMode}}`.
+- Inputs handed to you by the workflow:
+  - **Verified central claims** (survived 3-vote verify, <2 refutes), each with its
+    quote, sourceId, and the three vote outcomes: {{verifiedClaims}}
+  - **Supporting/incidental claims** (reported, not verified): {{supportingClaims}}
+  - **Refuted central claims** (≥2 refutes — do NOT assert these; disclose them):
+    {{refutedClaims}}
+- Your finding file is validated by the store: the workflow round-trips
+  `research show {{sessionId}} --json` and treats a non-zero exit as your write being
+  rejected. **`subQuestionId` inside the file MUST equal `{{subQuestionId}}` AND match
+  the filename stem `{{findingFilename}}`** — the store keys findings by filename, so a
+  mismatch is a consistency bug you must not ship.
+
+## 3. Context — confidence & transparency
+
+- **confidence** (`low | medium | high`), your honest read:
+  - `high` — central claims confirmed by the panel and grounded in `primary` sources
+    that agree.
+  - `medium` — mostly confirmed but thinner sourcing, some `secondary`-only support,
+    or minor unresolved tension.
+  - `low` — sparse/gated sources, unresolved contradictions, or several central claims
+    refuted.
+- **Refuted-claim transparency is mandatory.** Do not silently drop refuted central
+  claims — name them in the `summary` (e.g. "A common claim that X was tested and did
+  not hold: …") so the reader sees what was checked and rejected.
+- **Merge duplicates**: collapse claims that say the same thing; keep the strongest
+  quote/source.
+- `unsourced` is `true` iff any assertion in your `summary` lacks a supporting quote in
+  `quotes[]`. Aim for `false` — every summary sentence should trace to a quote.
+
+## 4. Tools & sources
+
+- `Read` to inspect the inputs and the schema at
+  `{{schemaDir}}/finding.schema.json` if you need it.
+- `Write` to create the finding file.
+- `Bash` to round-trip: `{{cli}} show {{sessionId}} --json` —
+  exit 0 means every finding on disk (including yours) validates.
+
+## 5. Boundaries
+
+- One finding file, for `{{subQuestionId}}` only. Do not write `sources.json`,
+  `manifest.json`, the session answer, or any sibling's finding — the workflow's
+  finalise stage owns those.
+- Do not invent quotes or source ids: every `quotes[].sourceId` and every id in
+  `sources[]` must come from the claims you were handed.
+- Do not mark the session done — the finalise stage does that after all findings land.
+
+## 6. Output format
+
+### The file you write — `findings/{{findingFilename}}` (finding schema)
+
+```json
+{
+  "subQuestionId": "{{subQuestionId}}",
+  "summary": "1–4 sentences answering the sub-question, incl. a refuted-claim note if any.",
+  "quotes": [
+    { "text": "verbatim quote", "sourceId": "s1-1", "importance": "central" }
+  ],
+  "sources": ["s1-1", "s1-2"],
+  "confidence": "high",
+  "verificationVotes": [
+    { "outcome": "confirmed", "lens": "contradiction-search", "note": "re: claim c-1 — no contradicting source found" }
+  ],
+  "unsourced": false
+}
+```
+
+- `quotes[].importance` ∈ `central | supporting | incidental` (optional per field but
+  include it). `confidence` ∈ `low | medium | high`.
+- `verificationVotes[].outcome` ∈ `confirmed | refuted | unverified-infra`; `lens` and
+  `note` are optional but use `note` to name which central claim each vote concerns
+  (the schema has no per-claim vote linkage, so the note carries it).
+- **No extra top-level fields** — the validator rejects unknown keys.
+
+### Your structured return to the workflow (the receipt)
+
+```json
+{
+  "subQuestionId": "{{subQuestionId}}",
+  "written": true,
+  "path": "findings/{{findingFilename}}",
+  "confidence": "high",
+  "claimCount": 5,
+  "centralConfirmed": 3,
+  "centralRefuted": 1,
+  "unsourcedCount": 0,
+  "refutedTransparency": "one line naming any refuted central claims, or 'none'"
+}
+```
+
+## 7. Done when
+
+- `findings/{{findingFilename}}` exists, its `subQuestionId` equals `{{subQuestionId}}`
+  and the filename stem, and `research show {{sessionId}} --json` exits 0 (your file
+  and every sibling's validate). Your receipt reports the real counts.
+
+## 8. Escalation
+
+- **The store rejects your file** (`show --json` exits 2 with a named error) → read the
+  error, fix the offending field, rewrite, re-run `show`. Never return `written: true`
+  while the round-trip is red.
+- **Schema and a coherent answer genuinely cannot agree** → return `written: false`
+  with `refutedTransparency` explaining the conflict; the workflow escalates rather
+  than shipping a broken finding.

package/dist/engineering-pa-cli/src/research/briefs/verifier.md

@@ -0,0 +1,86 @@
+# Brief — verifier (deep-research, mode `normal`)
+
+You are a **verifier** in the `research-normal.js` pipeline. You cast **one adversarial
+vote** on **one claim**. Three independent verifiers vote on each central claim; the
+workflow tallies. Your job is to *try to break the claim*, not to confirm it.
+
+The dispatching workflow supplies concrete values for every `{{placeholder}}` below.
+
+## 1. Goal
+
+Decide whether this claim survives an honest attempt to refute it:
+
+- Claim: **"{{claimText}}"**
+- Supporting quote (from the extractor): *"{{quote}}"*
+- Cited source: {{sourceUrl}}
+- In service of sub-question: *"{{subQuestionText}}"*
+- Your assigned lens (if any): **{{lens}}**
+
+Return one of three outcomes: `confirmed`, `refuted`, `unverified-infra`.
+
+## 2. Trace
+
+- Parent run: session `{{sessionId}}`. You are one of a 3-vote panel on this claim.
+- Downstream rule the workflow applies to the panel: **≥ 2 `refuted` → the claim is
+  dropped** from the finding and reported as refuted. `unverified-infra` votes do
+  **not** count toward refutation — they record that verification could not run, not
+  that the claim is false.
+
+## 3. Context — the adversarial posture
+
+- **Default to `refuted` when uncertain.** The burden is on the claim to survive, not
+  on you to disprove it beyond doubt. A claim you cannot corroborate from an
+  independent angle is not "probably fine" — it is `refuted`.
+- Vote `confirmed` only when an **independent** check agrees: the quote genuinely
+  supports the claim AND (where checkable) a second source, the primary source itself,
+  or first-principles reasoning agrees. Do not confirm on the strength of the single
+  cited source alone if the claim is checkable elsewhere.
+- Vote `refuted` when: the quote does not actually support the claim (quote–claim
+  mismatch is a top failure mode — read it literally); an independent source
+  contradicts it; the claim is stale (superseded version/date); or it overreaches
+  beyond what any source supports.
+- Lens focus (if `{{lens}}` is set): `quote-support` = does the quote prove the claim;
+  `contradiction-search` = actively search for a source that disagrees;
+  `recency-source-fit` = is it current and is the source the right kind of authority.
+  With no lens, apply all three.
+
+## 4. Tools & sources
+
+- `WebSearch` + `WebFetch` to seek contradiction and corroboration. Keep it lean —
+  a few targeted calls, not a re-research. You are testing one claim, not rebuilding
+  the sub-question.
+
+## 5. Boundaries
+
+- One claim, one vote. Do not re-extract, do not evaluate sibling claims, do not write
+  files.
+- Do not soften a genuine refutation into `unverified-infra` to be polite —
+  `unverified-infra` is **only** for infrastructure failure (rate limits, everything
+  you fetched timed out / errored), never for "I found it doubtful."
+- Conversely, do not report a real infra failure as `refuted` — that would falsely
+  sink a possibly-true claim.
+
+## 6. Output format — structured return (enforced by the workflow's schema)
+
+```json
+{
+  "outcome": "confirmed",
+  "note": "one line: what you checked and why it lands here (cite the contradicting/corroborating source if any)"
+}
+```
+
+- `outcome` ∈ `confirmed | refuted | unverified-infra` (exact spelling; these are the
+  finding schema's vote outcomes).
+- `note` is mandatory and must name the evidence — a bare outcome is not auditable.
+
+## 7. Done when
+
+- You have one `outcome` backed by a one-line, evidence-citing `note`, reached under
+  the adversarial default (uncertain ⇒ refuted).
+
+## 8. Escalation
+
+- **All your fetches failed (rate limit / network)** → `unverified-infra` with a note
+  naming the failure. Do not guess an outcome from the claim's plausibility.
+- You never block or hand back — a vote is always due; when truly unable to check and
+  it is not an infra failure, the adversarial default (`refuted`) applies.

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

@@ -0,0 +1,141 @@
+// research — deep-research session store CLI.
+//
+// The ONLY module that owns exit codes. Commands return a number or throw an
+// Error carrying `.exitCode`; this wrapper translates:
+//   0 — ok
+//   1 — usage error (bad args, unknown verb, bad enum, missing sessionId)
+//   2 — operational (session not found, malformed session dir, explicit prune matched nothing)
+//   3 — transport/IO (disk read/write failure)
+//
+// Shape: `main(argv)` returns the exit code as a number (async). The bin shim
+// converts to `process.exit`; `pa research <verb>` in `pa/cli.mjs` awaits the
+// number so `pa` can surface the same code. Same pattern as `pa/knowledge/cli.mjs`.
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HELP = `research — deep-research session store
+
+Creates, validates, inspects and prunes research sessions under
+<repoRoot>/.cache/research/sessions/<sessionId>/. Owns the schemas every
+research workflow reads. Zero runtime dependencies.
+
+Usage:
+  research run --mode <light|normal|deep> --question "..." [--gate <policy>]
+               [--intent "..."] [--output <mode>] [--dry-run]
+      Create a session (dir + manifest + skeleton plan), validate inputs, print
+      the plan, and return. Does NOT orchestrate research. --dry-run validates and
+      prints without persisting. Gate policy: operatorPresent | background | worker.
+      Output mode: shortAnswer | article | structured (default shortAnswer).
+
+  research list [--status <status>] [--all] [--json]
+      List sessions, newest first. Default: 20 most recent. --all lists every one.
+
+  research show <sessionId> [--json]
+      Dump one session: manifest, findings summary, gate summary.
+
+  research gates --list [<sessionId>] | --retry <sessionId> | --append <sessionId>
+      --list aggregates the gate queue across all sessions (or one if given).
+      --retry marks eligible (pending/retrying) gates as retrying and prints them.
+      --append reads gate records (JSON array on stdin, or --record '<json>' for a
+      single one) and appends them to the session's gates.json with fresh g-N ids.
+
+  research prune [--older-than <days>] [--status <status>] [--dry-run]
+      Delete sessions older than N days and/or matching a status. At least one
+      filter is required. --dry-run prints what would be deleted without deleting.
+
+  research mark <done|aborted> <sessionId> [--no-promote | --promote]
+      Set a terminal status on a session: done (finalised) or aborted (abandoned).
+      Bumps updatedAt. Both transitions are one-way — a session already done or
+      aborted is refused (exit 2). The one verb that mutates a session's status.
+      On mark done, a normal/deep session's answer.md is promoted into the
+      operator knowledge library (operator/knowledge/research/); light is never
+      promoted (--promote on light is a usage error). --no-promote skips promotion
+      on normal/deep with a note. Aborted sessions are never promoted.
+
+  research paths [--json]
+      Emit the resolved absolute paths the /research skill and workflow scripts
+      consume: sessionsDir, briefsDir, workflowsDir, cli. Text default; --json
+      for machine input. Uses the same repo-root resolver as pa knowledge / pa
+      work: \$DAVE_REPO_ROOT / \$PA_REPO_ROOT, else walk upward for a .git entry.
+
+  research --help | -h        This message.
+
+Exit codes: 0 ok, 1 usage error, 2 operational failure, 3 transport/IO failure.
+`;
+
+export async function main(argv) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  try {
+    switch (verb) {
+      case 'run': {
+        const { runCommand } = await import('./commands/run.mjs');
+        return (await runCommand(rest)) ?? 0;
+      }
+      case 'list': {
+        const { listCommand } = await import('./commands/list.mjs');
+        return (await listCommand(rest)) ?? 0;
+      }
+      case 'show': {
+        const { showCommand } = await import('./commands/show.mjs');
+        return (await showCommand(rest)) ?? 0;
+      }
+      case 'gates': {
+        const { gatesCommand } = await import('./commands/gates.mjs');
+        return (await gatesCommand(rest)) ?? 0;
+      }
+      case 'prune': {
+        const { pruneCommand } = await import('./commands/prune.mjs');
+        return (await pruneCommand(rest)) ?? 0;
+      }
+      case 'mark': {
+        const { markCommand } = await import('./commands/mark.mjs');
+        return (await markCommand(rest)) ?? 0;
+      }
+      case 'paths': {
+        const { pathsCommand } = await import('./commands/paths.mjs');
+        return (await pathsCommand(rest)) ?? 0;
+      }
+      default:
+        process.stderr.write(`unknown command: ${verb}\n\n`);
+        process.stderr.write(HELP);
+        return 1;
+    }
+  } catch (err) {
+    // parseArgs strict-mode errors and our own usage errors both surface here.
+    const exitCode = err && err.exitCode != null ? err.exitCode : 1;
+    process.stderr.write(`${err && err.message ? err.message : err}\n`);
+    return exitCode;
+  }
+}
+
+// Allow `node src/research/cli.mjs ...` in addition to the bin shim.
+//
+// ISMAIN-AUDIT (bug-3 sweep): the previous strict `file://${argv[1]}`
+// equality has the same fragility as the endsWith idiom fixed elsewhere —
+// no realpath resolution on argv[1], so a symlinked invocation path (e.g.
+// via a pnpm .bin shim) would silently fail to match import.meta.url
+// (which Node always resolves to the real path). Not proven to fire in
+// production today (the shipped `bin/research` imports and calls main()
+// directly, bypassing this branch entirely) but fixed defensively to match
+// the robust realpath-on-both-sides pattern used across the repo.
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectlyInvoked()) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

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

@@ -0,0 +1,176 @@
+// research gates --list [<sessionId>] | --retry <sessionId> | --append <sessionId>
+//
+// --list   aggregates the gate queue across all sessions (or one, if given).
+// --retry  marks eligible (pending/retrying) gates as `retrying` and prints them.
+//          Actual re-execution is workflow-side (w-018+); this only marks + prints.
+// --append reads gate records (JSON array on stdin, or --record '<json>' for a single
+//          one) and appends them to the session's gates.json with fresh g-N ids. The
+//          caller supplies the semantic fields ({url,gateType,whatIsNeeded,subQuestionId?});
+//          the verb assigns the id, sets blockedAt from the clock, defaults status:pending.
+//          The write goes through the store chokepoint (store.writeGates → validateGates).
+import { parseArgs } from 'node:util';
+import { getDefaultStore } from '../store/index.mjs';
+import { markEligibleForRetry, GATE_STATUSES } from '../store/gates.mjs';
+import { isObject } from '../store/validate.mjs';
+import { table, truncate } from '../format.mjs';
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research gates --list [<sessionId>] | --retry <sessionId> | --append <sessionId> [--record '<json>'] [--json]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+function notFound(msg) {
+  return Object.assign(new Error(msg), { exitCode: 2 });
+}
+
+// Read all of a readable stream to a utf8 string. Injected in tests.
+async function readAllStdin(stream = process.stdin) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// Collect every gate across sessions (or one session) into flat rows carrying
+// their sessionId. Pure over the store's reads.
+async function collectGates(store, onlyId) {
+  const ids = onlyId
+    ? [onlyId]
+    : (await store.listSessions()).filter((s) => s.manifest).map((s) => s.id);
+  const rows = [];
+  for (const id of ids) {
+    const gates = await store.readGates(id);
+    for (const g of gates.queue) rows.push({ sessionId: id, ...g });
+  }
+  return rows;
+}
+
+// Parse a caller-supplied record/records blob. Bad JSON is USER input → exit 1
+// (not the store validator's exit 2). Returns a normalised array.
+function parseRecords(text, where) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw usage(`invalid JSON on ${where}: ${e.message}`);
+  }
+  return Array.isArray(raw) ? raw : [raw];
+}
+
+// Turn one caller record into a full gate item. Validates input fields (exit 1 on a
+// bad one) and stamps the verb-owned fields (id, blockedAt, default status).
+function buildGateItem(r, id, nowIso, i) {
+  const at = `record[${i}]`;
+  if (!isObject(r)) throw usage(`${at} must be a JSON object`);
+  const KNOWN = new Set(['url', 'gateType', 'whatIsNeeded', 'subQuestionId', 'status']);
+  for (const k of Object.keys(r)) {
+    if (!KNOWN.has(k)) throw usage(`${at} has unexpected field "${k}" (allowed: url, gateType, whatIsNeeded, subQuestionId, status)`);
+  }
+  const reqStr = (k) => {
+    if (typeof r[k] !== 'string' || r[k].length === 0) throw usage(`${at}.${k} must be a non-empty string`);
+    return r[k];
+  };
+  const item = {
+    id,
+    url: reqStr('url'),
+    gateType: reqStr('gateType'),
+    whatIsNeeded: reqStr('whatIsNeeded'),
+    status: 'pending',
+    blockedAt: nowIso,
+  };
+  if (r.subQuestionId != null) {
+    if (typeof r.subQuestionId !== 'string' || r.subQuestionId.length === 0) throw usage(`${at}.subQuestionId must be a non-empty string if present`);
+    item.subQuestionId = r.subQuestionId;
+  }
+  if (r.status != null) {
+    if (!GATE_STATUSES.includes(r.status)) throw usage(`${at}.status must be one of ${GATE_STATUSES.join(' | ')} (got ${JSON.stringify(r.status)})`);
+    item.status = r.status;
+  }
+  return item;
+}
+
+export async function gatesCommand(argv, { store, stdout = process.stdout, now = Date.now, readStdin = readAllStdin } = {}) {
+  if (!store) store = await getDefaultStore();
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        list: { type: 'boolean' },
+        retry: { type: 'string' },
+        append: { type: 'boolean' },
+        record: { type: 'string' },
+        json: { type: 'boolean' },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const v = parsed.values;
+  const modes = [v.list && 'list', v.retry != null && 'retry', v.append && 'append'].filter(Boolean);
+  if (modes.length !== 1) throw usage('exactly one of --list, --retry <sessionId>, or --append <sessionId> is required');
+  if (v.record != null && !v.append) throw usage('--record is only valid with --append');
+
+  if (v.list) {
+    const onlyId = parsed.positionals[0];
+    if (parsed.positionals.length > 1) throw usage('--list takes at most one <sessionId>');
+    if (onlyId != null) {
+      if (!store.isValidSessionId(onlyId)) throw usage(`"${onlyId}" is not a valid sessionId`);
+      if (!store.exists(onlyId)) throw notFound(`session ${onlyId} not found`);
+    }
+    const rows = await collectGates(store, onlyId);
+    if (v.json) { stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
+    if (rows.length === 0) { stdout.write('no gates\n'); return 0; }
+    stdout.write(table(
+      ['SESSION', 'GATE', 'STATUS', 'TYPE', 'URL', 'NEEDED'],
+      rows.map((r) => [r.sessionId, r.id, r.status, r.gateType, truncate(r.url, 40), truncate(r.whatIsNeeded, 40)]),
+    ));
+    return 0;
+  }
+
+  if (v.append) {
+    const id = parsed.positionals[0];
+    if (!id) throw usage('--append requires a <sessionId>');
+    if (parsed.positionals.length > 1) throw usage('--append takes exactly one <sessionId>');
+    if (!store.isValidSessionId(id)) throw usage(`"${id}" is not a valid sessionId`);
+    if (!store.exists(id)) throw notFound(`session ${id} not found`);
+
+    const text = v.record != null ? v.record : await readStdin();
+    const records = parseRecords(text, v.record != null ? '--record' : 'stdin');
+    if (records.length === 0) throw notFound('no gate records supplied');
+
+    const existing = await store.readGates(id);
+    let maxN = 0;
+    for (const it of existing.queue) {
+      const m = /^g-(\d+)$/.exec(it.id);
+      if (m) maxN = Math.max(maxN, Number(m[1]));
+    }
+    const nowIso = new Date(now()).toISOString();
+    const newItems = records.map((r, i) => buildGateItem(r, `g-${maxN + i + 1}`, nowIso, i));
+    const next = { ...existing, queue: [...existing.queue, ...newItems] };
+    await store.writeGates(id, next); // chokepoint: validates the whole file before persist
+
+    if (v.json) { stdout.write(JSON.stringify(newItems, null, 2) + '\n'); return 0; }
+    stdout.write(`appended ${newItems.length} gate(s) to ${id}: ${newItems.map((it) => it.id).join(', ')}\n`);
+    return 0;
+  }
+
+  // --retry <sessionId>
+  const id = v.retry;
+  if (!store.isValidSessionId(id)) throw usage(`"${id}" is not a valid sessionId`);
+  if (!store.exists(id)) throw notFound(`session ${id} not found`);
+
+  const gates = await store.readGates(id);
+  const { gates: next, marked } = markEligibleForRetry(gates);
+  if (marked.length === 0) {
+    stdout.write('no eligible gates to retry\n');
+    return 0;
+  }
+  await store.writeGates(id, next);
+  if (v.json) { stdout.write(JSON.stringify(marked, null, 2) + '\n'); return 0; }
+  stdout.write(`marked ${marked.length} gate(s) as retrying in ${id}:\n`);
+  stdout.write(table(
+    ['GATE', 'TYPE', 'URL', 'NEEDED'],
+    marked.map((r) => [r.id, r.gateType, truncate(r.url, 40), truncate(r.whatIsNeeded, 40)]),
+  ));
+  return 0;
+}

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

@@ -0,0 +1,56 @@
+// research list — list sessions, newest first (sessionId sorts by creation time).
+// Default: 20 most recent. --all: every session. --status: filter. --json: machine output.
+import { parseArgs } from 'node:util';
+import { getDefaultStore } from '../store/index.mjs';
+import { STATUSES } from '../store/manifest.mjs';
+import { table, truncate } from '../format.mjs';
+
+const DEFAULT_LIMIT = 20;
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research list [--status <${STATUSES.join('|')}>] [--all] [--json]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+
+export async function listCommand(argv, { store, stdout = process.stdout } = {}) {
+  if (!store) store = await getDefaultStore();
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        status: { type: 'string' },
+        all: { type: 'boolean' },
+        json: { type: 'boolean' },
+      },
+      allowPositionals: false,
+      strict: true,
+    });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  const v = parsed.values;
+  if (v.status != null && !STATUSES.includes(v.status)) throw usage(`--status must be one of ${STATUSES.join(' | ')}`);
+
+  let sessions = await store.listSessions();
+  if (v.status != null) sessions = sessions.filter((s) => s.manifest && s.manifest.status === v.status);
+  const limited = v.all ? sessions : sessions.slice(0, DEFAULT_LIMIT);
+
+  if (v.json) {
+    stdout.write(JSON.stringify(limited.map((s) => (s.manifest ? s.manifest : { sessionId: s.id, error: s.error })), null, 2) + '\n');
+    return 0;
+  }
+
+  if (limited.length === 0) {
+    stdout.write('no sessions\n');
+    return 0;
+  }
+
+  const rows = limited.map((s) => s.manifest
+    ? [s.id, s.manifest.mode, s.manifest.status, s.manifest.createdAt, truncate(s.manifest.question, 50)]
+    : [s.id, '?', 'MALFORMED', '?', truncate(s.error, 50)]);
+  stdout.write(table(['SESSION', 'MODE', 'STATUS', 'CREATED', 'QUESTION'], rows));
+  if (!v.all && sessions.length > limited.length) {
+    stdout.write(`\n… ${sessions.length - limited.length} more (use --all)\n`);
+  }
+  return 0;
+}