omp-conductor 0.2.2 → 0.3.2

package/src/briefs/orchestrator.md

@@ -27,7 +27,10 @@ You are prompted on a timer. Each tick: do the three duties below, then stop.
 ## Coordinates
 
 - **Tracker:** {{TRACKER_REPO}}
-- **Queue label:** `{{QUEUE_LABEL}}` — a human puts it on. You never add it.
+- **Queue label:** `{{QUEUE_LABEL}}` — the claim gate, and the sign-off it stands
+  for. Adding it to an issue is *promotion*, and whether promotion is yours is
+  Duty 2's business and your operator's policy below, not a fixed rule here.
+  Never add it to an issue you have not read.
 - **State labels:** the conductor writes `agent:in-progress`, `agent:blocked` and
   `agent:failed` (whatever you renamed them to in setup). Read them; never
   hand-edit them, or the loop and the tracker will disagree about what is live.
@@ -45,14 +48,17 @@ gh issue list --repo {{TRACKER_REPO}} --state open --label agent:failed
 For each one, pick exactly one of three outcomes:
 
 - **You can answer it.** The worker hit an ambiguity that repo convention, the
-  issue thread, or an ADR already settles. Comment the answer on the issue,
-  remove the blocked label, and let the next tick re-claim it.
+  issue thread, or an ADR already settles. Comment the answer on the issue, then
+  run `omp-conductor unblock <n>`, and let the next tick re-claim it. That verb,
+  never a label edit, is how an answered block re-enters the queue: it clears the
+  state label through the same tracker the dispatcher writes with, which is why
+  the rule above stays absolute — orphan detection is only trustworthy while
+  every state label on the tracker was written by the conductor.
 - **You cannot.** It needs a product, UX, data-migration, credential, release or
   infrastructure decision. Escalate it (tier 2) with the issue link and the one
   question that unblocks it. Do not guess: a wrong answer costs a worker's whole
   budget and lands a wrong PR, while an unanswered question costs a delay.
-- **It is already done.** The PR is green and waiting on a human merge. Note it,
-  with the link, and move on. You do not merge it.
+{{MERGE_DUTY}}
 
 **Then check for orphans.** A worker is a process, and processes die: a daemon
 restart, a host reboot, a kill. The `agent:in-progress` label survives that death
@@ -69,7 +75,7 @@ directions), then the worktree (`git status --porcelain`, `git log
 origin/main..HEAD`) and any PR. Four cases, checked in this order:
 
 - **An open PR that is green.** That worker finished; it just never got to report.
-  This is the "already done" case above: note it with the link and move on. Never
+  This is the "already done" case above — handle it exactly the same way. Never
   release-and-re-claim it — a fresh worker would duplicate a finished run.
 - **A dirty tree** (uncommitted edits in the worktree). This is the one thing a
   re-claim destroys: the conductor removes and reattaches worktrees with `--force`
@@ -98,6 +104,14 @@ Keep the queue worth draining.
 - An issue with unreadable acceptance criteria will burn a whole worker budget.
   Rewrite them as a checklist on the issue, or take the queue label off and say
   why on the issue.
+- A worker's turns are mostly spent *finding* code, not writing it, and a big
+  repo can eat the whole budget in reads. Every issue you promote names its
+  entry points: the files to change, the files that prove the convention, the
+  test that will exercise it. Measured on this package's own fleet: six
+  turn-cap kills in one night, every one an issue promoted without paths, while
+  the one issue whose defect had been traced first landed in 92 of 120 turns.
+  Tracing before promoting is your work, once — or it is every worker's work,
+  every attempt.
 - An issue that has exhausted its attempts is not a retry candidate. Diagnose it,
   split it, or hand it back to a human.
 
@@ -140,11 +154,20 @@ Not yours to relax:
 - **Every claim cites evidence:** a PR URL, an issue number, or a named check you
   actually read. "Should be fine", "looks green" and "probably passing" are not
   evidence. If you did not read the check result, say that instead of asserting.
