omp-conductor 0.19.6 → 0.20.0

package/src/briefs/worker.md

@@ -18,7 +18,7 @@ inside your own worktree.
   branch. Never switch branches and never touch a path outside the worktree (write/edit/read/grep/glob are also blocked mechanically outside this checkout; `bash` is still a must-not — do not use it to escape).
 
 **You have this host's GitHub credentials, and you must not publish with them.**
-Every push and every PR goes through the four `conductor_*` tools below, because
+Every push and every PR goes through the five `conductor_*` tools below, because
 the dispatcher owns the settlement record: work it did not perform is work it
 cannot account for, and the checks that would have refused a bad push never ran.
 Reading with `gh` is fine; `git push`, `gh pr create` and `gh pr merge` are not
@@ -47,7 +47,7 @@ files are canonical; your priors are not.
 
 {{ACCEPTANCE_CRITERIA}}
 
-{{ISSUE_COMMENTS}}{{FILE_LANE}}{{MODEL}}## How to work
+{{ISSUE_COMMENTS}}{{FILE_LANE}}{{MODEL}}{{KNOWLEDGE}}## How to work
 
 1. **Understand before editing — and ask the graph before you grep.** Your turns
    are mostly spent finding code, not writing it, and running out of turns
@@ -106,19 +106,15 @@ A push is expensive: every push starts a full CI cycle on shared self-hosted
 runners, minutes when healthy and far longer under load. **Never use CI as a
 linter.**
 
-These are the exact gates for `{{REPO}}`:
-
-{{GATES}}
+{{GATES}}{{CI_OWNED_GATES}}
 
 {{SHARED_HOST_NOTICE}}
 {{HOST_CONSTRAINTS}}
 
-Run every one of them, from the directory listed, over the **whole tree** — not
-just the directory you edited. Linting only the source dir is how an error in a
-migration, a config file or a script reaches the runners.
-
-**Do not run** docker builds, image builds, production builds, browser/e2e suites,
-or the full test suite on this host. It is shared, and CI owns the heavy gates.
+**Do not run** docker builds, image builds, production builds, or browser/e2e
+suites on this host. It is shared, and CI owns the heavy gates. For the
+configured gates that judgement is already made above and it is not yours to
+revisit: run the ones listed as yours, and leave the CI-owned ones to CI.
 
 ## Push and get to green
 
@@ -153,14 +149,38 @@ credential.
    quote. If the tool is not mounted for this fleet, stop and report `blocked`
    saying you could not observe CI; never guess green.
 6. **Green** → stop and report `pushed-green`, quoting that same head SHA.
-   **Red** → diagnose the real cause and make **one** corrective push. Red a
-   second time → stop, do not push again, and report `failed` with the failure
-   digest (job name plus the decisive log lines).
+   **Red** → read what CI actually printed before you touch anything.
+   `conductor_ci_logs()` answers with the failing jobs' own failed steps at that
+   head, through the same bounded log read the dispatcher's own failure
+   classifier uses. It is read-only, it changes nothing, and it is not ledgered
+   — but it is not free in context either: read it once and fix from what it
+   said, rather than polling it or re-running the whole suite locally hoping to
+   reproduce a runner-only failure. If it cannot read the logs it says so; an
+   unreadable log is never reported to you as "no failures". Then make **one**
+   corrective push. Red a second time → stop, do not push again, and report
+   `failed` with the failure digest (job name plus the decisive log lines).
+7. **A runner-infrastructure red does not spend one of those two.** When the
+   failing job's own text says the *runner* failed rather than your diff — it
+   lost communication with the server, it received a shutdown signal, or no
+   runner ever acquired the job — `conductor_ci_logs` says so itself, in the
+   first line of its answer, quoting the wording it matched. That reply is the
+   ruling: do not change the diff for it, do not spend a corrective push on it,
+   wait, and poll `conductor_pr_status` again. If it is still red, stop and
+   report with that wording quoted — the dispatcher re-runs infrastructure
+   checks itself and does not charge the attempt.
+
+   You do not make this call, and you must not claim it. If the reply does not
+   name the infrastructure wording, the red counts, whatever it looks like to
+   you: a job cancelled for reasons the log does not name, a job that ran until
+   its execution-time ceiling, a log that could not be read, a red that "passes
+   locally". When some jobs are infrastructure and one is not, the reply says
+   the red counts — a real failure outranks any number of infra ones, so fix the
+   real one.
 
 ## Your verb surface — what you can do, and what answers back
 
 Editing, building and testing are yours: ordinary `bash` inside your worktree,
