omp-conductor 0.12.0 → 0.14.0

package/src/availability.ts

@@ -0,0 +1,165 @@
+/**
+ * Mechanical operator availability in an IANA timezone (#273).
+ *
+ * This module owns the clock decision. Callers supply `now`; neither a model nor
+ * process-local memory decides whether an interruption is allowed. UTC-minute
+ * scanning for the next transition is intentional: evaluating the same local
+ * predicate across real instants handles skipped and repeated DST wall-clock
+ * minutes without inventing an offset conversion of our own.
+ */
+
+import { WEEKDAYS, type InterruptCategory, type ReportingPolicy, type Weekday, type WeeklyAvailability } from "./types.ts";
+
+const MINUTE_MS = 60_000;
+const TRANSITION_HORIZON_MS = 15 * 24 * 60 * MINUTE_MS;
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+interface CachedTransition {
+  from: number;
+  until: number;
+  open: boolean;
+  nextTransitionAt?: number;
+}
+
+const transitions = new WeakMap<WeeklyAvailability, CachedTransition>();
+
+
+function formatter(timezone: string): Intl.DateTimeFormat {
+  const existing = formatters.get(timezone);
+  if (existing !== undefined) return existing;
+  const created = new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    weekday: "short",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  });
+  formatters.set(timezone, created);
+  return created;
+}
+
+interface LocalMinute {
+  day: Weekday;
+  date: string;
+  clock: string;
+}
+
+function localMinute(at: number, timezone: string): LocalMinute {
+  const parts = formatter(timezone).formatToParts(new Date(at));
+  const get = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((part) => part.type === type)?.value ?? "";
+  return {
+    day: get("weekday").slice(0, 3).toLowerCase() as Weekday,
+    date: `${get("year")}-${get("month")}-${get("day")}`,
+    clock: `${get("hour")}:${get("minute")}`,
+  };
+}
+
+function previousDay(day: Weekday): Weekday {
+  const index = WEEKDAYS.indexOf(day);
+  return WEEKDAYS[(index + WEEKDAYS.length - 1) % WEEKDAYS.length]!;
+}
+
+/** Whether `at` falls inside the configured local weekly window. */
+export function availabilityOpen(window: WeeklyAvailability | undefined, at: number): boolean {
+  if (window === undefined) return true;
+  const local = localMinute(at, window.timezone);
+  if (window.start < window.end) {
+    return window.days.includes(local.day) && local.clock >= window.start && local.clock < window.end;
+  }
+  // Overnight: a selected day opens at `start` and remains open on the next
+  // local day until `end`.
+  return (
+    (window.days.includes(local.day) && local.clock >= window.start) ||
+    (window.days.includes(previousDay(local.day)) && local.clock < window.end)
+  );
+}
+
+export type InterruptDisposition = "interrupt" | "digest" | "availability";
+
+export function availabilityDisposition(
+  window: WeeklyAvailability | undefined,
+  category: InterruptCategory,
+  at: number,
+): Exclude<InterruptDisposition, "digest"> {
+  if (window === undefined || availabilityOpen(window, at) || window.bypass.includes(category)) {
+    return "interrupt";
+  }
+  return "availability";
+}
+
+/**
+ * Decide one tier-2 category. `digest` means the category policy itself defers
+ * it; `availability` means it was otherwise interruptible and may be released
+ * when the configured window next opens.
+ */
+export function interruptDisposition(
+  policy: ReportingPolicy | undefined,
+  category: InterruptCategory,
+  at: number,
+): InterruptDisposition {
+  if (policy !== undefined && !policy.interruptOn.includes(category)) return "digest";
+  return availabilityDisposition(policy?.availability, category, at);
+}
+
+export interface AvailabilityState {
+  mode: "always" | "working" | "quiet";
+  timezone?: string;
+  nextTransitionAt?: number;
+  bypass: InterruptCategory[];
+}
+
+/** Current mode plus the first real instant at which that mode changes. */
+export function availabilityState(policy: ReportingPolicy | undefined, now: number): AvailabilityState {
+  const window = policy?.availability;
+  if (window === undefined) return { mode: "always", bypass: [] };
+
+  const from = Math.floor(now / MINUTE_MS) * MINUTE_MS;
+  let cached = transitions.get(window);
+  if (cached === undefined || from < cached.from || from >= cached.until) {
+    const open = availabilityOpen(window, now);
+    const end = now + TRANSITION_HORIZON_MS;
+    let cursor = from + MINUTE_MS;
+    while (cursor <= end && availabilityOpen(window, cursor) === open) cursor += MINUTE_MS;
+    cached = {
+      from,
+      until: cursor,
+      open,
+      ...(cursor > end ? {} : { nextTransitionAt: cursor }),
+    };
+    transitions.set(window, cached);
+  }
+
+  const { open, nextTransitionAt } = cached;
+  return {
+    mode: open ? "working" : "quiet",
+    timezone: window.timezone,
+    ...(nextTransitionAt === undefined ? {} : { nextTransitionAt }),
+    bypass: [...window.bypass],
+  };
+}
+
+/** Stable operator-facing local timestamp for status and tick prompts. */
+export function formatZonedMinute(at: number, timezone: string): string {
+  const local = localMinute(at, timezone);
+  return `${local.date} ${local.clock} ${timezone} (${new Date(at).toISOString()})`;
+}
+
+/** One prompt sentence; the runtime gate, not this prose, owns the decision. */
+export function availabilityPrompt(policy: ReportingPolicy | undefined, now: number): string {
+  const state = availabilityState(policy, now);
+  if (state.mode === "always") {
+    return "Operator availability (mechanical): 24-hour interrupts; no working-hours window is configured.";
+  }
+  const until =
+    state.nextTransitionAt === undefined || state.timezone === undefined
+      ? "the next configured transition"
+      : formatZonedMinute(state.nextTransitionAt, state.timezone);
+  const bypass = state.bypass.length === 0 ? "none" : state.bypass.join(", ");
+  return state.mode === "working"
+    ? `Operator availability (mechanical): working until ${until}; outside-hours bypass: ${bypass}.`
+    : `Operator availability (mechanical): quiet until ${until}; only these categories bypass quiet hours: ${bypass}.`;
+}

