muse-crew 0.14.5 → 0.14.7

package/docs/guide.md

@@ -17,7 +17,7 @@ This is the full setup and operations reference. If you're new, start with the [
 - A **release** — the first immutable snapshot of the crew's runtime code.
 - An **`.orchestration/` directory** in the crew home with identities, personas, workflow docs, and feedback conventions.
 - A **project registration** — the task service registered as its own first project.
-- **Cron jobs** — the scheduler state declared in `seed/crons.json`: a polling loop (every 15 minutes via Muse's scheduling, even when nobody's in the conversation). The scheduler identity is dashboard-independent — chosen once at first init (no owner; the platform rejects `cli:` owners) — so deleting the dashboard artifact does not stop the crew. Removing a crew entirely is `crew-uninstall`'s job.
+- **Cron jobs** — the scheduler state declared in `seed/crons.json`: a polling loop (every 15 minutes via Muse's scheduling, even when nobody's in the conversation), a 5-minute acknowledgement scan (observation-only — runs `scan-ack-pending` so publish verdicts land quickly; it never issues edits), and a daily update watcher. The scheduler identity is dashboard-independent — chosen once at first init (no owner; the platform rejects `cli:` owners) — so deleting the dashboard artifact does not stop the crew. Removing a crew entirely is `crew-uninstall`'s job.
 
 The agent running in the main chat receives the dispatcher's claims and launches each task workflow. Workflows can't launch workflows, so this handoff is structural.
 
@@ -126,7 +126,7 @@ The run has four phases:
 
 1. **Gates** — the crew home must be inside the workspace (uninstall refuses to delete anything outside it), and `confirm: true` must be present. Either missing blocks the run before anything is touched.
 2. **Safety** — if any task is `in_progress`, the run blocks unless `force: true`. Uninstalling under live workflows would strand them.
-3. **Crons** — removes the crew's scheduler jobs, and only those: the exact ids from `$CREW_HOME/.cron-registry.json` (written by init; covers id overrides), plus discovery of `crew-poll-*` jobs whose body contains the crew home path (covers installs from before the registry existed). Anything not on that union is never touched — shared crons are safe by construction, and a missing home still gets its orphaned crons removed.
+3. **Crons** — removes the crew's scheduler jobs, and only those: the exact ids from `$CREW_HOME/.cron-registry.json` (written by init; covers id overrides), plus discovery of `crew-poll-*` / `crew-ack-scan-*` / `crew-update-watch-*` jobs whose body contains the crew home path (covers installs from before the registry existed). Anything not on that union is never touched — shared crons are safe by construction, and a missing home still gets its orphaned crons removed.
 4. **Home** — best-effort `git worktree prune` on the crew's project repos, then deletes the crew home directory and verifies it is gone.
 
 Dashboard artifacts are left untouched — uninstall removes the crew instance (its crons and its home), never the user's artifacts.
@@ -230,7 +230,10 @@ A task in `todo` state becomes eligible for dispatch on the next polling tick. A
 
 ## How the loop works
 
-Every 15 minutes, the `crew-poll` cron fires:
+Every 15 minutes, the `crew-poll` cron fires. (Publish verdicts don't wait
+for it: a separate 5-minute `crew-ack-scan` cron runs the observation-only
+`scan-ack-pending` pass so acknowledgements, refusals, and timeouts land
+within one scan cadence — issuance stays in the poll tick below.)
 
 1. **Cron runs the dispatcher** — `crew-dispatch.js` with the task service slug and `crewHome` as arguments.
 
@@ -364,9 +367,42 @@ Bugfix tasks reproduce at the layer where the bug lives — not always in the br
 
 The workflow dispatches the Reproduce strategy mechanically on the classification. A garbled or missing marker degrades to `artifact` (the old behavior) — a task is never parked on it. The experiential loop is forbidden for engine/docs tasks: if the reproducer drives the browser anyway, the closeout fails the phase loudly for retry, so wrong-layer verdicts never reach Map.
 
-### Publish content verification
+### Publish acknowledgement
 