-unmediated. What leaves this machine is not. Four tools are the *only* route to
+unmediated. What leaves this machine is not. Five tools are the *only* route to
 GitHub you may take — another one exists on this host, and taking it is a
 reportable breach rather than a shortcut:
 
@@ -169,6 +189,7 @@ reportable breach rather than a shortcut:
 | `conductor_push` | Publishes **this run's branch**, fast-forward only. |
 | `conductor_pr_create` | Opens **this run's** PR: head is your branch, base is the repo default. |
 | `conductor_pr_status` | Reads the live PR state, head and checks. A poll, not a watcher. |
+| `conductor_ci_logs` | Reads the failing CI jobs' own log output at the PR head. Read-only and bounded; call it on a red check you have to diagnose. |
 | `conductor_pr_update_branch` | Merges the base into your PR when it has fallen behind. |
 
 Three things follow, and they are worth reading once rather than rediscovering:
@@ -233,7 +254,11 @@ at session start. The expected shape:
   "prUrl": "https://github.com/.../pull/N",
   "headSha": "<the 40-char head you watched go green>",
   "summary": "What you changed and why — the narrative a reviewer reads.",
-  "proof": ["bun test omp/src/worker.test.ts"]
+  "proof": ["bun test omp/src/worker.test.ts"],
+  "discoveries": [
+    "settlement flags are rendered in omp/src/diff-flags.ts, not in settlement.ts",
+    "store migrations here are PRAGMA-guarded ALTERs — never a table rebuild"
+  ]
 }
 ```
 
@@ -246,6 +271,15 @@ the stored report, so `summary` is what a reviewer reads and `proof` is the
 evidence; the `changed:` file list is derived from the PR's own diff, never
 written by you.
 
+`discoveries` is optional, and it is not about you. It is for durable facts
+about **this repo** that the next worker would otherwise pay turns to
+rediscover: where a behaviour really lives, a convention that is not where you
+looked first, a trap that cost you a turn. The fleet accumulates them per repo
+and renders them into later briefs — so "I fixed the parser" is not a
+discovery, while "the parser's callers are generated from `schema/` and must be
+regenerated with `bun run schema`" is. Leave the field out rather than filling
+it.
+
 Never report success you have not observed. "Should pass CI" is not a state,
 and `green` means you watched the checks go green — not that you expect them
 to.

package/src/cli.ts

@@ -14,12 +14,14 @@ import { armCommand } from "./commands/arm.ts";
 import { boardCommand } from "./commands/board.ts";
 import { companionCommand } from "./commands/companion.ts";
 import { briefUpgradeCommand } from "./commands/brief-upgrade.ts";
+import { consoleCommand } from "./commands/console.ts";
 import { daemonCommand } from "./commands/daemon.ts";
 import { dashboardCommand } from "./commands/dashboard.ts";
 import { decisionCommand } from "./commands/decision.ts";
 import { disarmCommand } from "./commands/disarm.ts";
 import { doctorCommand } from "./commands/doctor.ts";
 import { drainCommand } from "./commands/drain.ts";
+import { epicCommand } from "./commands/epic.ts";
 import { eventCommand } from "./commands/event.ts";
 import { extendCommand } from "./commands/extend.ts";
 import { frictionCommand } from "./commands/friction.ts";
@@ -281,6 +283,7 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     ledger: () => ledgerCommand(ctx),
     board: () => boardCommand(ctx),
     companion: () => companionCommand(ctx),
+    console: () => consoleCommand(ctx),
     dashboard: () => dashboardCommand(ctx),
     hold: () => holdCommand(ctx),
     drain: () => drainCommand(ctx),
@@ -299,6 +302,7 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     decision: () => decisionCommand(ctx),
     watch: () => watchCommand(ctx),
     intake: () => intakeCommand(ctx),
+    epic: () => epicCommand(ctx),
     friction: () => frictionCommand(ctx),
     "restore-db": () => restoreDbCommand(ctx),
     "snapshot-db": () => snapshotDbCommand(ctx),

package/src/command-manifest.ts

@@ -166,6 +166,13 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       toggle("--once", "draw one frame and exit instead of holding the pane"),
     ],
   },
+  {
+    name: "console",
+    description: "provision the operator console workspace and print its pane command",
+    scope: "project",
+    usage: ["console [--project NAME]"],
+    flags: [project()],
+  },
   {
     name: "dashboard",
     description: "serve the read-only browser dashboard",
@@ -263,10 +270,15 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
   },
   {
     name: "arm",
-    description: "prove Telegram delivery and arm scheduled ticks",
+    description: "send the arming challenge, then verify the operator's reply",
     scope: "fleet",
-    usage: ["arm [--project NAME | --all]"],
-    flags: [project(), all()],
+    usage: ["arm [--project NAME | --all]", 'arm --reply "OPERATOR MESSAGE" [--project NAME]'],
+    flags: [value("--reply", "verify the operator's verbatim reply and write the arm marker"), project(), all()],
+    details: `arm files a short-lived challenge, sends it to the paired Telegram owner and returns
+immediately — it never waits for the reply, because the reply lands in the console session.
+Nothing is armed until the second half: pass the operator's message verbatim to
+arm --reply, which classifies it and arms exactly the projects that challenge recorded.
+A wrong, expired or absent code arms nothing and says which of the three it was.`,
   },
   {
     name: "disarm",
@@ -466,6 +478,31 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     ],
     positionals: [{ name: "action" }, { name: "id" }],
   },
+  {
+    name: "epic",
+    description: "approve, revoke, or list standing operator approvals of epic scope",
+    scope: "project",
+    usage: [
+      "epic approve <issue> [--project NAME]",
+      "epic revoke <issue> [--project NAME]",
+      "epic list [--project NAME] [--json]",
+    ],
+    details: `An approved epic is standing consent to its scope: brief-complete children of it pass
+the promotion ready gate and are queued without a fresh operator decision. Approval is a durable
+fact of its own, not a resolved decision row — it never expires, and a gate can read it without
+parsing prose. approve is idempotent and first-write-wins: re-approving keeps the original
+timestamp and reports that nothing changed. revoke withdraws consent, so the epic's children need
+a decision again, and is a no-op on an epic that was never approved. Whether the issue number
+really names an epic is not checked here: parents and children are native GitHub sub-issues, which
+the daemon resolves when it promotes.`,
+    subcommands: [
+      { name: "approve", description: "approve an epic's scope" },
+      { name: "revoke", description: "withdraw an epic's approval" },
+      { name: "list", description: "list approved epics" },
+    ],
+    flags: [toggle("--json", "print the approval list as stable JSON"), project()],
+    positionals: [{ name: "action" }, { name: "issue" }],
+  },
   {
     name: "watch",
     description: "record, list, or withdraw orchestrator-only conditions and carry notes",
@@ -503,22 +540,31 @@ closed first) is withdrawn by the daemon itself.`,
     scope: "project",
     usage: [
       'intake "<text>" [--project NAME]',
-      "intake list [--project NAME]",
+      "intake list [--json] [--project NAME]",
       "intake dismiss <id> [--project NAME]",
       "intake groomed <id> --issue <url> [--project NAME]",
     ],
     details: `Captures one raw idea into the local store and prints its id. list shows what
-is still pending (id, age, text), oldest first; dismiss drops one by id. The
-capture is durable — it lives in the sqlite store, not in a session — so it
+is still pending (id, age, source, text), oldest first; dismiss drops one by id.
+The capture is durable — it lives in the sqlite store, not in a session — so it
 survives daemon restarts. The orchestrator files the idea as an issue and then
 marks that provenance with groomed: an id already resolved is a no-op with a
-message, never an error, because ticks retry.`,
+message, never an error, because ticks retry.
+
+The source column names the signal that filed an item, for the ones the daemon's
+hourly signal-mining pass files itself; a dash means you thought of it. A mined
+item is filed idempotently, so dismissing one dismisses it for good rather than
+seeing it again next hour.`,
     subcommands: [
       { name: "list", description: "list pending intake items" },
       { name: "dismiss", description: "dismiss an intake item" },
       { name: "groomed", description: "link an intake item to its issue" },
     ],
-    flags: [value("--issue", "groomed issue URL"), project()],
+    flags: [
+      value("--issue", "groomed issue URL"),
+      toggle("--json", "print the pending list as stable JSON"),
+      project(),
+    ],
     positionals: [{ name: "text|action" }, { name: "id" }],
   },
   {

package/src/commands/arm.ts

@@ -1,61 +1,125 @@
 /**
- * `arm` — proof-gated: send a Telegram challenge and write the arm marker only after the orchestrator's inbound adapter acknowledges the reply in conductor state (#614).
+ * `arm` — the two mechanical halves of the arming ceremony.
  *
- * Moved out of cli.ts's switch by the per-verb module split (#462);
- * only the case wrapper, the injected `ctx` lookups and the imports
- * changed from the original bodies.
+ * `arm` files a challenge, sends it, and returns immediately naming the
+ * follow-up command. `arm --reply "<the operator's message>"` verifies that
+ * message and writes the arm marker for exactly the projects the challenge
+ * recorded. Nothing waits anywhere: the operator's reply lands in the console
+ * session, which runs no tick extension, so the in-session acknowledgement wait
+ * this replaces could never be satisfied (phase 1 of the orchestrator-workflow
+ * redesign).
+ *
+ * Both halves print copy-pasteable commands, because the reader is usually an
+ * agent in a console pane rather than a human at a prompt.
  */
 
 import type { CommandContext } from "./context.ts";
-import { armFleet, armTicks } from "../fleet.ts";
+import { armFleet, armReply, armTicks, type ArmChallengeSent } from "../fleet.ts";
 import { withProgress } from "../ui/progress.ts";
 
 export async function armCommand(ctx: CommandContext): Promise<void> {
-const targets = ctx.targetProjects();
-// One ceremony for the whole fleet (#991). Two projects used to mean two
-// sequential handshakes with two codes in one chat, though nothing about the
-// fleet's state differed between them. `arm --project X` is untouched: it is
-// still exactly one project, one challenge, one marker.
-if (ctx.projectFlag === undefined && targets.length > 1) {
-  const r = await withProgress(
-    "arm: verifying one arming proof for the fleet…",
-    "Arming proof verified",
-    () =>
-      armFleet(
-        targets.map((project) => project.name),
-        { progress: (line) => process.stdout.write(`${line}\n`) },
-      ),
-    { plainMessage: true },
-  );
-  process.stdout.write(
-    `ARMED — one inbound round-trip proved with owner ${r.owner}; ticks are now live for ${String(r.armed.length)} project(s).\n` +
-      r.armed
-        .map(
-          (project) =>
-            `  ${project.project}: marker ${project.path}${project.alreadyArmed ? " (replaced previous marker)" : ""}`,
-        )
-        .join("\n") +
-      "\n",
-  );
-  return;
+  const reply = replyArgument(ctx);
+  if (reply !== undefined) {
+    // The verification half is one store read and (on a match) the marker
+    // writes: no send, no network, nothing to narrate.
+    const result = armReply(reply, ctx.projectFlag);
+    if (result.outcome === "refused") throw new Error(result.message);
+    process.stdout.write(
+      `ARMED — reply verified for owner ${result.owner}; ticks are now live for ` +
+        `${String(result.armed.length)} project(s).\n` +
+        result.armed
+          .map(
+            (project) =>
+              `  ${project.project ?? "this fleet"}: marker ${project.path}` +
+              `${project.alreadyArmed ? " (replaced previous marker)" : ""}`,
+          )
+          .join("\n") +
+        `\nchallenge ${result.challengeId} is settled — the same code cannot arm anything again.\n`,
+    );
+    return;
+  }
+
+  const targets = ctx.targetProjects();
+  // One ceremony for the whole fleet (#991). Two projects used to mean two
+  // sequential handshakes with two codes in one chat, though nothing about the
+  // fleet's state differed between them. `arm --project X` is untouched: it is
+  // still exactly one project, one challenge, one marker.
+  if (ctx.projectFlag === undefined && targets.length > 1) {
+    const sent = await withProgress(
+      "arm: sending one arming challenge for the fleet…",
+      "Arming challenge sent",
+      () =>
+        armFleet(
+          targets.map((project) => project.name),
+          { progress: (line) => process.stdout.write(`${line}\n`) },
+        ),
+      { plainMessage: true },
+    );
+    process.stdout.write(challengeReceipt(sent));
+    return;
+  }
+  for (const project of targets) {
+    // Proof-neutral wording: `claim-only` performs no Telegram send, so the
+    // progress line cannot promise a challenge that never goes out (#613). The
+    // result line names the proof that actually settled it.
+    const result = await withProgress(
+      "arm: verifying the arming proof…",
+      "Arming proof settled",
+      () => armTicks(project.name, { progress: (line) => process.stdout.write(`${line}\n`) }),
+      { plainMessage: true },
+    );
+    if (result.outcome === "armed") {
+      process.stdout.write(
+        `ARMED — claim-only plumbing verdict proved; ticks are now live.\n` +
+          result.armed
+            .map(
+              (armed) =>
+                `marker ${armed.path}${armed.alreadyArmed ? " (replaced previous marker)" : ""}`,
+            )
+            .join("\n") +
+          "\n",
+      );
+      continue;
+    }
+    process.stdout.write(challengeReceipt(result));
+  }
 }
-for (const project of targets) {
-  // Proof-neutral wording: `claim-only` performs no Telegram send, so the
-  // progress line cannot promise a challenge that never goes out (#613). The
-  // result line names the proof that actually armed it.
-  // The pending-proof heartbeat goes straight to stdout (#861): a challenge
-  // waits on a human for up to five minutes, and `withProgress`'s single step
-  // line cannot say how much of that window is left. Written unconditionally —
-  // a piped or plain-UI run needs it more than a TTY does, not less.
-  const r = await withProgress(
-    "arm: verifying the arming proof…",
-    "Arming proof verified",
-    () => armTicks(project.name, { progress: (line) => process.stdout.write(`${line}\n`) }),
-    { plainMessage: true },
-  );
-  process.stdout.write(
-    `ARMED — ${r.proof === "claim-only" ? "claim-only plumbing verdict proved" : `inbound round-trip proved with owner ${r.owner}`}; ticks are now live.\n` +
-      `marker ${r.path}${r.alreadyArmed ? " (replaced previous marker)" : ""}\n`,
+
+/**
+ * The challenge half's receipt: what was sent, how long it lasts, what a reply
+ * will arm, and the exact command that arms it. The follow-up line is written
+ * verbatim from the result so the printed command and the recorded transaction
+ * can never disagree.
+ */
+function challengeReceipt(sent: ArmChallengeSent): string {
+  return (
+    `CHALLENGE SENT — a code went to owner ${sent.owner}, valid for ${sent.validFor} ` +
+    `(challenge ${sent.challengeId}).\n` +
+    `NOTHING IS ARMED YET. When the operator replies, run:\n` +
+    `  ${sent.followUp}\n` +
+    `That reply will arm ${String(sent.targets.length)} project(s):\n` +
+    sent.targets
+      .map((target) => `  ${target.project ?? "this fleet"}: marker ${target.armedFile}`)
+      .join("\n") +
+    "\n"
   );
 }
+
+/**
+ * The `--reply` payload, refusing the shapes that would otherwise send a fresh
+ * challenge instead of verifying one. A bare `--reply` (no value) or an empty
+ * string is a mistake worth naming: silently re-arming from a verification
+ * attempt would leave the operator with two live codes and no idea why.
+ */
+function replyArgument(ctx: CommandContext): string | undefined {
+  const value = ctx.flag("reply");
+  const present = ctx.argv.includes("--reply") || ctx.argv.some((token) => token.startsWith("--reply="));
+  if (!present) return undefined;
+  if (value === undefined || value.trim().length === 0) {
+    throw new Error(
+      `arm --reply needs the operator's message, verbatim — for example: ` +
+        `omp-conductor arm --reply "FLEET-1A2B3C4D"`,
+    );
+  }
+  return value;
 }

