omp-conductor 0.19.5 → 0.19.7

package/REFERENCE.md

@@ -848,6 +848,22 @@ the queue label is refused with `file-lane-unparseable` and an actionable
 message, because promoting beside overlapping work on a section that plainly
 tried to declare is the exact gap the interlock exists to close.
 
+Since #1036, a promotion also checks a contract. When the issue carries a
+durable `promotable` grooming verdict (the store's grooming row, written by
+the to-spec batch), adding the queue label first recovers that verdict's strict
+payload and requires its `PROMOTABLE` result, then compares the lane admission
+would enforce against the verdict's `fileLane` as deduplicated,
+order-independent path sets — exact in both directions, so a missing path
+refuses exactly like an extra one, and an order-only difference promotes. Any
+disagreement refuses with `promotion-brief-mismatch`, naming both sets; so
+does evidence behind a `promotable` row that does not recover as a strict
+PROMOTABLE result, and an issue unreadable at promotion time behind such a
+row. The durable verdict is what made the issue dispatchable, so the gate
+fails closed before any tracker mutation or daemon wake — but it never edits
+the issue itself: the remediation is applying the verdict's `proposedBrief`
+to the issue (its `## Exact write lane` included), then adding the label
+again. An issue without a `promotable` row promotes exactly as before.
+
 #### What status shows
 
 `status` renders the two lifecycle kinds as two blocks, because "a branch is
