omp-conductor 0.4.2 → 0.4.4

package/src/briefs/orchestrator.md

@@ -267,6 +267,15 @@ Not yours to relax:
   redo the merge costs a whole attempt to buy what one call does in minutes — do
   not. Bypassing branch protection with admin rights is still forbidden;
   updating the branch is how you satisfy it, not how you dodge it.
+  When `conductor_pr_update_branch` cannot resolve it — a real conflict, or a
+  generated file a server-side merge cannot recompute — and the run has settled
+  so no worker is coming, repairing the branch from a **fresh clone** is yours
+  and is expected: clone outside every worktree, merge the base, resolve,
+  regenerate what must be regenerated, verify locally, and push without force.
+  Take the commit identity from the repository's own history; never invent one.
+  The prohibition is the worktree, the force-push and the fabricated identity —
+  not the branch. A settled run means nobody else is coming:
+  waiting is not caution, it is a stall.
 
 ## Your verb surface
 
@@ -297,16 +306,21 @@ to read the refusal instead of retrying in a loop.
 the SHA that produced it. Never work around one: there is no path around it, and
 the attempt is in the ledger.
 
-**Two of the boundaries above are mechanical, not only prose.** Your structured
-file tools (`read`, `write`, `edit`, `grep`, `glob`) run against an allowlist:
-the state directory, this brief, `POLICY.md`, the heartbeat's own files, and any
-path your operator added as `orchestratorReadPaths`. Every worker checkout, the
-mirror cache and the installed `omp-conductor` package are refused — reading
-included, and no config entry can re-open them. A refusal names the path and
-the roots that are allowed: read it and pick a different path rather than
-trying variations. When you genuinely need to see a run's code, read its PR.
-`bash` is not gated, and that is not an invitation — the boundary is the same
-one, and going around it is the one thing a fleet cannot audit.
+**Your file tools are not gated — the workers' are.** Every worker session runs
+under a mechanical worktree gate and, under `credentials.isolation: "per-run"`,
+its own OS principal. Your structured tools are gated by nothing, and that is a
+deliberate operator decision rather than an oversight. What holds YOUR
+boundaries is this brief, the verb ledger every `conductor_*` call writes, and
+the operator reading both. Never read or edit a worker's checkout or the mirror
+cache — when you need a run's code, read its PR. Unconfined means auditable, not
+licensed.
+
+One caveat, so you never assume more protection than you have: if this daemon
+started you *and* the fleet runs an isolating credentials mechanism, you are
+also a separate OS principal that genuinely cannot reach a run checkout, the
+mirror or the host credential — `omp-conductor status` names that mechanism on
+its `boundary` line. Started by your operator, or on a host that reports
+`unprotected`, nothing stops those reads but the paragraph above.
 
 **Your own** merge and release authority is not decided here, and not by this
 brief either. It is whatever your operator granted at setup time, and the
@@ -367,9 +381,7 @@ The protocol, in order:
    `telegram_ask` is a delivery failure, not an operator answer. Re-deliver the
    question with `telegram_send`, or report the channel as broken. Never infer
    rejection or “not now” from failed delivery. On an explicit “not now”, park
-   it: mention it once in the next report as
-   `pending amendment: <one-liner> — say 'apply it' or 'drop it'`, never re-open
-   the yes/no dialog, and drop it if still unanswered after 7 days.
+   it in the ledger rather than in your head — see below.
 4. **Log it.** Append one line to **Amendments** at the bottom of `POLICY.md`:
    the date, what triggered it, a one-sentence summary.
 5. **Offer general fixes upstream.** Ask one question of the amendment you just
@@ -381,6 +393,32 @@ The protocol, in order:
    diff and the incident that triggered it. File it only when your operator says
    yes — it is their name on the account.
 