-The artifact builder's `applied` report is derived from the diff the workflow carries to it, so comparing the report to the diff is circular — canary run 8 (2026-09-11) stamped provenance on a hollow build and every phase went green. The workflow therefore never stamps provenance itself, and since 2026-09-20 (blocker 22) it doesn't even issue the edit: workflow children cannot call `artifact_edit` (the tool requires a parent-conversation session id they don't have), so publish is one-party. The workflow prepares — preflight, provenance base, checksummed diff, pre-trigger manifest baseline — writes one issuer-stamped `publish-intent` ledger entry, and parks with `publish: publish-requested <commit> <attempt>`. The session-carrying tick worker (the only caller class that can reach `artifact_edit`) claims the intent, verifies the diff's sha256, issues the edit directly in its own turn, and records the issuer-stamped `submitted` entry plus `publish: verification-requested`. An unobserved outcome is an unknown outcome, parked fail-closed with an append-only `unknown` ledger entry — never stamped. The parent protocol owns the independent content confirmation: `lib/readback-disk.js` reads the platform's on-disk working copy of the artifact source and `lib/verify-publish.js` compares it mechanically against the base..commit diff (see `docs/publish-verification.md`); only a match stamps provenance. QA's provenance check then enforces the stamp mechanically, so an unverified publish fails loudly in QA instead of passing silently.
+Eric's publication contract (2026-09-20): "If we hear that the artifact acknowledges our version, that's it. We don't verify against content."
+
+The workflow never stamps provenance itself, and it doesn't issue the edit: workflow children cannot call `artifact_edit` (the tool requires a parent-conversation session id they don't have), so publish is one-party. The workflow prepares — preflight, provenance base, checksummed diff with the deterministic per-attempt version — writes one issuer-stamped `publish-intent` ledger entry, and parks with `publish: publish-requested <commit> attempt=N`. The session-carrying tick worker (the only caller class that can reach `artifact_edit`) claims the intent via `scan-publish-intent`, re-derives the version, verifies the diff's sha256, issues the edit directly in its own turn, and records the issuer-stamped `submitted` entry plus `publish: edit-issued` via `record-intent-issuance`.
+
+The ack scan (`scan-ack-pending`) owns the verdict from there: the exact per-attempt version on the artifact's disk is the sole positive completion criterion (2026-09-20 REVIEW removed the circular builder-report positive path; builder reports carry explicit refusals only). Bounds: 30-minute window per attempt, 2-hour total budget from first issuance, no backoff (reissue immediately claimable), fresh version per attempt. Explicit refusal parks terminally (`publish: publish-refused`); budget exhaustion parks `publish: version-timeout`. Silence is unknown and fails closed. See `docs/publish-verification.md` for the full protocol. QA's provenance check then enforces the stamp mechanically, so an unacknowledged publish fails loudly in QA instead of passing silently.
+
+### When publish is stuck
+
+Two different workers move a publish forward, and they own different halves:
+
+- The **5-minute `crew-ack-scan`** is observation-only: it watches the
+  on-disk version receipt and, when a 30-minute window expires, stages the
+  next attempt's intent (fresh version, immediately claimable). It never
+  issues an edit.
+- The **15-minute poll tick** is the only half that issues: its
+  `scan-publish-intent` claims staged intents and its session-carrying
+  worker calls `artifact_edit`.
+
+If the poll tick is down, reissues stay staged and unclaimed — the task
+sits at `publish: edit-issued` (or `publish: publish-requested` for a
+staged reissue) with no new issuance, and eventually the 2-hour total
+budget expires and the ack scan writes the terminal
+`publish: version-timeout`. The timeout is honest: the budget is measured
+from the first issuance, not from the last successful observation, so a
+dead issuer cannot stretch it.
+
+**Runbook:** check the poll tick first — is `crew-poll-*` enabled and
+producing recent tick reports? If yes, the stuck task is a publish-path
+problem (diagnose via `docs/publish-verification.md`'s Operator recovery).
+If no, the ack scan's staged reissues are waiting on an issuer that isn't
+running — fix the poll tick, not the publish machine. In either case, do
+not hand-issue the edit: issuance belongs to the tick worker's
+claim-and-issue path, and an out-of-band edit has no ledger anchor for
+the ack scan to verify against.
 
 ## Identities
 

package/docs/publish-unknown-recovery.md

@@ -1,120 +1,28 @@
-# Publish-unknown recovery (blocker 15, 2026-09-18; one-party 2026-09-20)
-
-When a standard/bugfix Publish parks with "Publish outcome unknown", the
-artifact-edit trigger went out fire-and-forget and no receipt came back —
-async was planned for, receipt-less was not. The unknown-recovery loop
-closes that gap without re-issuing blindly.
-
-(2026-09-20, blocker 22: the trigger child is retired. New publishes park
-at intent, not unknown — see the one-party section of
-docs/publish-verification.md. This document's unknown path is the legacy
-recovery for pre-one-party parks, plus the retry protocol, which now issues
-through the session-carrying tick worker directly — never a child.)
-
-## The note is the state machine
-
-Recovery state lives in the task's `note` events, keyed on machine-written
-`publish: <transition>` markers. Deterministic code (`lib/crew-api.js`) owns
-every transition; the cron tick (Step 4.4) is only the ferry between the
-deterministic steps. The initial park note is the workflow's
-"Publish outcome unknown …" note (no `publish:` marker — the scan matches it
-explicitly); every transition after that is machine-written.
-
-State diagram (latest `publish:` note wins; history is the retry budget):
-
-```
-"Publish outcome unknown" park
-  (< 30m) ──waiting──> scan: waiting (leave alone)
-  (>= 30m) ──scan──> publish: unknown-recovery-claimed <expiry>   (1h lease)
-       │
-       ├─ tick runs lib/classify-publish-absence.js, then
-       │  record-unknown-classification (CAS on the claim expiry):
-       │
-       ├─ verified ──────────> publish: verification-requested <commit>
-       │                        (content IS present; Step 4.5 verifies;
-       │                         ledger: unknown-resolved)
-       ├─ provably-dropped ──> publish: dropped <commit>
-       │                        (queues the retry protocol, next tick)
-       ├─ applied-not-built / ambiguous ──> publish: ambiguous <commit>
-       │                        (terminal; ledger: unknown-classified)
-       ├─ superseded ────────> publish: superseded <commit>  (terminal)
-       └─ deferred ──────────> (no note; the claim expires; the next scan
-                                re-claims and re-classifies)
-```
-
-Retry protocol (Step 4.4, for `publish: dropped` with a free budget):
-
-```
-publish: dropped
-  ── tick: HEAD == commit? no ──> publish: retry-superseded (terminal)
-  ── tick: acquire merge lock publish-retry:<task> (600s); held ──> stop, retry next tick
-  ── tick: re-read content in the lock (classifier)
-       ├─ not provably-dropped ──> record-retry-recheck routes it
-       │    (verified → verification-requested; ambiguous → terminal;
-       │     superseded → terminal; deferred → no-op)
-       └─ provably-dropped ──> publish: retry-intended <commit> <ts>
-            ── tick issues the edit DIRECTLY in its own turn (never a child;
-               blocker 22 — children cannot reach artifact_edit)
-            ├─ explicit refusal ──> publish: retry-refused (terminal)
-            └─ no refusal ──> publish: retry-issued <commit>
-                 ──> publish: verification-requested <commit> not-before=<ts+20m>
-                     (Step 4.5 skips not-before entries until the window passes)
-                 ──> one -retry1 ledger entry (best-effort)
-            ── release the merge lock (every path)
-```
-
-Crash recovery (fail closed, never re-trigger blind):
-
-- `publish: retry-intended` without `retry-issued` → the next scan mirrors
-  `verification-requested` with `not-before=intended+20m`. The trigger may
-  or may not have gone out; content verification is the arbiter.
-- `publish: retry-issued` without a mirrored request → the next scan writes
-  the missing mirror.
-- Exactly one retry per task, enforced from note history: the scan emits
-  `retry_due` only when no `publish: retry-issued` exists in the task's
-  history — including a retry for an earlier unknown attempt on a reworked
-  task. When the budget is spent, the drop is terminal: `publish: ambiguous`.
-
-## Commands
-
-- `scan-publish-unknown` — the cron scan (Step 4.5 of the old numbering).
-  Returns `{ waiting, due, retry_due, mirrored, skipped }`. `due` entries
-  ferry the classifier inputs: `commit`, `trigger_ts` (from the `submitted`
-  ledger entry — never a time window), `park_ts`, `slug`, `repo_path`,
-  `base` (provenance `source_commit`, else the empty tree), and
-  `claim_expiry` for the record CAS. `retry_due` entries ferry the retry
-  inputs (`commit`, `attempt`, `slug`, `repo_path`, `base`, `ledger_path`).
-- `record-unknown-classification --json '{task_id, claim_expiry, decision}'`
-  — routes the classifier's decision; CAS on the claim expiry (a stale tick
-  records nothing).
-- `record-retry-recheck --json '{task_id, decision}'` — routes the retry
-  protocol's in-lock content re-read; CAS on latest being `publish: dropped`.
-- `resolve-publish-unknown` — the manual one-shot for a single parked task
-  (unchanged; the audit-window contract, not the classifier).
-
-## Classifier (lib/classify-publish-absence.js)
-
-Decides, from the task's repo and the platform's on-disk state, whether the
-dropped edit is proven:
-
-- `verified` — the content IS present (the platform applied it; the receipt
-  was the only thing lost). Never re-issue.
-- `provably-dropped` — the old source is live AND the manifest shows no
-  build since the trigger. Only this decision may retry.
-- `applied-not-built` — the new source is live but no build ran (the
-  trigger reached the platform but the build didn't). Ambiguous outcome,
-  terminal: a retry would double-apply.
-- `ambiguous` — the content check is inconclusive. Never retry blind.
-- `deferred` — not yet quiesced; re-check next tick.
-- `superseded` — HEAD moved past the attempt's commit. Terminal.
-
-The classifier's verified path requires the CURRENT manifest to be a new
-build identity: `built_at` advanced past the trigger AND `content_sha256`
-differs from the pre-trigger baseline the workflow snapshots into the
-submitted ledger entry (design §1.9 — defeats a replayed manifest). When
-the baseline is unavailable the classifier falls back to the time-based
-advance check and notes it; the Step 4.5 verifier (`lib/verify-publish.js`)
-is the strict gate and fails closed without a baseline before stamping.
-Build-in-flight is checked twice bracketing the content read via manifest
-state change (no mtime heuristics), and the suite carries add-only and
-removal-only regression fixtures.
+# Publish-unknown recovery — RETIRED (0.14.6)
+
+The unknown-recovery machinery (the `publish: unknown-*` note state machine,
+`lib/classify-publish-absence.js`, `lib/retry-publish.js`,
+`lib/resolve-publish-unknown` flow) is RETIRED as of 0.14.6 (2026-09-20).
+
+It is subsumed by the version attempt loop: a 30-minute acknowledgement
+window per attempt, fresh per-attempt versions with immediate reissue (no
+backoff), a 2-hour total budget from first issuance, and `scan-ack-pending`
+as the sole verdict. There is no separate unknown state — silence within
+the window is unknown and fails closed; expiry re-issues with a fresh version;
+budget exhaustion parks `publish: version-timeout`.
+
+See `docs/publish-verification.md` for the current protocol.
+
+## Historical note
+
+The unknown path existed because the old two-party publish fired the
+artifact edit through a trigger child and got no receipt back — async was
+planned for, receipt-less was not. The one-party publish (2026-09-20,
+blocker 22) retired the trigger child: the workflow parks at intent, the
+session-carrying tick worker issues directly, and the ack scan attributes
+by exact version. The `publish: ambiguous`, `publish: retry-superseded`,
+`publish: retry-refused`, `publish: verified`, `publish: superseded`,
+`publish: verification-failed`, and `publish: intent-unverifiable` verbs
+remain in the vocabulary's legacy registry — the exact list in
+`lib/publish-note-vocabulary.js` (no wildcard families). Recognized so old
+note history skips as terminal, never written anew.