package/src/board.ts

@@ -95,7 +95,7 @@ const LIVE_LANES: Partial<Record<RunState, BoardLane>> = {
  *  that has to stay visible — #173. Differs from {@link LIVE_LANES} in that
  *  these are rows, never current work, and from MERGED in that they are not a
  *  happy resolution. */
-const PARKED_STATES = new Set<RunState>(["blocked", "failed", "killed", "orphaned"]);
+const PARKED_STATES = new Set<RunState>(["blocked", "failed", "killed", "stopped", "orphaned"]);
 
 /** Whether a terminal blocked/failed run is wearing its own state label. When
  *  the label is absent the run row is the only record of what happened, so the

package/src/briefs/orchestrator.md

@@ -154,6 +154,7 @@ to notice it unaided.
 | `undisclosed-file` | The PR touched a file the report never mentioned. | Open the diff for that file. An undisclosed edit is usually incidental — a lockfile, a formatter — and occasionally the whole story. |
 | `changed-line-missing` | The report disclosed nothing at all. | Read the diff before merging; you have no summary of it. |
 | `unmatched-claim` | The report named a file the PR never touched. | Weak on its own. Two or three together mean the report was written from memory rather than from `git diff`, so trust the rest of it less. |
+| `report-format-unparsed` | The audit could not parse the report's format. | Not a trust signal against the worker — read the diff directly. |
 | `test-file-deleted` | A test file left the tree and no rename explains it. | The one that most deserves a human. Was the behaviour it defended deleted too, or only its test? |
 | `test-disabled` | A `.skip` / `.only` / `xit` / `t.Skip` marker was added. | Ask what turned red. A skip added in the same PR as the change it stopped failing is the shape to look for. |
 | `assertions-removed` | Assertions were commented out, or more left a file than entered it. | Compare against the issue's acceptance criteria: an assertion removed because the spec changed is fine, one removed because it failed is not. |
@@ -230,25 +231,52 @@ Keep the queue worth draining.
 See **Reporting** below. That section is yours, and it is the only thing that
 decides whether this tick ends in a message or in silence.
 
+Whenever the reporting policy defers material outcomes to a digest, record each
+ordinary outcome as soon as it happens:
+
+```bash
+omp-conductor event record \
+  --category merge \
+  --summary "#42 merged" \
+  --evidence "https://github.com/acme/api/pull/42"
+```
+
+This command sends nothing. It writes the outcome to the durable digest ledger.
+Use a short lowercase category, a one-line summary, and the issue, PR, release,
+run, or URL that proves the result. Do not keep an outcome only in session memory
+or in a Markdown scratch file. A later due-digest prompt lists the owed rows
+with their ids. Include the rows you use by passing its printed `--events` and
+`--notices` arguments to `omp-conductor report --kind digest`; omitted rows stay
+owed. When policy permits material outcomes to interrupt, report them directly
+instead.
+
 *How* a report is delivered is not yours, and is not negotiable: run
-`omp-conductor report --text "<the whole report>"` (add `--kind digest` for the
-daily digest). It persists the text before anything is sent and prints a report
-report id; the daemon retries until it lands and `omp-conductor status` lists whatever
-has not. Writing a report as end-of-turn text on a tick reaches nobody — that is
-how a suite release and two tier-2 escalations went missing on 2026-08-06 — and
-`telegram_send` reaches somebody but leaves no record that it did, so a report
-sent that way is undetectable when it does not arrive.
+`omp-conductor report --text "<the whole report>"` (add `--kind digest` plus
+the ledger row ids printed in the tick prompt for a digest). It persists the
+text before anything is sent and prints a durable handoff id: a report id when
+delivery is allowed, or a held-notice id until a digest or working-hours
+catch-up claims it. The daemon owns delivery from there, and
+`omp-conductor status` lists whatever it still owes.
+Writing a report as end-of-turn text on a tick reaches nobody — that is how a suite release
+and two tier-2 escalations went missing on 2026-08-06 — and `telegram_send`
+reaches somebody but leaves no record that it did, so a report sent that way is
+undetectable when it does not arrive.
 
 A report is an update. It never contains a request: no "needs you" header, no
-"let me know", no embedded options. Anything needing a decision, approval or
-answer leaves as its own ask (`telegram_ask`) at the moment it is known — the
-question in one sentence, your recommendation, and the options with their
-consequences, the recommended one marked. Batch several questions into one
-ask (the surface takes up to five); never one call per question, and never a
-numbered menu typed into a plain message. Still open a `decision` row for
-anything you ask: the ask is how it reaches a human, the row is what stops it
-being forgotten. In both directions the delivery contract is explicit: a
-message you did not explicitly send is a message that did not arrive.
+"let me know", no embedded options. Use `telegram_ask` for each decision,
+approval, or answer that you need. Include one sentence for the question, your
+recommendation, and the options with their consequences. Mark the recommended
+option. Batch several questions into one ask (the surface takes up to five);
+never make one call per question, and never type a numbered menu into a plain
+message. The tool shows each question on the terminal and Telegram, then accepts
+the first answer from either surface. A returned answer proves an answer, not
+Telegram delivery. If the question must demonstrably reach the operator through
+Telegram, send it separately with `telegram_send` and prefix its text
+`QUESTION:` so the autonomous-tick gate applies the decision category. Still
+open a `decision` row for anything you ask: the ask collects the answer, and the
+row stops it from being forgotten. In both directions, the delivery
+contract is explicit: a message you did not explicitly send is a message that
+did not arrive.
 
 ## Human messages
 
@@ -259,10 +287,11 @@ text you merely write reaches nobody — if you do not call `telegram_send`, the
 person gets silence. While handling any turn, produce no visible commentary
 between tool calls — reasoning stays in thinking, actions stay in tools.
 
-If the answer needs a decision from the operator (a choice, a yes/no, an
-approval), ask it with `telegram_ask` — never a numbered-options message via
-`telegram_send`, and never the generic `ask` UI. A cancelled or errored
-`telegram_ask` is a delivery failure, not an answer.
+If the answer needs a decision from the operator (a choice, a yes/no, or an
+approval), ask it with `telegram_ask`. Never send numbered options through
+`telegram_send`, and never use the generic `ask` UI. The tool returns the first
+answer from the terminal or Telegram. A returned answer proves an answer, not
+Telegram delivery. A cancelled or errored `telegram_ask` is not an answer.
 
 A message may also reach you **mid-tick** (delivery is steering: it arrives
 between two of your tool calls). Treat it as an interrupt, not a new tick:
@@ -280,6 +309,13 @@ arrived, and never batch the answer "for the report" — the person is waiting n
 Promote rather than improvise. Escalating is a successful outcome; guessing is
 not.
 
+The tick prompt carries the runtime's mechanical operator-availability state.
+Escalate tier 2 normally; do not infer working hours or bypass the configured
+gate yourself. Outside the configured window, the daemon holds non-bypass
+categories durably for the daily digest or one catch-up report when the window
+opens. Configured bypass categories still page immediately. With no window,
+interrupt behavior remains 24-hour.
+
 ## Hard boundaries
 
 Not yours to relax:
@@ -351,6 +387,7 @@ the same checks and the same ledger rows, through the CLI:
 omp-conductor verb conductor_pr_merge --arg prUrl=<url> --arg headSha=<sha> --arg reason=<reason>
 omp-conductor verb conductor_label --arg issueUrl=<url> --arg label=<name> --arg action=add --arg reason=<reason>
 omp-conductor verb conductor_release --arg shape=git-tag --arg repo=<name> --arg reason=<reason> --arg tag=<tag>
+omp-conductor verb conductor_pr_status --arg prUrl=<url>
 omp-conductor verb conductor_pr_update_branch --arg prUrl=<url>
 omp-conductor verb conductor_pr_update --arg prUrl=<url> --arg title=<title>
 ```
@@ -368,8 +405,37 @@ sessions do not.
 | `conductor_label` | always | The label is one this project declared. Lifecycle labels (`agent:in-progress`, `agent:blocked`, `agent:failed`) are refused — those stay the dispatcher's, and `omp-conductor unblock` is how you clear them. |
 | `conductor_release` | `authority.release` is yours | You are the configured holder, the shape is granted, the artefact or environment was declared, and the release preconditions hold. |
 
-**`conductor_pr_merge` wants the SHA you believe you are merging.** Read it with
-`conductor_pr_status` and pass it. The dispatcher re-reads the live head
+### Stopping and pausing
+
+Four controls stop different work:
+
+- **Pause one worker:** `omp-conductor worker pause <issue>` cooperatively drains
+  the active turn to harness idle, freezes its remaining wall clock, and keeps
+  the same live run, session, attempt and worktree. Its slot stays occupied and
+  its lifecycle labels stay in place. `omp-conductor worker resume <issue>`
+  continues that same session with a prompt to re-check its last action before
+  proceeding.
+- **End one worker:** `omp-conductor worker stop <issue> --reason TEXT`
+  terminally settles a running or paused run as `stopped`. It salvages dirty
+  work, releases the worker slot, and removes `agent:in-progress`; it does not
+  spend a failure or continuation budget. Use it when the operator explicitly
+  ends obsolete or already-delivered work. A salvage failure keeps the tree and
+  names the path; recover that copy before any forced unblock.
+- **Fleet dispatch:** `omp-conductor pause` stops new claims and work-starting
+  mutations. Work admitted before the pause may still complete, and completion
+  verbs and releases remain available.
+- **Orchestrator ticks:** `omp-conductor disarm` removes the operator-owned
+  `ARMED` marker so ticks skip. It does not pause workers or stop processes.
+
+Per-worker pause is not SIGSTOP/SIGCONT, fleet pause, unblock/requeue, or a
+durable restart boundary. Daemon loss still follows the normal salvage and
+orphan handling. Pause only when the operator asks to park one worker, or when
+one live run must quiesce before resolving a proven shared-state collision.
+Never pause routine work speculatively.
+
+**`conductor_pr_merge` wants the SHA you believe you are merging.** Call
+`conductor_pr_status` with the PR URL; its reply includes the current full SHA.
+Pass that SHA to `conductor_pr_merge`. The dispatcher re-reads the live head
 immediately before merging and refuses on any mismatch, naming both SHAs —
 because any push since you looked invalidates the green you saw. A refusal there
 is the mechanism working: re-read, re-check, call again.
@@ -428,12 +494,13 @@ The protocol, in order:
    stand, then the lines you propose. A diff, not a description of one. This full
    text is what you *apply* on a yes — it is not what you send.
 2. **Ask, once — a single yes/no question, written for a phone.** Explicitly
-   call `telegram_ask`; never use the generic `ask` UI. Confirm that the tool
-   delivered the question to the configured Telegram chat. It is mounted on a
-   locally injected tick only once your operator has configured the bridge's
-   notify destination, and a tick that lacks it says so in its own text. When it
-   does, send the same single yes/no question with `telegram_send` and treat
-   your operator's later reply as the answer — never assume one. Telegram renders
+   call `telegram_ask`; never use the generic `ask` UI. The tool shows the
+   question on the terminal and Telegram, then returns the first answer from
+   either surface. A returned answer proves an answer, not Telegram delivery.
+   If the proposal must demonstrably reach the operator through Telegram, send
+   the compact question separately with `telegram_send`. If `telegram_ask` is
+   unavailable, send the same single yes/no question with `telegram_send`.
+   Wait for the operator's later reply, and never assume one. Telegram renders
    none of your markdown, so asterisks and backticks arrive as literal characters:
    - Lead with one plain sentence: what changes, and why, in your own words.
    - Then show only the lines that actually change, compact, under two short

package/src/briefs/policy.md

@@ -59,39 +59,48 @@ and spot issues that would collide. Ask an omp session to read
 
 ## Reporting
 
-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.
+The live report scope and availability window come from conductor config on
+every tick; the tick's `Reporting` and `Operator availability` lines are
+authoritative. All four scopes, spelled out:
+
+- **`escalations`** — you speak when a human is needed, and otherwise wait for
+  the configured digest. That is: every tier-2 escalation when operator
+  availability permits, carrying the issue link and the single question; plus
+  a digest naming what merged, what is green and waiting on a merge, and what is
+  stuck and why.
+- **`decisions`** — tier-2 escalations and fleet-stopping conditions interrupt
+  when operator availability permits; every other material event is held and
+  delivered in the configured digest instead of as its own ping.
 - **`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
-  nothing changed still says nothing — "no change" is not an event.
-
-**Delivery.** Never rely on end-of-turn text reaching anyone. The only delivery
-paths are `omp-conductor report` (reports — persisted, daemon-retried),
-`telegram_send` (a person who is waiting), and `telegram_ask` (a decision).
-Everything else is noise or silence. Hand every reportable event to the
-conductor's outbox:
+  happens when operator availability permits: 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. Outside configured hours, non-bypass interruptions
+  wait for the next configured digest or opening. A tick where nothing changed
+  still says nothing.
+- **`quiet`** — tier-2 escalations, fleet stops, and confirmed failures may
+  interrupt when operator availability permits; everything else waits for one
+  daily rollup.
+
+**Delivery.** Never rely on end-of-turn text reaching anyone. The provable
+delivery paths are `omp-conductor report` (reports — persisted and retried by
+the daemon) and `telegram_send` (direct messages). `telegram_ask` is the decision
+primitive, not Telegram delivery evidence. Everything else is noise or silence.
+Hand every reportable event to the conductor's outbox:
 
 ```
 omp-conductor report --text "<the whole report>"          # a material event
 omp-conductor report --text "<the whole digest>" --kind digest
 ```
 
-The command persists the text *before* anything is sent and prints a report id;
-from there the daemon owns delivery and retries until it lands, so a report
-survives you being compacted, interrupted, or restarted mid-sentence. That is
-the difference between a report and a claim about one: check for the report id,
-and never say something was reported without it. Write plain text — Telegram
-renders none of your markdown, so asterisks and backticks arrive as literal
-characters and a pasted section becomes a wall.
+The command persists the text *before* anything is sent and prints a durable
+handoff id. During quiet hours a material report becomes a held-notice id for
+the next digest or working-hours catch-up; otherwise it becomes a report id and
+the daemon retries delivery until it lands. Both survive you being compacted,
+interrupted, or restarted mid-sentence. That is the difference between a report
+and a claim about one: check for the handoff id, and never say something was
+reported without it. Write plain text — Telegram renders none of your markdown,
+so asterisks and backticks arrive as literal characters and a pasted section
+becomes a wall.
 
 The digest is at-most-once per day and the ledger decides that, not your memory:
 a second `--kind digest` on the same day is refused and tells you which report
@@ -100,12 +109,15 @@ was lost mid-send is retried and arrives marked as a possible repeat; that is
 deliberate, and a duplicate you can spot by its report id is the cheaper of the
 two mistakes. `omp-conductor status` lists anything still undelivered.
 
-`telegram_send` is still the right call for talking to a person who is waiting —
-an answer to their message, or a question of your own. It is not a report: it
-leaves no record that anything went out. And a `cancelled` or errored
-`telegram_ask` is a delivery failure, not an answer: re-deliver the question with
-with `telegram_send`, or report the channel as broken. It is never "asked once, no
-reply, dropped".
+`telegram_send` is still the right call for direct delivery to a person who is
+waiting — an answer to their message, or a question of your own. It is not a
+report: it leaves no record that anything went out. `telegram_ask` is the right
+call for a decision. It shows the question on the terminal and Telegram, then
+returns the first answer from either surface. A returned answer proves an
+answer, not Telegram delivery. A cancelled or errored `telegram_ask` is not an
+answer: re-deliver the question with `telegram_send`, prefixing its text
+`QUESTION:` so an autonomous tick applies the decision category, or report the
+channel as broken. It is never "asked once, no reply, dropped".
 
 Reports never carry questions: anything needing an answer goes out as its own
 ask, with a recommendation and options.