omp-conductor 0.13.0 → 0.14.0

package/README.md

@@ -75,34 +75,31 @@ Reporting is the one half of that the config also knows about, because the wizar
 has to ask something in order to seed the brief, and it is the one half the
 runtime acts on:
 
-| `reporting.scope` | What the orchestrator says unprompted | The line every tick carries |
+| Setup choice | What may interrupt | What waits |
 | --- | --- | --- |
-| `material` (default) | Escalations, plus every material event: a run reaching a green PR, a run that failed twice, an issue pulled off the queue, a cap that stopped the fleet. | `Report material events per your brief.` |
-| `escalations` | Escalations when they happen, plus one daily digest. Silent otherwise. | `Report NOTHING this turn except a Tier 1 or Tier 2 escalation; everything else -- releases included -- waits for the daily digest.` |
-| `decisions` | Tier-2 decisions and fleet-stopping conditions immediately; every other material event is held and ships with the next tick report, as one message. | `Reporting scope decisions: interrupt only for a decision you need (tier-2) or a condition that stops the fleet. Every other material event accumulates and ships as ONE message with this tick's report via omp-conductor report -- a merge, a green PR, a pulled issue wait for the tick; nothing between ticks.` |
+| `material` | Every configured material event, when operator availability permits. | Non-bypass events outside configured hours wait for the next configured digest or opening. |
+| `escalations` | Tier-2 escalations, when operator availability permits. | Everything else waits for the configured digest. |
+| `decisions` (recommended) | Tier-2 decisions and fleet-stopping conditions, when operator availability permits. | Every other material event is recorded durably and ships with the configured digest as one message. |
+| `quiet` | Tier-2 escalations, fleet stops, and confirmed failures, when operator availability permits. | Everything else waits for one daily rollup. |
 
 **What the scope does:** the [orchestrator heartbeat](#orchestrator-tick) appends
-that line to every tick it sends, so the reporting contract arrives with the
-prompt instead of only in a brief the session read hours ago. It is re-read from
-`~/.omp/conductor/config.json` on **every** tick, so turning the volume up or
-down — `/conductor setup` again, or an edit to the file — binds the next tick
-without restarting the session. Three cases fall back to `material`: no config
-yet, an unreadable or invalid one, and several projects with none named (the same
-ambiguity `status` refuses to guess through). Stopping the heartbeat over a
-reporting preference would be the worse trade, so it ticks on the default and
-logs the reason once.
-
-**What it does not do:** there is no hard outbound filter. Nothing inspects the
-orchestrator's messages and drops the ones your scope did not ask for, so a
-session that ignores its constraint line still reaches you. Scope is a
-constraint the model is handed each turn. It is not a gate the model is held to.
-The enforcement roadmap (a tool-call tripwire, and config-versus-behaviour drift
-in the daily digest) is
-[issue #11](https://github.com/TerrifiedBug/conductor/issues/11).
-
-Changing the key later does not rewrite an `ORCHESTRATOR.md` you already have:
-the tick line changes, the brief does not. Edit its Reporting section too, or the
-session is carrying two versions of your policy.
+the current constraint to every tick it sends, so the reporting contract arrives
+with the prompt instead of only in a brief the session read hours ago. Explicit
+policies name their actual interrupt categories and digest cadence. The policy is
+re-read from `~/.omp/conductor/config.json` on **every** tick, and escalation,
+direct Telegram, and durable report paths apply it mechanically. Turning the
+volume up or down — `/conductor setup` again, or an edit to the file — therefore
+binds the next tick without restarting the session.
+
+No config, an unreadable or invalid config, or several unnamed projects fall
+back to the legacy `material` scope for the heartbeat and log the reason once.
+An invalid live availability policy blocks autonomous Telegram fail-closed; it
+does not guess that the operator is awake.
+
+Changing the key later does not rewrite an `ORCHESTRATOR.md` you already have.
+The generated `POLICY.md` describes every scope without pinning the current
+choice; the tick constraint remains derived from live config. Keep any
+operator-owned reporting additions in `ORCHESTRATOR.md` consistent with it.
 
 ## Where issues come from
 
@@ -808,6 +805,10 @@ every check succeeded or was skipped. Missing or nonterminal checks become
 `pushed-pending` and are rechecked on later ticks; red or cancelled checks become
 `failed` with a bounded job/log digest. Only verified evidence becomes
 `pushed-green`.
+If a failed report mentions PRs only in prose, the daemon retains the last URL
+whose `owner/repo` matches the run's repository; links to other repositories are
+ignored. This preserves the continuation target without trusting an unrelated
+PR mentioned in the same report.
 
 What happens after verification is a human's decision, taken minutes to days
 later and never announced to the daemon — so every tick asks the tracker about
@@ -816,14 +817,15 @@ every pushed PR it is still holding:
 | PR | Row becomes | Why |
 | --- | --- | --- |
 | merged | `merged` | The work landed. This is the state `merged` was reserved for. |
-| closed without merging | `failed`, with the PR in `lastError` | A human read the work and said no. Leaving it `pushed-green` strands the issue forever behind a PR nobody will merge, and calling it `merged` is a lie about code that is not on the base branch. `failed` is true, and it releases the issue so a re-queue can be attempted again. |
+| closed without merging | `failed`, class `returned-for-revision`, with the PR in `lastError` | A human read the work and asked for another pass. Leaving it `pushed-green` strands the issue forever behind a PR nobody will merge, and calling it `merged` is a lie about code that is not on the base branch. `failed` is the honest row state; the class preserves the review decision and releases the issue so a re-queue can be attempted again. |
 | still open | unchanged | The normal steady state. Its issue must stay occupied, or a second attempt lands on the live PR. |
 | could not be determined | unchanged | A flaky network, a revoked token, a deleted PR. An unknown answer never settles a row; the next tick asks again for free. |
 
-Run history is untouched. A PR closed without merging becomes a concrete failed
-attempt; a merge does not spend failure or continuation budget. A settled row also
-loses `agent:in-progress` from its issue: the row transition and the label are one
-fact, and a terminal answer about the PR proves no worker process owns the issue,
+Run history is untouched. A PR closed without merging consumes one continuation,
+not a failed implementation attempt; a merge spends neither budget. A settled
+row also loses `agent:in-progress` from its issue: the row transition and label
+removal are one fact, and a terminal answer about the PR proves no worker
+process owns the issue,
 so the duplicate-dispatch guard it exists for is spent. The removal is *enqueued
 on the label projection outbox in the same breath as the terminal write* — a
 durable local write that cannot fail on the tracker — so the row settles at once
@@ -848,6 +850,30 @@ issues carrying `agent:in-progress`, which eligibility reads as "a worker owns
 this" — with the brief forbidding the orchestrator from editing a state label and
 `unblock` declining to clear that one, neither issue could ever be claimed again.
 
+### Base-branch health after merge
+
+The daemon records two different facts after a merge:
+
+- The **post-merge audit** attributes a regression to one merge. For up to 24
+  hours, it checks only push-triggered workflow runs for the exact merge SHA and
+  base branch. A new red result adds `base-branch-red` evidence and escalates.
+- **Current health** drives `status` and release policy. On every sweep, the
+  daemon resolves the live head of each branch it merged into during the last
+  seven days, then reads only push-triggered runs for that head and branch. The
+  status row includes the head SHA and run count.
+
+Current health is `green` only when every observed run completed successfully,
+neutrally, or skipped. A failing conclusion is `red`; an in-progress or
+unrecognised conclusion is `pending`; and a head with no push-triggered run is
+`unknown`, never green. Pending and unknown heads are rechecked. Green and red
+heads are read again when the branch moves, so an old verdict cannot describe a
+new commit. If GitHub cannot return the head or its runs, the daemon keeps the
+last honest row instead of replacing evidence with a network failure.
+
+The `base-branch-green` release requirement reads this current live-head row for
+the repository being released. Red, pending, unknown, and absent evidence all
+refuse the release.
+
 ### The settlement audit
 
 Verifying `state: pushed-green` left two lines of the same report still taken on
@@ -868,6 +894,7 @@ change a run's state, hold a merge, or spend an attempt.
 | `undisclosed-file` | The PR touched a file the `changed:` line never named. Lockfiles are exempt — they are derived from a manifest the report did disclose. |
 | `changed-line-missing` | The report had no usable `changed:` line at all. One flag, not one per file. |
 | `unmatched-claim` | `changed:` named a path the PR never touched. The weaker direction, and reported as such. |
+| `report-format-unparsed` | The same file appeared as both claimed-but-untouched and touched-but-unclaimed, so the `changed:` line's format defeated the parser. Read the diff directly; this is not a trust signal against the worker. |
 | `test-file-deleted` | A test file left the tree with no rename to account for it. |
 | `test-disabled` | A `.skip` / `.only` / `xit` / `@pytest.mark.skip` / `t.Skip` marker appears on a line the PR added. |
 | `assertions-removed` | An assertion was commented out, or a test file lost more assertions than it gained. |
@@ -1298,20 +1325,72 @@ a report reached you only if the model remembered to call `telegram_send`. On
 none of the three arrived, and nothing anywhere recorded that fact — an undelivered
 report and a quiet tick look identical.
 
+### Material events survive the session
+
+A deferred digest does not use the session transcript as its source of truth.
+Record each ordinary outcome when it happens:
+
+```bash
+omp-conductor event record \
+  --category merge \
+  --summary "#42 merged" \
+  --evidence "https://github.com/acme/api/pull/42"
+```
+
+`--category` is a short lowercase slug. `--summary` states the outcome, and
+`--evidence` names the issue, PR, release, run, commit, or URL that proves it.
+Use `--occurred-at <ISO timestamp>` when the event happened earlier; otherwise,
+the command uses the current time. The command writes one row to SQLite and
+sends nothing. The row survives later ticks, session compaction, session
+replacement, and daemon restarts.
+
+When a digest is due, its tick prompt lists a bounded, oldest-first set of
+owed material events and deferred escalations. Each line includes its ledger id.
+The prompt gives the exact handoff shape:
+
+```bash
+omp-conductor report \
+  --kind digest \
+  --events EVENT_ID_1,EVENT_ID_2 \
+  --notices NOTICE_ID_1,NOTICE_ID_2 \
+  --text "<the whole digest>"
+```
+
+Remove the id of any row you did not use. Omitted rows stay owed. The report row
+and the named ledger rows are associated in one SQLite transaction. If the
+handoff fails, no row is consumed. If a daily report deduplicates against a
+daily report already queued that day, newly named rows also stay owed. If
+delivery exhausts its retry budget and the report becomes `failed`, its rows
+return to the owed backlog, where a replacement digest can claim them.
+`omp-conductor status` always shows the
+material-event and held-escalation backlog counts, including the age of the
+oldest row when one exists.
+
+This accumulator does not poll GitHub and does not infer outcomes from tracker
+state. The orchestrator still decides what is material and records the evidence.
+The mechanism only makes that decision durable until a non-failed digest owns it.
+
 Authorship still needs judgement the daemon does not have, so it stays with the
 model. Delivery does not, so it moved:
 
 ```bash
-omp-conductor report --text "<the whole report>"                 # one material event
-omp-conductor report --text "<the whole digest>" --kind digest   # the daily digest
+omp-conductor report --text "<the whole report>"  # immediate report, when policy permits
+omp-conductor report \
+  --text "<the whole digest>" --kind digest \
+  --events EVENT_IDS --notices NOTICE_IDS          # use row ids from its tick
 ```
 
-The command writes the text into a `reports` table in the store and prints a
-report id. Nothing has been sent at that point, and that is the guarantee: the
-report survives the session being compacted, interrupted or restarted, and it
-survives the daemon being restarted under it. The daemon then delivers it over
-the same bot token tier 2 uses, with bounded retries, and `omp-conductor status`
-lists anything that has not landed.
+The command persists the text before anything is sent and prints a durable
+handoff id. An immediate report admitted during quiet hours is stored as a held
+notice and prints that id; the daemon includes it in the next digest or in a
+catch-up report when the configured window opens. Otherwise it writes a
+`reports` row and prints its report id. Both survive the session being
+compacted, interrupted or restarted,
+and the daemon being restarted under it. The daemon delivers over the same bot
+token tier 2 uses, with bounded retries, and `omp-conductor status` lists
+anything it still owes. If availability closes after a material report was
+queued but before its first attempt, the outbox atomically converts that row to
+the same held-notice path instead of leaking the update through quiet hours.
 
 ### Delivery is at-least-once, and the docs will not pretend otherwise
 
@@ -1374,14 +1453,16 @@ then the only surface — a report has no tracker issue, so there is no issue
 comment to fall back to. The page goes through the ordinary escalation ledger and
 carries the report id, so one undeliverable report pages exactly once.
 
-### The daily digest is deduplicated from the ledger
+### Daily digests are deduplicated from the ledger
 
-`--kind digest` is accepted at most once per **local** day, per project. The
-second hand-over on the same day is refused and told which report already holds
-the slot, including when that report has already been delivered. This is decided
-from the `reports` table, not from the model's memory of the last tick — a
-restarted or compacted session cannot send a second digest by forgetting the
-first. Material reports carry no such key: two events in a day are two events.
+With `digest.cadence: "daily"`, `--kind digest` is accepted at most once per
+**local** day, per project. The second hand-over on the same day is refused and
+told which report already holds the slot, including when that report has already
+been delivered. This is decided from the `reports` table, not from the model's
+memory of the last tick — a restarted or compacted session cannot send a second
+daily digest by forgetting the first. A `per-tick` digest carries no daily key,
+so later ticks can hand off newly accumulated rows. Material reports carry no
+dedupe key either: two events in a day are two events.
 
 ### What `status` shows
 
@@ -1477,6 +1558,7 @@ persists the class on the row, and performs the one recovery that class names.
 | --- | --- | --- | --- |
 | `env-start-failure` | turn 0 plus an explicit harness start error (`No model selected`, a rejected key) | escalate — the session never read the issue | none |
 | `settlement-stuck` | a row carrying a PR that has since merged | settle: release the label, mark the row merged | none |
+| `returned-for-revision` | a `pushed-green` or `pushed-pending` PR was closed without merging | none — preserve the review decision for a human re-queue | continuation |
 | `merge-conflict` | `pushed-green`, PR open, GitHub reports conflicting | requeue for a rebase continuation | continuation |
 | `question` | the worker stopped to ask something (`blocked`) | escalate, carrying the worker's own report as evidence | none |
 | `orphan-dirty` | orphaned with a failed salvage and no operator ack | hold — recorded only; the tree is the only copy | none |
@@ -1486,7 +1568,9 @@ persists the class on the row, and performs the one recovery that class names.
 | `admin-kill` | killed *below* its own ceiling — a restart or a drain | requeue | none |
 | `ci-infra` | PR open, every unresolved check cancelled / timed out / stale | re-run the failed jobs | none |
 | `ci-deterministic` | PR open, a check genuinely reports `FAILURE` | escalate with the failing check names and links | failed attempt |
+| `dispatch-infra` | the conductor's own Git path failed before the worker's first turn | requeue, bounded by per-class strikes | none |
 | `provider-credit` | the provider refused the run for credit (HTTP 402, or its own out-of-credit text read off the transcript) | pause the fleet and require `omp-conductor resume` once the provider has credit | none |
+| `provider-transient` | the provider aborted a request stream before the run produced a verdict | requeue, bounded by per-class strikes | none |
 | `unknown` | anything unrecognised | escalate | as recorded |
 
 **Unknown escalates; it never silently retries.** A shape this table does not
@@ -1496,13 +1580,14 @@ cause nobody has named — the behaviour this exists to end.
 ### The budgets follow the cause
 
 `failuresFor` (implementation attempts) excludes `ci-infra`, `settlement-stuck`,
-`env-start-failure` and `provider-credit`; `continuationsFor` excludes
-`admin-kill`, `settlement-stuck`, `env-start-failure` and `provider-credit`. An
-environment fault charges neither: the session never started, so nothing about
-the issue was attempted, and nor does a provider-credit refusal, which is a
-billing state rather than an implementation failure. A merge conflict *is*
-charged as a continuation, because a rebase is real work — just never as a
-failed implementation attempt.
+`env-start-failure`, `dispatch-infra`, `provider-credit`, `provider-transient`
+and `returned-for-revision`. `continuationsFor` excludes `admin-kill`,
+`settlement-stuck`, `env-start-failure`, `dispatch-infra`, `provider-credit`
+and `provider-transient`, but explicitly counts a failed
+`returned-for-revision` row. Environment, dispatch and provider faults charge
+neither budget because the issue did not receive a valid implementation
+attempt. A merge conflict and a returned review both charge a continuation:
+each asks for more work, but neither is a failed implementation attempt.
 
 An **unclassified** row (every row written before 0.4.3) counts exactly as it
 did before classification existed. Upgrading therefore changes no existing
@@ -1686,7 +1771,7 @@ Field notes:
 | `escalation.orchestrator` | Optional; `"embedded"` (default) or `"external"`. `external` means an orchestrator session already runs elsewhere: the daemon starts none, and tier-1 escalations post as issue comments for that session to drain. Any other value is an error. |
 | `authority` | Optional; `{ "merge": …, "release": … }`, each `"human"` (default) or `"orchestrator"`. It grants nothing to the daemon — it words the orchestrator's standing orders and the Releases paragraph of the rendered brief, so the config and the prompt cannot disagree about who holds the merge button. Unknown keys and any other value are errors, never folded to the default. |
 | `releasePolicy` | Optional; `"none"` (default) or `"operator-brief"`. `none` installs a pre-tool-call tripwire in worker, embedded-orchestrator and external-orchestrator sessions. It blocks `git tag`, tag pushes, package publishing, GitHub release creation and recognised deploy commands before execution. `operator-brief` opens that gate only for the procedure in the operator-owned brief. Unknown values are errors. Every rejection is written to `release-policy-blocks.jsonl`; the heartbeat carries that day's count into the daily digest so configured intent and observed behaviour cannot drift silently. This is the mechanical gate; `authority.release` still says who owns the decision. |
-| `reporting` | Optional; a **legacy scope preset** (`reporting.scope` — `"material"` default, `"decisions"`, `"escalations"`) or the **explicit form** `{ "interruptOn": [...], "digest": { ... } }`. The preset writes which categories may page the operator (`interruptOn`) and when the rollup happens (`digest.cadence`); the explicit form sets both directly and the two forms are mutually exclusive in one config. See [Reporting policy](#reporting-policy-reporting). |
+| `reporting` | Optional; a **legacy scope preset** (`reporting.scope` — `"material"` default, `"decisions"`, `"escalations"`) or the **explicit form** `{ "interruptOn": [...], "digest": { ... }, "availability": { ... } }`. The preset writes which categories may page the operator (`interruptOn`) and when the rollup happens (`digest.cadence`); the explicit form sets both directly and may add a weekly operator-availability window. The two forms are mutually exclusive in one config. See [Reporting policy](#reporting-policy-reporting). |
 | `orchestratorReadPaths` | **Retired in 0.4.3.** Still accepted in a config and ignored, so a fleet carrying it upgrades without an edit. It widened the orchestrator's file-tool allowlist; there is no allowlist any more — the orchestrator is [unconfined by design](#the-orchestrator-is-unconfined-deliberately). |
 | `policy` | Optional; the gating conditions a merge or a release must satisfy, in two sections — `policy.merge` and `policy.release`. Any member may be omitted and the loader fills it from the strict default; an unknown key in either section, or a value outside its vocabulary, is an error naming the field, never a silent downgrade. See [Merge and release preconditions](#merge-and-release-preconditions-policy). |
 | `workspaceRoot` / `mirrorRoot` | Optional; default to `worktrees/` and `mirrors/` under the state directory. `~` is expanded. |
@@ -1708,13 +1793,66 @@ spellings, mutually exclusive in one config (the loader rejects a `scope` next t
 - **Explicit** — `reporting: { "interruptOn": ["tier2", "fleet-stopped", ...], "digest": { "cadence": "none" | "per-tick" | "daily" } }`.
   `interruptOn` must be a non-empty array of known categories (`tier2`, `decision-needed`, `fleet-stopped`, `confirmed-failure`, `material`), each an escalation's tier-2 category. `daily` may add `at` (`HH:MM`, 24h) and `timezone` (a known IANA zone, defaulting to the host zone) — both only valid with `daily`.
 
+The explicit form may add a weekly local-time window:
+
+```json
+{
+  "reporting": {
+    "interruptOn": ["tier2", "fleet-stopped"],
+    "digest": { "cadence": "daily", "at": "17:00", "timezone": "Europe/London" },
+    "availability": {
+      "timezone": "Europe/London",
+      "days": ["mon", "tue", "wed", "thu", "fri"],
+      "start": "09:00",
+      "end": "17:00",
+      "bypass": ["fleet-stopped"]
+    }
+  }
+}
+```
+
+`timezone` must be a known IANA zone. For a daily digest, its timezone defaults
+to this value and must match it when both are set.
+
+`days` is a non-empty set of `mon` through `sun`; `start` is inclusive and
+`end` is exclusive. A start later than the end defines an overnight window on
+the day it opens. `bypass` is an explicit list of known interrupt categories
+that may still page outside the window; it may be empty. For ordinary notices,
+a bypass has no effect on a category omitted from `interruptOn`. Urgent recovery
+notices may bypass category batching when the digest loop itself is unavailable,
+but they still require the configured availability bypass outside the window.
+
+The setup wizard offers this as **Weekly availability window** and asks for the
+zone, days, start/end, bypass categories, and digest schedule: every tick,
+model-timed daily, disabled, or a fixed daily `HH:MM`. Re-running setup or
+amending reporting preselects and preserves the configured `none`, `per-tick`,
+or `daily` cadence. Choosing **Continuous (24-hour interrupts)** is the explicit
+opt-out and preserves the behavior of every existing config; an absent
+`availability` key also means continuous operation.
+
+Outside the window, an otherwise interruptible escalation is stored durably
+instead of sent. A daily digest may consume it first. Otherwise the daemon
+atomically queues one working-hours catch-up report when the window opens,
+including after downtime; associating the held rows before delivery prevents a
+later tick from authoring a duplicate. Each heartbeat prompt names the
+mechanically computed current mode and next transition. `status` shows the same
+state plus the next digest opportunity (`due now`, every tick, disabled, or its
+next operator-local timestamp). Config, escalation routing, and report transport
+are re-read at tick or send time, so changing the window or Telegram target
+does not require a daemon restart.
+
+Attachment-bearing autonomous Telegram sends cannot be replayed by the text
+digest, so they are blocked with an explicit “nothing sent or held” error rather
+than silently dropping their files.
+
 A tier-2 escalation whose category is **not** in `interruptOn` is not dropped: it
 is held (`held_notices`) and the next accepted digest is its delivery authority.
-The digest itself is at-most-once per local day (`digest:<YYYY-MM-DD>` in the
-configured zone), which remains the delivery authority across restarts. A
-scheduled `daily` digest is only sent on a day it has not already run, once the
-local clock has passed `at`; a restart after `at` still sends today's (one
-catch-up), and a fully missed day is skipped, never sent late.
+A `daily` digest is at-most-once per local day (`digest:<YYYY-MM-DD>` in the
+configured zone), which remains the delivery authority across restarts.
+`per-tick` digests are not daily-deduplicated, so a later tick can claim newly
+accumulated rows. A scheduled `daily` digest is only sent on a day it has not
+already run, once the local clock has passed `at`; a restart after `at` still
+sends today's (one catch-up), and a fully missed day is skipped, never sent late.
 
 ### Merge and release preconditions (`policy`)
 
@@ -1737,7 +1875,7 @@ policy instead of restating it — no threshold lives in two places.
 
 | Field | Values | Default | Means |
 | --- | --- | --- | --- |
-| `requires` | `runs-settled`, `no-open-prs`, `queue-drained`, `base-branch-green`, `epic-children-closed` | `["runs-settled"]` | What must already have landed. `base-branch-green` requires the newest observed post-merge workflow verdict for that routed repository to be green; pending, unknown, red, or no observation refuses release. Order and duplicates do not matter; the loader canonicalises. |
+| `requires` | `runs-settled`, `no-open-prs`, `queue-drained`, `base-branch-green`, `epic-children-closed` | `["runs-settled"]` | What must already have landed. `base-branch-green` requires the current live head's push-triggered workflow verdict for that routed repository to be green; pending, unknown, red, or no observation refuses release. Order and duplicates do not matter; the loader canonicalises. |
 | `requiredChecks` | any check names | `[]` | Checks that must be green on the branch being released. Empty means every check it reports. |
 | `artefacts` | any names | `[]` | The packages or images this project releases. **Empty denies**: nothing has been authorised to ship. |
 | `environments` | any names | `[]` | Deploy targets. **Empty denies** every environment. |
@@ -1797,13 +1935,14 @@ writes this file for external orchestration. A manual configuration has this for
 | `budgetSeconds` | no | `600` | Seconds a turn may run before the tick guard refuses its remaining tool calls (#189), and before a queued operator message preempts them. An integer ≥ 60; anything else degrades to the default. |
 | `armedFile` | no | none — the gate passes | Path to the arm marker. A tick does nothing while the file is missing. Relative paths resolve against the session cwd, so `state/armed` means `<cwd>/state/armed`. |
 | `accessFile` | no | none — the gate passes | Path to the Telegram bridge's `access.json`. Every tick re-reads it and requires `enabled: true` with exactly one entry in `allowFrom`. Relative paths resolve against the session cwd. **Configure this on any fleet deploy** — see below. |
-| `message` | no | `Tick <ISO timestamp>: re-read <workspaceRoot>/ORCHESTRATOR.md from disk, then run your standing loop from it.`, then the `reporting.scope` line, then the delivery rule | Sent verbatim when set — and then it owns the whole contract: neither the scope line nor the delivery rule is appended to a prompt you wrote yourself. Re-read from disk on **every** tick, so rewording it binds the next heartbeat instead of waiting for a session restart; a re-read that fails — caught mid-edit, removed, or invalid — keeps the value read at session start rather than stopping the heartbeat. `intervalSeconds` is *not* re-read: rescheduling a live timer still needs a restart. The default *orders* the session to re-read its brief, naming the path resolved from the project's `workspaceRoot`, because a standing prompt drifts out of a long-lived session's context while the file on disk does not. |
+| `message` | no | `Tick <ISO timestamp>: re-read <workspaceRoot>/ORCHESTRATOR.md from disk, then run your standing loop from it.`, then the reporting-policy line, delivery rule, and mechanical availability state | When set, this text replaces the ordinary reporting-policy line and delivery rule, but the runtime-owned availability state is still appended: a custom prompt cannot infer whether the operator may be interrupted. Re-read from disk on **every** tick, so rewording it binds the next heartbeat instead of waiting for a session restart; a re-read that fails — caught mid-edit, removed, or invalid — keeps the value read at session start rather than stopping the heartbeat. `intervalSeconds` is *not* re-read: rescheduling a live timer still needs a restart. The default *orders* the session to re-read its brief, naming the path resolved from the project's `workspaceRoot`, because a standing prompt drifts out of a long-lived session's context while the file on disk does not. |
 | `agentName` | no | `fleet` | The herdr agent name the orchestrator's pane is registered under. Under herdr this is the whole of the identity check below, and the default matches `AGENT_NAME=${AGENT_NAME:-fleet}` in the recovery plugin's `recover.sh`, so both halves key on one name. Rename the agent and set this to match. |
 
-A tick sends one message (`customType` `omp-conductor.tick`, attributed to the
-user): the standing-loop prompt, the one constraint line the project's
-[`reporting.scope`](#your-workflow-vs-the-package) resolves to, re-read from the
-conductor config on every tick, and a delivery rule. That last line is there
+A default tick sends one message (`customType` `omp-conductor.tick`, attributed
+to the user): the standing-loop prompt, the reporting-policy constraint re-read
+from conductor config on every tick, the delivery rule, and the mechanically
+computed operator-availability state. A configured `message` replaces the first
+three parts but not that clock state. The delivery rule is there
 because end-of-turn text reaches the operator's Telegram only on a turn that
 *began* as an inbound Telegram message: a tick is injected locally, so anything
 the session merely writes at the end of one is read by nobody, and a reportable
@@ -2008,7 +2147,8 @@ omp-conductor worker stop <issue> --reason TEXT [--project NAME]
 omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
 omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
 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 event record --category NAME --summary TEXT --evidence REF [--occurred-at ISO] [--project NAME]
+omp-conductor report --text TEXT [--kind material|digest] [--events IDS] [--notices IDS] [--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]
@@ -2042,7 +2182,7 @@ omp-conductor help
 | `unblock <issue> [--force] [--no-requeue]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. The label changes go through the [label projection outbox](#the-tick): they are applied inline before the command returns, but **a tracker that refuses them (403, rate limit) no longer fails the verb** — it exits `0`, the intended label state is durable and the daemon retries it, and the output says `label sync queued (N pending) — the daemon retries` instead of claiming the labels were restored. Safety is preserved, but the issue is only claimable once the queue label itself lands: the queue read asks GitHub for issues carrying that label, so a refused queue-label add keeps the issue out of dispatch until projection succeeds. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
 | `verb <conductor_*> [--arg k=v ...]` | Run one [mediated verb](#the-mediated-verbs-126) as the orchestrator, from the CLI — the external-orchestrator half of the verb surface. Every argument goes in as a `--arg k=v` string; an orchestrator can merge (`conductor_pr_merge`), label (`conductor_label`), release (`conductor_release`), update a branch (`conductor_pr_update_branch`) or title/body (`conductor_pr_update`), or read PR state (`conductor_pr_status`). The daemon applies the same checks and writes the same ledger rows a session's call would; a missing `--arg` is refused exactly as a missing tool argument is, worker-only verbs (`conductor_push`, `conductor_pr_create`) are refused with `role-not-allowed`, and a refusal exits `3`. An unknown verb exits `2`. |
 | `friction <kind> --detail TEXT [--issue N]` | Record one bounded judgment the daemon cannot infer: an escalation belonged in a digest, or a tick report was noise/surprising. The detail is limited to 160 characters. One event never changes policy; three observations inside seven days make the aggregate eligible for one Learning-loop prompt, followed by a seven-day cooldown. |
-| `report --text TEXT [--kind material|digest]` | Hand a rendered report to the daemon's durable outbox. The text is persisted **before** anything is sent and the command prints a report id; the daemon then owns delivery, retries on a bounded backoff, and records the Telegram message id it actually got back. Delivery is [at-least-once](#report-delivery-the-outbox) — a crash mid-send is retried and the retry says it may be a repeat — so `delivered` is never proof of exactly one message. `--kind digest` is accepted at most once per local day, decided from the ledger rather than from what the session remembers sending; an unknown `--kind` exits `2` rather than quietly becoming a material report. Anything undelivered shows in `status` with its age. |
+| `report --text TEXT [--kind material|digest]` | Hand a rendered report to the daemon's durable outbox. The command persists the text **before** anything can send and prints a durable handoff id. A material report submitted during quiet hours becomes a held notice until the window opens; otherwise it becomes a report whose delivery the daemon owns, retries with bounded backoff, and records. Delivery is [at-least-once](#report-delivery-the-outbox), so a crash mid-send is retried as a possible repeat and `delivered` never proves exactly one message. `--kind digest` is accepted at most once per local day, decided from the ledger; an unknown `--kind` exits `2`. Anything still owed appears in `status` with its age. |
 | `decision open --question TEXT [--blocks TEXT] [--resolves-when COND]` | Record a question the orchestrator has put to you, and print its id. A question that lives only in a session's context is lost at the next compaction — after which it is either asked twice or dropped silently. `--resolves-when` attaches a machine-checkable condition: `pr-merged:<https url>`, `pr-checks-green:<https url>`, `pr-mergeable:<https url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`, or `rate-limit-reset:github`; anything else exits `2` listing the six forms. See [The decision ledger](#the-decision-ledger-resolves-when). |
 | `decision resolve <id> --answer TEXT` | Record what you decided. Exits `1` naming the id when it is unknown or no longer open, so a second answer cannot overwrite the first. |
 | `decision withdraw <id> [--reason TEXT]` | Close a question the session stopped needing, with why. Same guard as `resolve`. |
@@ -2261,6 +2401,14 @@ role must equal the configured holder.** `authority` has exactly two values, so
 a `!== "human"` test would have let a *worker* release. A worker is refused
 every release shape under the most permissive config there is.
 
+For Git-backed releases, `git-tag` is idempotent when the named tag exists
+locally but has not been pushed: it re-points the tag to the verified live
+default-branch head. `git-push-tags` performs the same re-point immediately
+before pushing if the default branch moved between the two calls. A tag already
+published on origin is immutable: an identical tag is accepted as already
+complete, while a different published target is refused and must use a new tag
+name.
+
 ### The transport
 
 Identity is never an argument. `project`, `run`, `issue` and the caller's role

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "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/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}.`;
+}