+**Every question you put to your operator is recorded, not remembered.** The
+moment you send one — an amendment, a tier-2 decision, anything you are waiting
+on an answer for — write it down:
+
+```
+omp-conductor decision open --question "<the question as you sent it>" \
+  [--blocks "<what is waiting on it>"] [--resolves-when <condition>]
+omp-conductor decision resolve <id> --answer "<what they decided>"
+omp-conductor decision withdraw <id> --reason "<why it stopped mattering>"
+```
+
+Use `--resolves-when` whenever the answer only becomes actionable once something
+observable happens: `pr-merged:<url>`, `issue-closed:<n>`,
+`npm-version:<pkg>@<version>`. The daemon checks it for you and flags the row as
+`[CONDITION MET — act on this now]` in your tick digest, so a parked question
+wakes up on its own instead of waiting for you to think of it.
+
+**Trust the digest, never your recollection.** Every tick's prompt lists what is
+still open. A question that exists only in your context is gone at the next
+compaction, and you will either ask it twice or drop it silently — both of which
+look, to your operator, like a fleet that does not follow up. Resolve or withdraw
+each row explicitly; expiry is enforced for you at seven days, so an unanswered
+question closes itself rather than accumulating. Re-mention a parked item once in
+your next report as `pending amendment: <one-liner> — say 'apply it' or 'drop
+it'`, and never re-open the yes/no dialog.
+
 Two limits. You never propose relaxing **Hard boundaries** — that section changes
 only in the shipped package floor, never via this loop. And at most one proposal
 per tick: an amendment waits for the three duties to finish, it never interrupts

package/src/briefs/policy.md

@@ -59,12 +59,16 @@ and spot issues that would collide. Ask an omp session to read
 
 ## Reporting
 
-Your report scope is **`{{REPORT_SCOPE}}`**. Both scopes, spelled out:
+Your report scope is **`{{REPORT_SCOPE}}`**. All three scopes, spelled out:
 
 - **`escalations`** — you speak when a human is needed, and once a day otherwise.
   That is: every tier-2 escalation immediately, carrying the issue link and the
   single question; plus one daily digest naming what merged, what is green and
   waiting on a merge, and what is stuck and why. Every other tick is silent.
+- **`decisions`** — tier-2 escalations immediately, and a fleet-stopping
+  condition immediately; every other material event is held and delivered as one
+  message with the next tick report. A merge at 10:04 and a green PR at 10:09
+  arrive together at the 10:15 tick, not as two pings.
 - **`material`** — everything in `escalations`, plus each material event as it
   happens: a run reaching a green PR (with the link), a run that failed twice, an
   issue you pulled off the queue, a cap that stopped the fleet. A tick where