-
-**Your own** merge and release authority is not decided here. It lives in
-**Releases** below, and unedited it is none: you do not merge, tag, publish or
-deploy either. That is a default your operator can change deliberately, in that
-section. The three boundaries above are not.
+- **Nobody patches the running conductor.** The package dispatching this fleet —
+  its installed plugin, CLI and daemon — is never edited in place, not by you and
+  not by a worker. A conductor bug or improvement is an issue on the conductor's
+  own repo (the Learning loop says when to file one); what lands on this host is
+  a whole built version — a release, or a test build — and your operator installs
+  it, never you. A fleet that patches its own dispatcher is a fleet whose
+  behavior nobody can reproduce, and the next install silently reverts the
+  patch, which is worse than never having made it.
+
+**Your own** merge and release authority is not decided here. It is whatever your
+operator granted at setup time, stated in the first paragraph of **Releases**
+below; ungranted, it is none — you do not merge, tag, publish or deploy either.
+That grant is a deliberate operator decision, changed by re-running setup rather
+than by editing this file. The four boundaries above are not.
 
 ## Learning loop
 
@@ -198,9 +221,7 @@ amendment waits for the three duties to finish, it never interrupts them.
 
 ## Releases (yours to define)
 
-**Default: humans release, and you do not merge.** Work ends at a green PR;
-merging is a separate human action, and releasing is a separate human action after
-that. "This needs releasing" is something you report, never something you take on.
+{{RELEASES_DEFAULT}}
 
 Releases are yours or nobody's. A worker can never take them, so this section is
 the only place they can be delegated, and it is the only place your merge
@@ -258,6 +279,17 @@ Your report scope is **`{{REPORT_SCOPE}}`**. Both scopes, spelled out:
   issue you pulled off the queue, a cap that stopped the fleet. A tick where
   nothing changed still says nothing — "no change" is not an event.
 
+**Delivery.** Your end-of-turn text reaches your operator only on a turn that
+*began* as an inbound Telegram message. A tick did not: it is injected locally,
+so a report you merely write at the end of one is read by nobody, however well
+you wrote it. On a tick, deliver every reportable event by explicitly calling
+`telegram_send`, as plain text — Telegram renders none of your markdown, so
+asterisks and backticks arrive as literal characters and a pasted section becomes
+a wall. Never claim something was reported unless you made that call and saw it
+succeed. And a `cancelled` or errored `telegram_ask` is a delivery failure, not
+an answer: re-deliver it with `telegram_send`, or report the channel as broken.
+It is never "asked once, no reply, dropped".
+
 Neither scope licenses narration. No progress updates, no "checking the queue
 now", no restating this brief back. Evidence, or silence.
 

package/src/briefs/worker.md

@@ -34,8 +34,15 @@ files are canonical; your priors are not.
 
 ## How to work
 
-1. **Understand before editing.** Trace the real flow end to end — every file the
-   change touches. Grep the callers of any function you are about to change; the
+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
+   mid-refactor loses the run. If code-graph MCP tools are mounted (a
+   `codebase-memory` server or similar), start there: list its indexed projects,
+   and query by **project name** — your worktree is a throwaway path the index
+   has never seen, so a cwd-based lookup finds nothing while the canonical
+   checkout's index has the whole call graph. Fall back to grep where the graph
+   is silent. Either way, trace the real flow end to end — every file the change
+   touches — and check the callers of any function you are about to change; the
    smallest diff in the wrong place is a second bug.
 2. **Follow existing patterns.** A second convention beside an existing one is a
    defect. Reuse the helper that already exists rather than writing a sibling.

package/src/cli.ts

@@ -5,13 +5,26 @@
  * process lifecycle in ./lifecycle.ts, so the CLI and the `/conductor` plugin
  * cannot drift apart.
  */