package/src/commands/console.ts

@@ -0,0 +1,70 @@
+/**
+ * `omp-conductor console` — provision the operator console's workspace and
+ * print the pane command that launches it.
+ *
+ * The console is the second session of the two-session split: the tick brain
+ * keeps its pane and never receives an operator turn, and the console owns the
+ * Telegram conversation. This verb materialises the console's side of that —
+ * its own cwd, the rendered floor, the `AGENTS.md` link that makes an `omp`
+ * started there load the floor — and then says exactly how to launch it.
+ *
+ * Idempotent by construction: the plan reports `keep` for a current brief and a
+ * correct link, so a re-run rewrites nothing. That matters because both this
+ * verb and `setup host` provision the same workspace through the same
+ * `planConsole`/`writeConsole` pair, and an operator will run whichever they
+ * remember.
+ *
+ * It launches nothing. `recover.sh` owns pane restoration for the whole fleet
+ * (exact-identity rules, one companion per role), so a verb that spawned its
+ * own pane here would be a second pane nobody reconciles.
+ */
+
+import { findProject, loadConfig } from "../config.ts";
+import { consolePaneCommand, planConsole, writeConsole, type ConsolePlan, type ConsoleWrite } from "../setup.ts";
+import type { CommandContext } from "./context.ts";
+
+/**
+ * The whole printed report, as lines, from facts a caller already holds.
+ *
+ * Pure so the byte-exact pane command is assertable without a config, a state
+ * directory or a captured stdout — the pane command is a contract shared with
+ * `recover.sh`, and a test that could only check "contains omp" would not hold
+ * it.
+ *
+ * `otherProjects` is the DM-force-claim decision, expressed as its evidence
+ * rather than as a boolean: one Telegram state dir may have exactly one DM
+ * owner, so the claim is this console's only when no other project is
+ * configured — and when it is not, the operator is told which projects took it
+ * away.
+ */
+export function consoleReport(
+  plan: ConsolePlan,
+  written: ConsoleWrite,
+  otherProjects: readonly string[],
+): string[] {
+  const dmOwner = otherProjects.length === 0;
+  const pane = consolePaneCommand({ cwd: plan.cwd, dmOwner });
+  return [
+    `console cwd    ${plan.cwd}`,
+    `console brief  ${plan.brief.action} ${plan.brief.path}`,
+    plan.link.action === "skip"
+      ? `console link   ${plan.link.path} — ${plan.link.skippedReason}`
+      : `console link   ${plan.link.action} ${plan.link.path} -> ${plan.link.target}`,
+    `pane command   ${pane}`,
+    dmOwner
+      ? "dm owner       yes — this host configures exactly one project, so the console force-claims the Telegram DM owner"
+      : `dm owner       no — this host also configures ${otherProjects.join(", ")}, and one Telegram state dir has exactly one DM owner; inbound reaches this console by forum-topic routing instead`,
+    `recovery       recover.sh restores this pane with the fleet; by hand, run: ${pane}`,
+    ...(written.wrote.length === 0 ? [] : [`wrote          ${written.wrote.join(", ")}`]),
+    ...written.warnings.map((w) => `warning        ${w}`),
+  ];
+}
+
+export function consoleCommand(ctx: CommandContext): void {
+  const cfg = loadConfig();
+  const project = findProject(cfg, ctx.projectFlag);
+  const plan = planConsole(project);
+  const written = writeConsole(plan);
+  const others = cfg.projects.filter((p) => p.name !== project.name).map((p) => p.name);
+  process.stdout.write(`${consoleReport(plan, written, others).join("\n")}\n`);
+}