@@ -3099,7 +3115,7 @@ daemon, across a process boundary, not in a prompt the model can rewrite.
 | `conductor_pr_status` | worker or orchestrator | Read-only — nothing to gate. A worker reads only its own run's PR; an orchestrator may name any syntactically valid PR URL, open, merged, or closed, and gets its live state and head (checks are reported when available; a merged or closed PR reports its state instead of an `expected OPEN` refusal). |
 | `conductor_pr_update_branch` | orchestrator, or the worker owning the run | The PR belongs to this project and is open. A worker may only name its own run's PR. |
 | `conductor_pr_merge` | **orchestrator only** | Ordinarily, `authority.merge` equals the caller. A hand-edited `recoveryMerges` entry may instead authorize one exact unrecorded PR/head/reason while held. In both paths, while the project has an [active release composition](#the-active-release-composition-850), the PR must be named in it or carry an explicit operator override; then `headSha` equals the live head *at execution time*; checks are green at that same SHA; no [review evidence](#the-exact-head-review-gate-888) stands at that head without a recorded `conductor_pr_review_clear`; the project route and migration chain are valid; the project's single merge slot is free. |
-| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. Adding the queue label echoes the parsed [file lane](#the-file-lane-declaration), or refuses with `file-lane-unparseable` when a clearly delimited write-lane section parsed nothing — it never claims fail-open beside a declaration that was actually attempted. |
+| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. Adding the queue label echoes the parsed [file lane](#the-file-lane-declaration), or refuses with `file-lane-unparseable` when a clearly delimited write-lane section parsed nothing — it never claims fail-open beside a declaration that was actually attempted. When the issue carries a durable `promotable` grooming verdict, adding the queue label also verifies the current brief against that verdict before any mutation: a brief that disagrees with the verdict's `fileLane` (or evidence that no longer recovers as a strict PROMOTABLE result) refuses with `promotion-brief-mismatch` — apply the verdict's `proposedBrief`, then re-add ([the file-lane declaration](#the-file-lane-declaration)). |
 | `conductor_release` | **orchestrator only** | `authority.release` equals the caller; the per-shape grant permits it; the artefact or environment was declared; the release preconditions hold; the `reason` is in the closed enum. `version-bump-pr` creates or re-validates one deterministic version-only PR and, on a later call, merges only its exact green head through the project's single merge slot. |
 | `conductor_install` | **orchestrator only** | Gated like a release act: the `install` shape defaults to `human` and a grant is what moves it. The daemon refuses a version npm does not expose with a full `gitHead`, refuses while another install is still in flight, and otherwise starts a detached transient unit that pauses, drains, installs the CLI/omp plugin/Herdr plugin and reloads — outside this session and the daemon. The unit never declares its own success; the first tick after the restart verifies and reports through the durable outbox. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.19.5",
+  "version": "0.19.7",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/cli.ts

@@ -32,6 +32,7 @@ import { reportCommand } from "./commands/report.ts";
 import { releaseCompositionCommand } from "./commands/release-composition.ts";
 import { restartCommand } from "./commands/restart.ts";
 import { restoreDbCommand } from "./commands/restore-db.ts";
+import { snapshotDbCommand } from "./commands/snapshot-db.ts";
 import { resumeCommand } from "./commands/resume.ts";
 import { setupCommand } from "./commands/setup.ts";
 import { startCommand } from "./commands/start.ts";
@@ -300,6 +301,7 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     intake: () => intakeCommand(ctx),
     friction: () => frictionCommand(ctx),
     "restore-db": () => restoreDbCommand(ctx),
+    "snapshot-db": () => snapshotDbCommand(ctx),
     resume: () => resumeCommand(ctx),
     "brief-upgrade": () => briefUpgradeCommand(ctx),
     help: () => helpCommand(USAGE),

package/src/command-help.ts

@@ -6,10 +6,11 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            the project already exists, a chooser of which area to amend. Naming
            an area positionally skips that chooser and amends only that area:
            ${AMEND_AREA_IDS.join(", ")}.
-  upgrade  update the Bun-global CLI, omp plugin, Herdr recovery plugin, and
-           brief as one pinned release. Pauses only new claims, drains live
-           workers, reloads, verifies twice, and restores the prior dispatch
-           state. Run it from a shell outside the target Herdr session.
+  upgrade  discover the installed CLI package root, then update it with the omp
+           plugin, Herdr recovery plugin, and brief as one pinned release.
+           Pauses only new claims, drains live workers, reloads, verifies twice,
+           and restores the prior dispatch state. Run it from a shell outside
+           the target Herdr session.
            --bootstrap SHA --source PATH installs an exact commit instead of a
            published version, for when the installed conductor is what is
            broken: the source must be a checkout AT that sha, the package's own
@@ -66,6 +67,10 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            --probe-telegram sends through the report transport. Exit code 0
            only when nothing failed; --json prints the stable CI shape. Run
            it after install and after every upgrade.
+  snapshot-db
+           publish a transaction-consistent conductor.db snapshot with SQLite
+           VACUUM INTO, record it in the durable event ledger, and apply the
+           daemon cadence's bounded retention. Safe while the daemon writes.
   restore-db
            put conductor.db back to a restorable snapshot, replacing the live
            file and dropping stale -wal/-shm sidecars. Refuses while a daemon
@@ -153,6 +158,9 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            sending now and holding, exactly as for a daemon escalation. An
            identical retry is refused only while the earlier handoff is still
            undelivered, and admitted again once it lands (#453).
+           report withdraw removes only an unsent pending report or unassigned
+           held notice, requires a reason, preserves an audit row, and refuses
+           sending/delivered/failed/already-withdrawn handoffs.
   message  deliver one direct Telegram message to this project's own chat and
            forum topic, resolved from config rather than from whichever chat
            last wrote to the session. This is how a locally injected tick
@@ -180,10 +188,12 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
   watch    set a condition or carry note for the orchestrator itself, with no
            human in the loop — the same no-sleep surface \`decision open
            --resolves-when\` used to serve, given its own verb so it never renders
-           as a question put to the operator. \`--resolves-when\` attaches a
-           condition the daemon checks for you; a met watch wakes the next tick
-           with its note, exactly as a met question does, but it is listed under
-           its own heading and never under "Open operator decisions", and it has
+           as a question put to the operator. The running daemon checks a
+           \`--resolves-when\` condition; an armed or ungated heartbeat wakes the
+           orchestrator tick when one is met. With no daemon the durable row is
+           unmonitored. With ticks disarmed the condition may still be marked met,
+           but no tick can be woken until the heartbeat returns. It is listed
+           under its own heading, never under "Open operator decisions", and has
            no seven-day expiry. \`watch list\` shows open watches; \`watch
            withdraw <id>\` ends one with a recorded reason — the verb that
            creates a watch is the verb that ends it (watches are decision rows,

package/src/command-manifest.ts

@@ -202,6 +202,17 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       toggle("--probe-telegram", "send the self-identified Telegram health probe"),
     ],
   },
+  {
+    name: "snapshot-db",
+    description: "publish a transaction-consistent conductor.db snapshot",
+    scope: "host",
+    usage: ["snapshot-db"],
+    flags: [],
+    details:
+      "Publish one transaction-consistent conductor.db snapshot using SQLite VACUUM INTO, " +
+      "record the action in every configured project's durable event ledger, and apply the " +
+      "daemon cadence's bounded retention. Safe while the daemon is writing.",
+  },
   {
     name: "restore-db",
     description: "restore conductor.db from a safe snapshot",
@@ -403,14 +414,18 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     scope: "project",
     usage: [
       "report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure] [--events IDS] [--notices IDS] [--project NAME]",
+      "report withdraw <id> --reason TEXT [--project NAME]",
     ],
+    subcommands: [{ name: "withdraw", description: "withdraw an unsent report or held notice" }],
     flags: [
       value("--text", "rendered report text"),
       value("--kind", "material, digest, or escalation category"),
       value("--events", "comma-separated event ledger ids"),
       value("--notices", "comma-separated notice ledger ids"),
+      value("--reason", "why a pending handoff is obsolete"),
       project(),
     ],
+    positionals: [{ name: "action" }, { name: "id" }],
   },
   {
     name: "message",
@@ -460,11 +475,13 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       "watch list [--project NAME] [--json]",
       "watch withdraw <id> [--reason TEXT] [--project NAME]",
     ],
-    details: `add records a row the daemon checks for you and the next tick reads, with no
-operator answer needed. list shows open watches, oldest first. withdraw ends
-one with a recorded reason — the verb that creates a watch is the verb that
-ends it. A watch whose PR condition can no longer be observed (the PR merged
-or closed first) is withdrawn by the daemon itself.`,
+    details: `add records a durable row with no operator answer needed. The running daemon
+checks conditions; an armed or ungated heartbeat wakes the orchestrator tick when one is met.
+With no daemon the row is unmonitored. With ticks disarmed the daemon may still mark a
+condition met, but no tick can be woken until the heartbeat returns. list shows open watches,
+oldest first. withdraw ends one with a recorded reason — the verb that creates a watch is the
+verb that ends it. A watch whose PR condition can no longer be observed (the PR merged or
+closed first) is withdrawn by the daemon itself.`,
     subcommands: [
       { name: "add", description: "record a watch" },
       { name: "list", description: "list open watches" },

package/src/commands/context.ts

@@ -104,6 +104,7 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   daemon: "host",
   restart: "host",
   "restore-db": "host",
+  "snapshot-db": "host",
   start: "host",
   upgrade: "host",
   "upgrade-install": "host",

package/src/commands/report.ts

@@ -22,7 +22,70 @@ import {
   type ReportKind,
 } from "../types.ts";
 
+async function withdrawHandoff(ctx: CommandContext): Promise<void> {
+  const id = ctx.argv[2];
+  const reason = ctx.flag("reason")?.trim();
+  if (id === undefined || id.startsWith("--")) {
+    process.stderr.write("omp-conductor: report withdraw needs the report or held-notice id\n");
+    process.exit(2);
+  }
+  if (reason === undefined || reason.length === 0 || reason.startsWith("--")) {
+    process.stderr.write("omp-conductor: report withdraw needs --reason with why the handoff is obsolete\n");
+    process.exit(2);
+  }
+  for (let i = 3; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === "--project" || token === "--reason") {
+      i += 1;
+      continue;
+    }
+    if (token?.startsWith("--project=") || token?.startsWith("--reason=")) continue;
+    process.stderr.write(`omp-conductor: report withdraw: unexpected argument "${token ?? ""}"\n`);
+    process.exit(2);
+  }
+  const sessionRole = process.env[SESSION_ROLE_ENV];
+  if (sessionRole === "worker") {
+    process.stderr.write("omp-conductor: report withdraw is an operator/orchestrator action, not a worker action\n");
+    process.exit(3);
+  }
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const inHerdrPane =
+    process.env["HERDR_ENV"] !== undefined && process.env["HERDR_ENV"] !== "";
+  const actor = sessionRole ?? (inHerdrPane ? "orchestrator" : "operator");
+  const store = openStore(dbPath());
+  try {
+    const result = store.withdrawHandoff(
+      id,
+      project.name,
+      actor,
+      reason,
+      Date.now(),
+    );
+    if (result.kind === "not-found") {
+      process.stderr.write(`omp-conductor: no report or held notice ${id} for ${project.name}\n`);
+      process.exit(1);
+    }
+    if (result.kind === "refused") {
+      process.stderr.write(
+        `omp-conductor: cannot withdraw ${result.target} ${id}: state is ${result.state}; ` +
+          "only an unsent pending report or unassigned held notice may be withdrawn\n",
+      );
+      process.exit(1);
+    }
+    process.stdout.write(
+      `${result.withdrawal.target} ${id} withdrawn for ${project.name} — ${reason}\n`,
+    );
+  } finally {
+    store.close();
+  }
+}
+
+
 export async function reportCommand(ctx: CommandContext): Promise<void> {
+if (ctx.argv[1] === "withdraw") {
+  await withdrawHandoff(ctx);
+  return;
+}
 const rawText = ctx.flag("text");
 const body = rawText?.trim();
 if (body === undefined || body.length === 0 || rawText?.startsWith("--") === true) {

package/src/commands/restore-db.ts

@@ -128,7 +128,7 @@ export async function restoreDbCommand(ctx: CommandContext): Promise<void> {
   const snapshot = requested === undefined ? newestSnapshot(snapDir) : resolve(requested);
   if (snapshot === undefined) {
     throw new Error(
-      `no conductor.db snapshot in ${snapDir} — take one (the snapshot primitive) or pass an explicit snapshot path`,
+      `no conductor.db snapshot in ${snapDir} — run \`omp-conductor snapshot-db\` or pass an explicit snapshot path`,
     );
   }
   if (!existsSync(snapshot)) {

package/src/commands/snapshot-db.ts

@@ -0,0 +1,67 @@
+/** `snapshot-db` — publish one transaction-consistent conductor.db snapshot. */
+
+import type { CommandContext } from "./context.ts";
+import { dbBackupDirFor, loadConfig } from "../config.ts";
+import type { Store } from "../types.ts";
+import {
+  DB_SNAPSHOT_RETENTION,
+  dbPath,
+  openStore,
+  pruneDbSnapshots,
+  snapshotDb,
+} from "../store.ts";
+
+export async function snapshotDbCommand(ctx: CommandContext): Promise<void> {
+  if (ctx.projectFlag !== undefined) {
+    process.stderr.write("omp-conductor: snapshot-db does not take a project — the store is host-wide\n");
+    process.exit(2);
+  }
+  if (ctx.argv.length > 1) {
+    process.stderr.write(`omp-conductor: snapshot-db: unexpected argument "${ctx.argv[1]}"\n`);
+    process.exit(2);
+  }
+
+  const cfg = loadConfig();
+  const directory = dbBackupDirFor(cfg);
+  const published = snapshotDb(dbPath(), directory);
+  // Publication is already durable. Print its path before secondary accounting
+  // so a ledger/prune failure cannot turn success into an invisible file.
+  process.stdout.write(`snapshot published: ${published}\n`);
+
+  let store: Store | undefined;
+  try {
+    const opened = openStore(dbPath());
+    store = opened;
+    const now = Date.now();
+    const eventIds = cfg.projects.map((project) =>
+      opened.recordMaterialEvent({
+        project: project.name,
+        category: "db-snapshot",
+        summary: "published manual conductor.db snapshot",
+        evidence: published,
+        occurredAt: now,
+        recordedAt: now,
+      }).id,
+    );
+    process.stdout.write(`ledger events recorded: ${eventIds.join(", ")}\n`);
+  } catch (err) {
+    process.stderr.write(
+      `warning: snapshot published, but its ledger event could not be recorded: ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    );
+  } finally {
+    store?.close();
+  }
+
+  try {
+    const pruned = pruneDbSnapshots(directory, DB_SNAPSHOT_RETENTION);
+    process.stdout.write(`retention ${DB_SNAPSHOT_RETENTION} (${pruned} pruned)\n`);
+  } catch (err) {
+    process.stderr.write(
+      `warning: snapshot published, but retention pruning failed: ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    );
+  }
+}

package/src/commands/upgrade-install.ts

@@ -22,7 +22,7 @@ const result = await runDetachedUpgrade({
 });
 process.stdout.write(
   `install complete — awaiting first-tick verification:\n` +
-    `  Bun-global CLI     omp-conductor@${result.version}\n` +
+    `  omp-conductor CLI omp-conductor@${result.version}\n` +
     `  omp plugin         omp-conductor@${result.version}\n` +
     `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
     `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +

package/src/commands/upgrade.ts

@@ -1,5 +1,5 @@
 /**
- * `upgrade` — update the Bun-global CLI, omp plugin, Herdr recovery plugin and brief as one pinned release.
+ * `upgrade` — update the discovered CLI package, omp plugin, Herdr recovery plugin and brief as one pinned release.
  *
  * 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
@@ -33,7 +33,7 @@ const result = await upgradeConductor({
 const spec = sha === undefined ? `omp-conductor@${result.version}` : `${result.version} @ ${result.gitHead.slice(0, 12)}`;
 process.stdout.write(
   `${result.alreadyCurrent ? "already current" : sha === undefined ? "upgrade complete" : "bootstrap complete"}:\n` +
-    `  Bun-global CLI     ${spec}\n` +
+    `  omp-conductor CLI ${spec}\n` +
     `  omp plugin         ${spec}\n` +
     `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
     `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +

package/src/commands/verb.ts

@@ -59,6 +59,7 @@ try {
   const reply = await handleVerbCall(
     {
       project: () => findProject(loadConfig(), project.name),
+      projects: () => loadConfig().projects,
       store,
       tracker: makeTracker(project),
       actions: githubVerbActions(project),

package/src/commands/watch.ts

@@ -21,6 +21,7 @@
 import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
+import { watchMonitoringForProject } from "../fleet.ts";
 import { shellQuote } from "../shell.ts";
 import { dbPath, openStore } from "../store.ts";
 
@@ -94,7 +95,12 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
         ...(condition === undefined ? {} : { condition }),
         at: Date.now(),
       });
-      const wake = condition === undefined ? "read by the next tick" : "the daemon wakes the next tick when it is met";
+      const monitoring = watchMonitoringForProject(project.name);
+      const wake = monitoring.monitored
+        ? condition === undefined
+          ? "read by the next tick"
+          : "the daemon checks it and wakes the next available tick when it is met"
+        : `durable but currently unmonitored (${monitoring.reason}); it becomes wake-capable automatically when the daemon and heartbeat are active`;
       // The verb that ends the row names the project it was created in: this
       // command is copied, and on a host with several projects the bare form is
       // ambiguous (#810).
@@ -107,6 +113,7 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
     if (sub === "list" || sub === undefined) {
       assertKnownWatchArgs(ctx, "list", 2);
       const open = store.openDecisions(project.name).filter((d) => d.kind === "watch");
+      const monitoring = watchMonitoringForProject(project.name);
       const now = Date.now();
       const watches = open.map((d) => ({
         id: d.id,
@@ -116,13 +123,18 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
         note: d.question,
       }));
       if (ctx.argv.includes("--json")) {
-        process.stdout.write(`${JSON.stringify({ project: project.name, watches }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ project: project.name, monitoring, watches }, null, 2)}\n`);
         return;
       }
       if (watches.length === 0) {
         process.stdout.write("no watches\n");
         return;
       }
+      process.stdout.write(
+        monitoring.monitored
+          ? "watch monitoring: active\n"
+          : `watch monitoring: durable, unmonitored (${monitoring.reason})\n`,
+      );
       for (const watch of watches) {
         process.stdout.write(
           `${watch.id}  ${watch.ageHours}h  blocks:${watch.blocks ?? "-"}  ` +

package/src/config.ts

@@ -320,6 +320,23 @@ export function resolveReleaseGrants(p: ProjectConfig): ResolvedGrants {
   return grants;
 }
 
+/** The one install holder shared by every project on this host, or the
+ * per-project evidence explaining why no shared holder exists (#1018). */
+export function resolveSharedInstallAuthority(projects: readonly ProjectConfig[]): {
+  holder?: ResolvedGrants["install"];
+  entries: readonly { project: string; holder: ResolvedGrants["install"] }[];
+} {
+  const entries = projects.map((project) => ({
+    project: project.name,
+    holder: resolveReleaseGrants(project).install,
+  }));
+  const holders = new Set(entries.map((entry) => entry.holder));
+  return {
+    ...(holders.size === 1 ? { holder: entries[0]!.holder } : {}),
+    entries,
+  };
+}
+
 /**
  * The gating conditions for one project, complete (#129).
  *