@@ -102,7 +106,7 @@ leaves no record that anything went out. And a `cancelled` or errored
 `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
+No scope licenses narration. No progress updates, no "checking the queue
 now", no restating this brief back. Evidence, or silence.
 
 ## Amendments

package/src/cli.ts

@@ -11,18 +11,18 @@ import { dirname, join } from "node:path";
 import { runBoard } from "./board.ts";
 import {
   applyRetrofit,
-  checkBrief,
-  formatBriefStatus,
+  formatBriefReport,
   formatMigrateResult,
   formatRetrofitProposal,
   formatRetrofitRefusal,
   inspectBriefLayout,
   migrateToPolicy,
+  missingSections,
   proposeRetrofit,
   repairPolicyBannerCrumbs,
-  writeMergedBrief,
 } from "./brief-upgrade.ts";
 import { findProject, loadConfig, resolveCaps, sharedRoot, stateDir } from "./config.ts";
+import { CONDITION_FORMS, parseCondition } from "./decisions.ts";
 import { boundarySetupScript } from "./credentials.ts";
 import { runDaemon, setPaused } from "./daemon.ts";
 import {
@@ -105,9 +105,14 @@ usage:
   omp-conductor pause
   omp-conductor resume
   omp-conductor graph-setup [--project NAME] [--write]
+  omp-conductor boundary-setup [--slots N] [--daemon-user USER] [--shared-root PATH]
   omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
   omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
   omp-conductor report --text TEXT [--kind material|digest] [--project NAME]
+  omp-conductor decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
+  omp-conductor decision resolve <id> --answer TEXT [--project NAME]
+  omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
+  omp-conductor decision list [--project NAME]
   omp-conductor help
 
   upgrade  update the Bun-global CLI, omp plugin, Herdr recovery plugin, and
@@ -171,6 +176,17 @@ usage:
            at-least-once: a crash mid-send is retried and the retry says it may
            be a repeat. --kind digest is accepted at most once per local day,
            decided from the ledger rather than from what you remember sending.
+  decision record, list and close the questions you have put to your operator.
+           A question that lives only in a session's context is lost to the next
+           compaction, so \`decision open\` writes it down and every tick's prompt
+           carries what is still owed. \`--resolves-when\` attaches a condition the
+           daemon checks for you (pr-merged:<url>, issue-closed:<n>,
+           npm-version:<pkg>@<version>); a met one is flagged in that digest.
+           Unanswered rows expire after seven days rather than accumulating.
+             decision open --question TEXT [--blocks TEXT] [--resolves-when COND]
+             decision resolve <id> --answer TEXT
+             decision withdraw <id> [--reason TEXT]
+             decision list
   friction record a bounded observation the daemon cannot classify itself:
            an escalation that belonged in a digest, or a tick report that was
            noise/surprising. Repeated observations feed the existing Learning
@@ -186,14 +202,23 @@ usage:
            current. --write writes the two units and the script they run, and
            prints the systemctl line to run — it never runs systemctl itself.
            Exits 1 when no repo in the project has graphProject configured.
+  boundary-setup
+           print the root commands that provision the credential boundary
+           (#125): the per-run slot accounts, the conductor-daemon and
+           conductor-runs groups, the 0711 shared root, and the daemon home's
+           mode. Prints; never runs them — it creates system accounts, so it is
+           your sudo and your chance to read it first. Needs no config, and
+           must run BEFORE setup, which writes worktree and mirror paths into
+           the root this creates. --slots defaults to maxConcurrentWorkers.
   brief-upgrade
            inspect the brief overlay (package floor + POLICY.md). Reports by
            default. --migrate lifts a bannered ORCHESTRATOR.md owned half into
            POLICY.md and recomposes. --retrofit proposes inserting the YOURS TO
            EDIT banner before the first Releases/Project context/Reporting/
-           Amendments heading (#20); --retrofit --apply writes it. Legacy
-           --apply still merges a bannered single-file brief. --file checks a
-           brief that is not where the wizard would have put it.
+           Amendments heading (#20); --retrofit --apply writes it. --apply only
+           ever confirms one of those two — the legacy single-file merge was
+           removed in 0.4.3. --file checks a brief that is not where the wizard
+           would have put it.
   help     print this text (also --help, -h).
   --version
            print the installed omp-conductor package version (also -V, version).
@@ -804,6 +829,98 @@ try {
       break;
     }
 
+    case "decision": {
+      const sub = argv[1];
+      const project = findProject(loadConfig(), flag(argv, "project"));
+      const store = openStore(dbPath());
+      try {
+        if (sub === "open") {
+          const question = flag(argv, "question")?.trim();
+          if (question === undefined || question.length === 0 || question.startsWith("--")) {
+            process.stderr.write(
+              "omp-conductor: decision open needs --question with the question you sent\n",
+            );
+            process.exit(2);
+          }
+          const condition = flag(argv, "resolves-when")?.trim();
+          if (condition !== undefined && parseCondition(condition) === undefined) {
+            process.stderr.write(
+              `omp-conductor: --resolves-when must be one of:\n${CONDITION_FORMS.map((f) => `  ${f}`).join("\n")}\n`,
+            );
+            process.exit(2);
+          }
+          const blocks = flag(argv, "blocks")?.trim();
+          const decision = store.createDecision({
+            project: project.name,
+            question,
+            ...(blocks === undefined || blocks.length === 0 ? {} : { blocks }),
+            ...(condition === undefined ? {} : { condition }),
+            at: Date.now(),
+          });
+          process.stdout.write(
+            `decision ${decision.id} recorded — resolve with: omp-conductor decision resolve ${decision.id} --answer "..."\n`,
+          );
+          break;
+        }
+
+        if (sub === "resolve" || sub === "withdraw") {
+          const id = argv[2];
+          if (id === undefined || id.startsWith("--")) {
+            process.stderr.write(`omp-conductor: decision ${sub} needs the decision id\n`);
+            process.exit(2);
+          }
+          const answered = sub === "resolve";
+          const text = answered ? flag(argv, "answer")?.trim() : flag(argv, "reason")?.trim();
+          if (answered && (text === undefined || text.length === 0)) {
+            process.stderr.write("omp-conductor: decision resolve needs --answer with what was decided\n");
+            process.exit(2);
+          }
+          const ok = store.resolveDecision(
+            id,
+            answered ? "answered" : "withdrawn",
+            text === undefined || text.length === 0 ? "withdrawn" : text,
+            Date.now(),
+          );
+          if (!ok) {
+            // A decision that is not open is a different mistake from an id that
+            // never existed, and the operator can only act on one of them.
+            process.stderr.write(
+              `omp-conductor: no open decision ${id} for ${project.name} — it was answered, withdrawn or expired, or the id is wrong\n`,
+            );
+            process.exit(1);
+          }
+          process.stdout.write(`decision ${id} ${answered ? "answered" : "withdrawn"}\n`);
+          break;
+        }
+
+        if (sub === "list" || sub === undefined) {
+          const open = store.openDecisions(project.name);
+          if (open.length === 0) {
+            process.stdout.write("no open decisions\n");
+            break;
+          }
+          const now = Date.now();
+          for (const d of open) {
+            const condition =
+              d.condition === undefined ? "-" : d.conditionMetAt === undefined ? "pending" : "met";
+            const hours = Math.max(0, Math.round((now - d.askedAt) / 3_600_000));
+            process.stdout.write(
+              `${d.id}  ${hours}h  blocks:${d.blocks ?? "-"}  condition:${condition}  ${d.question}\n`,
+            );
+          }
+          break;
+        }
+
+        process.stderr.write(
+          `omp-conductor: unknown decision subcommand "${sub}" — expected open, resolve, withdraw or list\n`,
+        );
+        process.exit(2);
+      } finally {
+        store.close();
+      }
+      break;
+    }
+
     case "friction": {
       const name = argv[1] as FrictionFeedbackName | undefined;
       if (name === undefined || !Object.hasOwn(FRICTION_FEEDBACK_KINDS, name)) {
@@ -962,7 +1079,7 @@ try {
         if (layout.kind === "overlay") {
           if (!argv.includes("--apply")) {
             process.stdout.write(
-              `${formatBriefStatus(path, layout)}\n\n` +
+              `${formatBriefReport(path, layout, [])}\n\n` +
                 "POLICY.md already present. --migrate --apply will strip any leading\n" +
                 "banner-comment crumbs from POLICY.md and recompose ORCHESTRATOR.md.\n",
             );
@@ -981,7 +1098,7 @@ try {
           });
           if (repaired === undefined) {
             process.stdout.write(
-              `${formatBriefStatus(path, layout)}\n\nrecomposed ORCHESTRATOR.md — POLICY.md needed no crumb strip.\n`,
+              `${formatBriefReport(path, layout, [])}\n\nrecomposed ORCHESTRATOR.md — POLICY.md needed no crumb strip.\n`,
             );
           } else {
             process.stdout.write(`${formatMigrateResult(repaired)}\n`);
@@ -993,9 +1110,7 @@ try {
           process.exit(1);
         }
         if (layout.kind === "legacy-handwritten") {
-          process.stdout.write(
-            `${formatBriefStatus(path, { kind: "unsplittable", missing: layout.missing })}\n`,
-          );
+          process.stdout.write(`${formatBriefReport(path, layout, layout.missing)}\n`);
           process.exit(1);
         }
         if (project === undefined && /\{\{[A-Za-z0-9_]+\}\}/.test(floor)) {
@@ -1028,36 +1143,38 @@ try {
         break;
       }
 
-      let live: string;
-      try {
-        live = readFileSync(path, "utf8");
-      } catch {
+      // No `--migrate` / `--retrofit`: report the layout and what to run. The
+      // legacy single-file merge that used to live here is gone (#131) — a bare
+      // `--apply` now says so rather than silently doing nothing.
+      if (argv.includes("--apply")) {
         process.stderr.write(
-          `omp-conductor: no brief at ${path}` +
-            `${override === undefined ? " — run /conductor setup and say yes to writing ORCHESTRATOR.md." : "."}\n`,
+          "brief-upgrade: the legacy single-file merge was removed in 0.4.3 — use --migrate --apply (bannered) or --retrofit --apply (hand-written)\n",
         );
-        process.exit(1);
+        process.exit(2);
       }
 
-      if (layout.kind === "overlay") {
-        process.stdout.write(
-          `${formatBriefStatus(path, { kind: "overlay", policyPath: layout.policyPath, orchestratorPath: layout.orchestratorPath })}\n`,
-        );
-        break;
+      let missing: string[] = [];
+      if (layout.kind !== "overlay" && layout.kind !== "missing") {
+        let live: string;
+        try {
+          live = readFileSync(path, "utf8");
+        } catch {
+          process.stderr.write(
+            `omp-conductor: no brief at ${path}` +
+              `${override === undefined ? " — run /conductor setup and say yes to writing ORCHESTRATOR.md." : "."}\n`,
+          );
+          process.exit(1);
+        }
+        missing = missingSections(live, rendered);
       }
 
-      const status = checkBrief(live, rendered);
-      process.stdout.write(`${formatBriefStatus(path, status)}\n`);
-      if (project === undefined) {
+      process.stdout.write(`${formatBriefReport(path, layout, missing)}\n`);
+      if (layout.kind !== "overlay" && project === undefined) {
         process.stdout.write(
           "\nnote: no conductor config resolved on this host, so the template's\n" +
             "{{PLACEHOLDER}} coordinates are unsubstituted. Section names are unaffected.\n",
         );
       }
-      if (argv.includes("--apply") && status.kind === "mergeable") {
-        const backup = writeMergedBrief(path, status.merged);
-        process.stdout.write(`\napplied — previous brief kept at ${backup}\n`);
-      }
       break;
     }
 

package/src/config.ts

@@ -231,6 +231,19 @@ export function saveConfig(c: ConductorConfig): void {
  * rewrote a live fleet's config into a dialect the previous release rejected.
  */
 export function writeConfigFile(c: unknown): void {
+  writeConfigRaw(`${JSON.stringify(c, null, 2)}\n`);
+}
+
+/**
+ * Atomic write of exact bytes.
+ *
+ * The rollback path needs this rather than {@link writeConfigFile}: it captured
+ * a snapshot as text, and putting it back through `JSON.parse` and
+ * `JSON.stringify` returns canonically formatted output, not the operator's
+ * file. Keys and values would survive; their formatting would not — and a
+ * rollback that reformats the thing it is restoring is not a restore.
+ */
+export function writeConfigRaw(text: string): void {
   const dir = stateDir();
   const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
   // mkdir's mode is masked by umask; chmod only what we just created so an
@@ -240,7 +253,7 @@ export function writeConfigFile(c: unknown): void {
   const target = configPath();
   const tmp = join(dir, `.config.json.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`);
   try {
-    writeFileSync(tmp, `${JSON.stringify(c, null, 2)}\n`, { mode: 0o600 });
+    writeFileSync(tmp, text, { mode: 0o600 });
     renameSync(tmp, target);
   } catch (err) {
     rmSync(tmp, { force: true });
@@ -478,11 +491,6 @@ function normalizeProject(
   // (logged by `runWorker`) is what tells the operator the pattern missed.
   const rawWorkerModel = raw["workerModel"];
   const workerModel = nonEmptyString(rawWorkerModel) ? rawWorkerModel : undefined;
-  const orchestratorReadPaths = normalizeOrchestratorReadPaths(
-    raw["orchestratorReadPaths"],
-    label,
-    problems,
-  );
 
   if (problems.length > before) return undefined;
 
@@ -504,7 +512,6 @@ function normalizeProject(
     policy,
     credentials,
     reporting,
-    ...(orchestratorReadPaths === undefined ? {} : { orchestratorReadPaths }),
     // Derived from this project's own isolation, not from `stateDir()`: a
     // hand-written `per-run` config that omits these optional keys would
     // otherwise resolve under the 0700 private tree and be refused at dispatch,
@@ -814,8 +821,7 @@ function normalizeReleaseRequirements(
  * Open-ended by necessity — this package cannot know what a fleet publishes —
  * but a malformed entry still rejects the whole config rather than being
  * dropped. A silently dropped environment name is an operator debugging a
- * refusal that reads exactly like a correctly-denied one, which is the same
- * trap `orchestratorReadPaths` documents.
+ * refusal that reads exactly like a correctly-denied one.
  */
 function normalizeNameList(parsed: unknown, at: string, problems: string[]): string[] {
   if (parsed === undefined) return [];
@@ -1074,51 +1080,16 @@ function normalizeGraphProject(parsed: unknown, label: string, problems: string[
 }
 
 /**
- * Extra roots the orchestrator's tool gate will let it read (#127).
+ * `orchestratorReadPaths` was the allowlist extension for the orchestrator's
+ * file gate (#127). The gate is gone — the orchestrator is unconfined by
+ * operator ruling (#143) — and with it every reader of this key.
  *
- * Fail-closed for the same reason `graphProject` is: the value is written by a
- * human here and *enforced* in another process, by a session whose cwd is the
- * state directory. A relative `../notes` would name a different directory for
- * every reader, so it is an error rather than something resolved against
- * whichever cwd happened to load the file — and a jail entry that resolves
- * somewhere unintended is worse than no entry at all.
- *
- * A malformed entry rejects the whole config rather than being dropped: an
- * operator who mistyped a path they believed they had granted would otherwise
- * debug a refusal that reads exactly like a correctly-denied one.
+ * It is deliberately *not* validated, and not rejected either: project-level
+ * keys this build does not know are ignored, so a live fleet whose config still
+ * carries it keeps loading. A retired key that failed validation would brick
+ * exactly the fleets that adopted it, which is the 0.4.1→0.4.2 outage repeated
+ * on purpose.
  */
-function normalizeOrchestratorReadPaths(
-  parsed: unknown,
-  label: string,
-  problems: string[],
-): string[] | undefined {
-  if (parsed === undefined) return undefined;
-  if (!Array.isArray(parsed)) {
-    problems.push(`${label}.orchestratorReadPaths must be an array of absolute paths`);
-    return undefined;
-  }
-
-  const paths: string[] = [];
-  parsed.forEach((entry: unknown, i) => {
-    if (!nonEmptyString(entry)) {
-      problems.push(
-        `${label}.orchestratorReadPaths[${i}] must be a non-empty absolute path, found ${JSON.stringify(entry)}`,
-      );
-      return;
-    }
-    const path = expandHome(entry.trim());
-    if (!isAbsolute(path)) {
-      problems.push(
-        `${label}.orchestratorReadPaths[${i}] must be an absolute path (or start with "~") — the ` +
-          `orchestrator session's cwd is the state directory, not wherever this file was edited — ` +
-          `found ${JSON.stringify(entry)}`,
-      );
-      return;
-    }
-    paths.push(path);
-  });
-  return paths.length === 0 ? undefined : paths;
-}
 
 /**
  * Gates are the pre-push CI equivalent, so a malformed entry is an error, not