-import { readFileSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
-import { findProject, loadConfig } from "./config.ts";
-import { formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
-import { healthCheck, livingDaemon, startDaemon, stopDaemon } from "./lifecycle.ts";
+import { findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
+import { dbPath, formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
+import {
+  clearRecord,
+  DEFAULT_PORT,
+  healthCheck,
+  livingDaemon,
+  startDaemon,
+  stopDaemon,
+  writeRecord,
+} from "./lifecycle.ts";
+import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
 import { briefPathForProject, renderBriefForProject, shippedBriefTemplate } from "./setup.ts";
+import { LIVE_STATES, openStore } from "./store.ts";
+import { makeTracker } from "./tracker/github.ts";
 import type { ProjectConfig } from "./types.ts";
+import { formatUnblock, unblockIssue } from "./unblock.ts";
 
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
@@ -20,6 +33,8 @@ usage:
   omp-conductor stop
   omp-conductor restart [--port N] [--project NAME]
   omp-conductor status [--project NAME]
+  omp-conductor tail <issue> [--project NAME]
+  omp-conductor unblock <issue> [--project NAME]
   omp-conductor daemon [--once] [--port N] [--project NAME]
   omp-conductor pause
   omp-conductor resume
@@ -34,6 +49,16 @@ usage:
            unless a flag overrides them.
   status   show pause state, caps, active runs, today's usage, and whether a
            daemon is alive.
+  tail     follow the newest run for <issue>: the worker's assistant text and
+           the tools it calls, printed as they land. Workers are sessions inside
+           the daemon rather than terminals, so this is the only way to watch
+           one live. Runs until Ctrl-C, or until the run has finished and its
+           transcript has stopped growing.
+  unblock  clear <issue>'s blocked and failed labels so the next tick can claim
+           it again — the supported way back for an escalation you answered,
+           and why the brief's "never hand-edit a state label" rule can stay
+           absolute. Attempts already spent are kept: an answered block still
+           cost a worker.
   daemon   run the dispatch loop in the foreground; --once runs a single tick
            and exits. This is what \`start\` launches.
   pause    stop claiming new work. The running daemon notices on its next tick.
@@ -49,9 +74,10 @@ usage:
   help     print this text (also --help, -h).
 
 Pause is a flag file under the state directory, so it applies to every project
-and survives a daemon restart. The background daemon is tracked by a pidfile
-under $OMP_CONDUCTOR_RUNTIME_DIR (default ~/.omp/run/daemons/omp-conductor),
-whose liveness is probed on every read — a stale one never blocks a start.`;
+and survives a daemon restart. A running daemon is tracked by a pidfile under
+$OMP_CONDUCTOR_RUNTIME_DIR (default ~/.omp/run/daemons/omp-conductor), written
+whether it was started in the background or in the foreground, and probed for
+liveness on every read — a stale one never blocks a start.`;
 
 /** Accepts both `--port 9000` and `--port=9000`; returns undefined when absent. */
 function flag(argv: string[], name: string): string | undefined {
@@ -108,17 +134,248 @@ async function daemonSection(): Promise<string> {
   ].join("\n");
 }
 
+/**
+ * The orchestrator half, and the one thing `status` has ever known about the
+ * supervising session: the stall marker its heartbeat writes when its own
+ * prompts stop being consumed (see {@link STALL_MARKER_FILE}).
+ *
+ * The marker is written in the *session's* cwd, which this process has no way
+ * to discover — so this reads the state directory, on the reference deploy's
+ * convention that the orchestrator session runs from exactly there. That makes
+ * the reading one-directional: a line printed here is proof of a wedge, and no
+ * line is proof of nothing at all. On a fleet whose session lives elsewhere the
+ * check is simply inert, which is why it never prints a reassuring "healthy".
+ */
+function stallLine(): string | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(join(stateDir(), STALL_MARKER_FILE), "utf8").trim();
+  } catch {
+    return undefined;
+  }
+  // "<ISO timestamp> <one-line diagnosis>". A file truncated by something else
+  // still gets reported: that the marker exists at all is the news.
+  const cut = raw.indexOf(" ");
+  const since = cut < 0 ? raw : raw.slice(0, cut);
+  const diagnosis = cut < 0 ? "" : ` — ${raw.slice(cut + 1)}`;
+  return `orchestrator   STALLED since ${since === "" ? "an unrecorded time" : since}${diagnosis}`;
+}
+
+/**
+ * `DaemonRecord.logFile` for a daemon nobody spawned. The field is required and
+ * `status` prints it, so it has to say something true: a foreground daemon
+ * opened no log of its own — whoever started it owns its stdout, be that
+ * systemd's journal, a terminal, or a pane.
+ */
+const FOREGROUND_LOG = "<inherited stdout — started in the foreground>";
+
+/** How often `tail` re-stats the transcript it is following. */
+const TAIL_POLL_MS = 1_000;
+
+/**
+ * How long the transcript must stay unchanged, after its run has left the live
+ * states, before `tail` calls it over. The state flips from the daemon's thread
+ * while the harness may still be flushing its last message, so exiting on the
+ * state alone truncates the ending an operator ran this command to watch.
+ */
+const TAIL_QUIET_MS = 5_000;
+
+/**
+ * The `<issue>` positional, for the two verbs that take one. Exits 2 rather
+ * than following run #NaN or clearing the labels of issue #0; `verb` is named
+ * in the message so the operator is told which of the two they mistyped.
+ */
+function issueArg(verb: string, raw: string | undefined): number {
+  const issue = raw === undefined ? Number.NaN : Number.parseInt(raw.replace(/^#/, ""), 10);
+  if (!Number.isInteger(issue) || issue < 1) {
+    process.stderr.write(`omp-conductor: ${verb} needs an issue number, got "${raw ?? ""}"\n`);
+    process.exit(2);
+  }
+  return issue;
+}
+
+/** Read one property off an unvalidated transcript entry. */
+function prop(source: unknown, key: string): unknown {
+  if (source === null || typeof source !== "object") return undefined;
+  return Reflect.get(source, key);
+}
+
+/**
+ * One transcript line rendered for somebody watching, or `undefined` for the
+ * lines not worth a row: thinking blocks, tool results, session metadata, and
+ * anything this parser does not recognise.
+ *
+ * Defensive throughout. The transcript is written by the harness, not by this
+ * package, so its shape is a peer dependency's business and can gain entry
+ * types without warning. A `tail` that dies on one unfamiliar line is strictly
+ * worse than one that skips it — the operator is watching a run they have no
+ * other window onto.
+ */
+function formatTranscriptLine(line: string): string | undefined {
+  let entry: unknown;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (prop(entry, "type") !== "message") return undefined;
+  const message = prop(entry, "message");
+  if (prop(message, "role") !== "assistant") return undefined;
+
+  const content = prop(message, "content");
+  // The harness writes an array of blocks; a bare string is the degenerate form
+  // some sessions still produce, and dropping it would silently lose the text.
+  if (typeof content === "string") {
+    return content.trim() === "" ? undefined : `assistant: ${content.trim()}`;
+  }
+
+  const blocks: readonly unknown[] = Array.isArray(content) ? content : [];
+  const out: string[] = [];
+  for (const block of blocks) {
+    const type = prop(block, "type");
+    if (type === "text") {
+      const text = prop(block, "text");
+      if (typeof text === "string" && text.trim() !== "") out.push(`assistant: ${text.trim()}`);
+    } else if (type === "toolCall") {
+      const name = prop(block, "name");
+      if (typeof name === "string" && name !== "") out.push(`tool: ${name}`);
+    }
+  }
+  return out.length === 0 ? undefined : out.join("\n");
+}
+
+/**
+ * Follow one run's transcript the way `tail -f` follows a log.
+ *
+ * Reads from byte zero rather than from the end: attaching to a worker that is
+ * already ten turns in and then showing nothing until turn eleven is not
+ * watching the run. Polls `stat` instead of taking a file watcher because the
+ * transcript is a plain append-only file that may sit on a filesystem where
+ * change events are a polite fiction, and one stat a second costs nothing.
+ *
+ * SIGINT is deliberately left to its default, which is immediate exit. Nothing
+ * here is buffered, and a handler could only add a poll interval of latency to
+ * every Ctrl-C.
+ */
+async function tailRun(project: string, issue: number): Promise<void> {
+  // Read-only in practice: the store is opened WAL with a busy timeout, so this
+  // never contends with the daemon writing the same rows.
+  const store = openStore(dbPath());
+  try {
+    const run = store.latestRun(project, issue);
+    if (run === undefined) throw new Error(`no run recorded for #${issue}`);
+    const path = run.sessionFile;
+    // Claimed but not yet started, or an attempt whose session never opened one.
+    if (path === undefined) throw new Error(`no transcript yet (state: ${run.state})`);
+
+    const fd = openSync(path, "r");
+    try {
+      let offset = 0;
+      let pending = Buffer.alloc(0);
+      let lastChange = Date.now();
+
+      for (;;) {
+        let size = offset;
+        try {
+          size = statSync(path).size;
+        } catch {
+          // A transcript that vanishes mid-follow is not worth crashing over.
+          // The run's own state, below, is what decides when this command ends.
+        }
+        // Shorter than what we have already read means truncated or replaced;
+        // resuming from the old offset would read the middle of another file.
+        if (size < offset) {
+          offset = 0;
+          pending = Buffer.alloc(0);
+        }
+        if (size > offset) {
+          const chunk = Buffer.allocUnsafe(size - offset);
+          const read = readSync(fd, chunk, 0, chunk.length, offset);
+          offset += read;
+          // Split on newlines as bytes, not as text: a UTF-8 sequence straddling
+          // a read boundary would be mangled by decoding each chunk on its own.
+          pending = Buffer.concat([pending, chunk.subarray(0, read)]);
+          for (;;) {
+            const nl = pending.indexOf(0x0a);
+            if (nl < 0) break;
+            const rendered = formatTranscriptLine(pending.subarray(0, nl).toString("utf8"));
+            pending = pending.subarray(nl + 1);
+            if (rendered !== undefined) process.stdout.write(`${rendered}\n`);
+          }
+          if (read > 0) lastChange = Date.now();
+        }
+
+        // Re-read this exact run every poll — not `latestRun`, which would jump
+        // to a retry started meanwhile and report its state against the wrong
+        // transcript. The daemon writes the row from another process, so looking
+        // is the only way to notice the run finished.
+        const state = store.getRun(run.id)?.state ?? run.state;
+        if (!LIVE_STATES.includes(state) && Date.now() - lastChange >= TAIL_QUIET_MS) {
+          process.stdout.write(`run ended: ${state}\n`);
+          return;
+        }
+        await new Promise<void>((resolve) => setTimeout(resolve, TAIL_POLL_MS));
+      }
+    } finally {
+      closeSync(fd);
+    }
+  } finally {
+    store.close();
+  }
+}
+
 const argv = process.argv.slice(2);
 const cmd = argv[0];
 
 try {
   switch (cmd) {
     case "daemon": {
-      await runDaemon({
-        once: argv.includes("--once"),
-        port: portFlag(argv),
-        project: flag(argv, "project"),
-      });
+      // Until now only `lifecycle.startDaemon()` — the spawn path — wrote the
+      // pidfile, which left a daemon started in the foreground (which is how
+      // systemd runs it) invisible twice over: `omp-conductor status` reported
+      // no daemon at all, and a `daemon --once` drill run beside it saw
+      // `livingDaemon() === undefined`, concluded nothing else was dispatching,
+      // and reconciled the live daemon's in-flight runs as orphans. Writing the
+      // record here closes both holes.
+      const once = argv.includes("--once");
+      const port = portFlag(argv);
+      const project = flag(argv, "project");
+
+      // `--once` registers nothing, on purpose. It is precisely the single-tick
+      // drill the orphan guard exists to protect, so a drill that announced
+      // itself as the daemon would be the process that misleads the next reader
+      // — and would clear the real daemon's record on its way out.
+      if (once) {
+        await runDaemon({ once, port, project });
+        break;
+      }
+
+      const running = livingDaemon();
+      if (running !== undefined && running.pid !== process.pid) {
+        process.stderr.write(`omp-conductor: another daemon is alive (pid ${running.pid}); stop it first\n`);
+        process.exit(1);
+      }
+
+      // A living record that already names this pid was written by the `start`
+      // that spawned us, and it knows the log file our stdout is really going
+      // to. Replacing it with a guess would be a downgrade.
+      if (running === undefined) {
+        writeRecord({
+          pid: process.pid,
+          port: port ?? DEFAULT_PORT,
+          startedAt: Date.now(),
+          logFile: FOREGROUND_LOG,
+          ...(project === undefined ? {} : { project }),
+        });
+      }
+
+      try {
+        await runDaemon({ once, port, project });
+      } finally {
+        // The record names a pid that is about to stop existing. Leaving it
+        // behind makes the next reader probe a ghost before believing us.
+        clearRecord();
+      }
       break;
     }
 
@@ -159,7 +416,28 @@ try {
 
     case "status": {
       const snapshot = formatStatus(statusSnapshot(flag(argv, "project")));
-      process.stdout.write(`${snapshot}\n\n${await daemonSection()}\n`);
+      const stalled = stallLine();
+      process.stdout.write(`${snapshot}\n\n${await daemonSection()}\n${stalled === undefined ? "" : `\n${stalled}\n`}`);
+      break;
+    }
+
+    case "tail": {
+      const issue = issueArg("tail", argv[1]);
+      await tailRun(findProject(loadConfig(), flag(argv, "project")).name, issue);
+      break;
+    }
+
+    case "unblock": {
+      const issue = issueArg("unblock", argv[1]);
+      const cfg = loadConfig();
+      const project = findProject(cfg, flag(argv, "project"));
+      const store = openStore(dbPath());
+      try {
+        const outcome = await unblockIssue(project, makeTracker(project), store, issue);
+        process.stdout.write(`${formatUnblock(issue, outcome, project, resolveCaps(project, cfg.defaults))}\n`);
+      } finally {
+        store.close();
+      }
       break;
     }
 

package/src/config.ts

@@ -16,9 +16,12 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, wri
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import {
+  AUTHORITY_HOLDERS,
   CONFIG_VERSION,
+  DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_REPORT_SCOPE,
+  ORCHESTRATOR_MODES,
   READABLE_CONFIG_VERSIONS,
   REPORT_SCOPES,
   type Caps,
@@ -43,8 +46,10 @@ type Raw = { readonly [key: string]: unknown };
 /** Derived from the data so a new `Caps` field cannot be silently ignored. */
 const CAP_KEYS = Object.keys(DEFAULT_CAPS) as (keyof Caps)[];
 
-/** Quoted for error messages, from the same data the guard below reads. */
-const REPORT_SCOPE_LIST = REPORT_SCOPES.map((s) => `"${s}"`).join(" or ");
+/** Quoted for error messages, from the same data the guards below read. */
+const REPORT_SCOPE_LIST = quoteList(REPORT_SCOPES);
+const AUTHORITY_HOLDER_LIST = quoteList(AUTHORITY_HOLDERS);
+const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
 
 /** `owner/repo`, the only tracker spelling `gh` accepts without a host. */
 const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
@@ -267,13 +272,8 @@ function normalizeProject(
 
   const stateLabels = raw["stateLabels"] as Raw | undefined;
 
-  const escalationIn = raw["escalation"] as Raw | undefined;
-  const chatId = escalationIn?.["telegramChatId"];
-  const escalation: ProjectConfig["escalation"] = {
-    // Absent means "yes, still tell me": a silently stuck run is the worst case.
-    fallbackToIssueComment: escalationIn?.["fallbackToIssueComment"] !== false,
-  };
-  if (nonEmptyString(chatId)) escalation.telegramChatId = chatId;
+  const escalation = normalizeEscalation(raw["escalation"], label, problems);
+  const authority = normalizeAuthority(raw["authority"], label, problems);
 
   const caps = coerceCaps(raw["caps"], `${label}: caps`, problems, legacyCaps);
   const reporting = normalizeReporting(raw["reporting"], label, problems);
@@ -298,6 +298,7 @@ function normalizeProject(
     caps,
     ...(workerModel === undefined ? {} : { workerModel }),
     escalation,
+    authority,
     reporting,
     workspaceRoot: expandHome(pickString(raw["workspaceRoot"], join(stateDir(), "worktrees"))),
     mirrorRoot: expandHome(pickString(raw["mirrorRoot"], join(stateDir(), "mirrors"))),
@@ -326,14 +327,92 @@ function normalizeReporting(parsed: unknown, label: string, problems: string[]):
     problems.push(`${label}: reporting has unknown key(s): ${unknownKeys.join(", ")}`);
   }
 
-  const declared = raw["scope"];
-  if (declared === undefined) return { scope: DEFAULT_REPORT_SCOPE };
-  const scope = REPORT_SCOPES.find((s) => s === declared);
-  if (scope === undefined) {
-    problems.push(`${label}: reporting.scope must be ${REPORT_SCOPE_LIST}, found ${JSON.stringify(declared)}`);
-    return { scope: DEFAULT_REPORT_SCOPE };
+  return {
+    scope: pickLiteral(
+      raw["scope"],
+      REPORT_SCOPES,
+      DEFAULT_REPORT_SCOPE,
+      `${label}: reporting.scope`,
+      REPORT_SCOPE_LIST,
+      problems,
+    ),
+  };
+}
+
+/**
+ * Who triages escalations, and how they are delivered when nobody answers.
+ *
+ * `orchestrator` is validated rather than folded to the default for the reason
+ * `reporting.scope` is: a misspelt `"externl"` that quietly resolved to
+ * `"embedded"` would start a second brain beside the operator's own session,
+ * and both of them would triage the same issue from different transcripts.
+ */
+function normalizeEscalation(parsed: unknown, label: string, problems: string[]): ProjectConfig["escalation"] {
+  let raw: Raw = {};
+  if (parsed !== undefined) {
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) raw = parsed as Raw;
+    else problems.push(`${label}: escalation must be an object`);
+  }
+
+  const escalation: ProjectConfig["escalation"] = {
+    // Absent means "yes, still tell me": a silently stuck run is the worst case.
+    fallbackToIssueComment: raw["fallbackToIssueComment"] !== false,
+    orchestrator: pickLiteral(
+      raw["orchestrator"],
+      ORCHESTRATOR_MODES,
+      "embedded",
+      `${label}: escalation.orchestrator`,
+      ORCHESTRATOR_MODE_LIST,
+      problems,
+    ),
+  };
+  const chatId = raw["telegramChatId"];
+  if (nonEmptyString(chatId)) escalation.telegramChatId = chatId;
+  return escalation;
+}
+
+/**
+ * Who lands PRs and who cuts releases. Both default to the human: this is the
+ * one config value that decides whether an unattended session may write to a
+ * main branch, so it is granted explicitly or not at all.
+ *
+ * Unknown keys are rejected outright, as in `reporting` and for the same
+ * reason: the object has exactly two members, so an unrecognised one is a typo
+ * every time — and a `authority: { merges: "orchestrator" }` that loaded
+ * cleanly would read as delegated while the orchestrator was still told to keep
+ * its hands off.
+ */
+function normalizeAuthority(parsed: unknown, label: string, problems: string[]): ProjectConfig["authority"] {
+  if (parsed === undefined) return { ...DEFAULT_AUTHORITY };
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${label}: authority must be an object with "merge" and "release" of ${AUTHORITY_HOLDER_LIST}`);
+    return { ...DEFAULT_AUTHORITY };
   }
-  return { scope };
+  const raw = parsed as Raw;
+
+  const unknownKeys = Object.keys(raw).filter((k) => k !== "merge" && k !== "release");
+  if (unknownKeys.length > 0) {
+    problems.push(`${label}: authority has unknown key(s): ${unknownKeys.join(", ")}`);
+  }
+
+  return {
+    merge: pickLiteral(
+      raw["merge"],
+      AUTHORITY_HOLDERS,
+      DEFAULT_AUTHORITY.merge,
+      `${label}: authority.merge`,
+      AUTHORITY_HOLDER_LIST,
+      problems,
+    ),
+    release: pickLiteral(
+      raw["release"],
+      AUTHORITY_HOLDERS,
+      DEFAULT_AUTHORITY.release,
+      `${label}: authority.release`,
+      AUTHORITY_HOLDER_LIST,
+      problems,
+    ),
+  };
 }
 
 function normalizeRepos(parsed: unknown, label: string, problems: string[]): Record<string, RepoTarget> {
@@ -439,6 +518,38 @@ function pickString(v: unknown, fallback: string): string {
   return nonEmptyString(v) ? v : fallback;
 }
 
+/** Quoted alternatives for an error message, from the same data the guard reads. */
+function quoteList(values: readonly string[]): string {
+  return values.map((v) => `"${v}"`).join(" or ");
+}
+
+/**
+ * One rule for "a declared literal out of a closed set, else the documented
+ * default", used by every such field here.
+ *
+ * Absent takes the default silently; a value outside the set is always
+ * reported and never folded. Each of these sets decides something the operator
+ * would otherwise believe they had configured — who merges, who triages, how
+ * loud the fleet is — and a typo that resolves to the default reads exactly
+ * like a deliberate choice in the file afterwards.
+ */
+function pickLiteral<T extends string>(
+  v: unknown,
+  allowed: readonly T[],
+  fallback: T,
+  field: string,
+  quoted: string,
+  problems: string[],
+): T {
+  if (v === undefined) return fallback;
+  const hit = allowed.find((a) => a === v);
+  if (hit === undefined) {
+    problems.push(`${field} must be ${quoted}, found ${JSON.stringify(v)}`);
+    return fallback;
+  }
+  return hit;
+}
+
 /** `~/x` in a hand-written config must not create a literal `~` directory. */
 function expandHome(p: string): string {
   if (p === "~") return homedir();