package/src/commands/context.ts

@@ -82,8 +82,10 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   // project — exactly one project; findProject demands --project when several
   "brief-upgrade": "project",
   companion: "project",
+  console: "project",
   decision: "project",
   drain: "project",
+  epic: "project",
   event: "project",
   extend: "project",
   friction: "project",

package/src/commands/epic.ts

@@ -0,0 +1,132 @@
+/**
+ * `epic` — approve, revoke, or list the operator's standing approvals of epic
+ * scope (#1041).
+ *
+ * The operator surface over the `epic_approvals` table. Approving an epic means
+ * exactly one thing: its brief-complete children may pass the ready gate and be
+ * queued without asking the operator again. That is why it is a dedicated
+ * durable fact and not a resolved decision row — a decision's answer is free
+ * text written for a human, and the promotion gate needs a boolean it can read
+ * without parsing prose.
+ *
+ * Whether the issue number names a real epic is the tracker's business, not this
+ * verb's: parents and children are native GitHub sub-issues, resolved by the
+ * daemon at promotion time. Reading the tracker here would trade a network round
+ * trip and a rate-limit failure mode for a check the gate performs anyway.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, openStore } from "../store.ts";
+import { dim, ok } from "../ui/style.ts";
+import { SESSION_ROLE_ENV } from "../types.ts";
+
+/** The flags each subcommand accepts after the subcommand itself. Declared so a
+ *  typo'd flag exits 2 instead of being ignored while the approval still lands. */
+const EPIC_FLAGS: Readonly<Record<string, readonly string[]>> = {
+  approve: ["--project"],
+  revoke: ["--project"],
+  list: ["--project", "--json"],
+};
+
+/**
+ * Rejects trailing tokens a subcommand does not declare (the #793 shape: a
+ * real-looking flag that belongs to another verb must not be silently dropped).
+ * Starts at index 2 because index 0 is the verb and index 1 the subcommand; the
+ * issue positional is consumed by the caller before this runs.
+ */
+function assertKnownArgs(ctx: CommandContext, sub: string, from: number): void {
+  const allowed = EPIC_FLAGS[sub] ?? [];
+  for (let i = from; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    const eq = token.startsWith("--") ? token.indexOf("=") : -1;
+    const name = eq < 0 ? token : token.slice(0, eq);
+    if (allowed.includes(name)) {
+      // `--json` takes no value, so only a value-taking flag swallows the next
+      // token. `--project` is the only one here.
+      if (eq < 0 && name === "--project") i += 1;
+      continue;
+    }
+    process.stderr.write(`omp-conductor: epic ${sub}: unexpected argument "${token}"\n`);
+    process.exit(2);
+  }
+}
+
+export async function epicCommand(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[1];
+  if (sub !== "approve" && sub !== "revoke" && sub !== "list") {
+    process.stderr.write(
+      sub === undefined
+        ? "omp-conductor: epic needs approve, revoke or list\n"
+        : `omp-conductor: unknown epic subcommand "${sub}" — expected approve, revoke or list\n`,
+    );
+    process.exit(2);
+  }
+  // The issue positional is validated before the config or store is opened, so a
+  // typo'd number never creates a database on a fresh host.
+  const issue = sub === "list" ? 0 : ctx.issueArg(`epic ${sub}`, ctx.argv[2]);
+  assertKnownArgs(ctx, sub, sub === "list" ? 2 : 3);
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const store = openStore(dbPath());
+  try {
+    if (sub === "approve") {
+      // Read first, because `approveEpic` is first-write-wins and returns
+      // nothing: the operator must be told which of the two happened, and a
+      // silent second approve that looks identical to the first is exactly how
+      // an operator concludes the approval did not stick.
+      const existing = store.epicApproval(project.name, issue);
+      if (existing !== undefined) {
+        process.stdout.write(
+          `epic #${issue} was already approved for ${project.name} by ${existing.approvedBy} at ` +
+            `${new Date(existing.approvedAt).toISOString()} — nothing changed\n`,
+        );
+        return;
+      }
+      // The same identity spelling `report withdraw` uses: the session role when
+      // one is set, else orchestrator inside a Herdr pane, else a human at a
+      // shell. Provenance for an audit line, never a gate.
+      const sessionRole = process.env[SESSION_ROLE_ENV];
+      const inHerdrPane = process.env["HERDR_ENV"] !== undefined && process.env["HERDR_ENV"] !== "";
+      const by = sessionRole ?? (inHerdrPane ? "orchestrator" : "operator");
+      store.approveEpic(project.name, issue, Date.now(), by);
+      process.stdout.write(
+        ok(`epic #${issue} approved for ${project.name} by ${by}`) + "\n",
+      );
+      process.stdout.write(
+        dim(
+          "brief-complete children of this epic may now be queued without a new operator decision — " +
+            `revoke with: omp-conductor epic revoke ${issue} --project ${project.name}`,
+        ) + "\n",
+      );
+      return;
+    }
+
+    if (sub === "revoke") {
+      const revoked = store.revokeEpicApproval(project.name, issue);
+      process.stdout.write(
+        revoked
+          ? ok(`epic #${issue} approval revoked for ${project.name} — its children need a decision again`) + "\n"
+          : `epic #${issue} was not approved for ${project.name} — nothing to revoke\n`,
+      );
+      return;
+    }
+
+    const approvals = store.epicApprovals(project.name);
+    if (ctx.argv.includes("--json")) {
+      process.stdout.write(`${JSON.stringify({ project: project.name, epics: approvals }, null, 2)}\n`);
+      return;
+    }
+    if (approvals.length === 0) {
+      process.stdout.write("no approved epics\n");
+      return;
+    }
+    for (const approval of approvals) {
+      process.stdout.write(
+        `#${approval.issue}  ${new Date(approval.approvedAt).toISOString()}  ${approval.approvedBy}\n`,
+      );
+    }
+  } finally {
+    store.close();
+  }
+}