muse-crew 0.7.20 → 0.8.1

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). Owner is `space:<slug>`, so deleting the task service also removes the crons.
+- **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 — owner `cli:<instance-id>`, chosen once at first init — 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.
 
@@ -57,17 +57,21 @@ Dashboard arguments (optional as a pair — provide both or neither):
 - `dashboardSlug` — slug of the task service artifact (must already exist).
 - `dashboardRepoPath` — path to the dashboard's git repository (your local clone from the Prerequisites). Must be a real git repo inside the workspace. Init registers the dashboard project against this path and the crew's worktree lifecycle works from it — it is never the crew home, and init will never create it for you.
 
-Omit both dashboard arguments for a CLI-only install: init skips project registration (create projects later with `crew-api.js create-project`), and the polling cron is owned by `cli:<crew-home-basename>` instead of `space:<slug>`. The crew never requires a dashboard.
+Omit both dashboard arguments for a CLI-only install: init skips project registration (create projects later with `crew-api.js create-project`). The scheduler identity is the same in both modes — the crew never requires a dashboard, and attaching or removing one later never renames the crew's cron jobs.
 
 Optional arguments:
 - `dashboardName` — display name for the project registration (default: `"Muse Crew"`).
 - `crewName` — the human's chosen name for the crew. Stored as plain text at `$CREW_HOME/crew-name` and returned in the init summary. The setup conversation should always ask for one; init won't fail without it.
 - `cronIds` — manifest id → live id map for parallel instances on one account (default: `{}`). The manifest's ids are used as-is unless overridden, e.g. `{"crew-poll": "crew-poll-canary"}`.
-- `cronOwner` — explicit owner for the created cron jobs. Defaults to `space:<dashboardSlug>` in dashboard mode, `cli:<crew-home-basename>` in CLI-only mode.
+- `cronOwner` — explicit owner for the created cron jobs. Defaults to `cli:<instance-id>`: the instance id is chosen at first init (the crew-home basename) and kept from `.cron-registry.json` on re-runs, so re-init never renames the crew's jobs.
+- `autoUpdateCrew` — automatic crew upgrades on/off (default: `true`). Persists as the `auto_update_crew` config key; `false` turns the update watcher's crew check off.
+- `autoUpdateDashboard` — automatic dashboard upgrades on/off (default: `true`). Persists as the `auto_update_dashboard` config key.
+- `updateChannel` — `latest` (default) or `patch`: narrows crew upgrades to patch releases. Persists as the `update_channel` config key; any other value fails the init.
+- Re-init semantics for all four policy values: an explicit input wins; otherwise the existing config value is kept; the default applies only on first init — a re-init that passes no inputs never silently resurrects a deliberate opt-out.
 
 ### What init creates
 
-Init runs four phases, each idempotent — re-running converges anything that drifted and skips what already matches:
+Init runs five phases, each idempotent — re-running converges anything that drifted and skips what already matches:
 
 1. **Release** — copies `crew-release.sh` to `crewHome`, runs `init` to create the first release from the source directory. From a Git checkout, it extracts `workflows/` and `lib/` via `git archive` and uses the commit hash as the release identity. From an npm install, it copies the directories directly and uses the package version (e.g., `pkg-0.1.0`). Creates a release directory, sets the `current` symlink.
 
@@ -75,7 +79,9 @@ Init runs four phases, each idempotent — re-running converges anything that dr
 
 3. **Project registration** — registers the task service as a project in its own database via `createproject`, with `repo_path` set to the validated `dashboardRepoPath`. The dashboard becomes its own first project, so the crew can work on the dashboard itself. Re-running init is self-healing: a project already registered with the correct path is left alone, while one with a different path (e.g. from an older init) is repaired via `update-project`. Skipped entirely in CLI-only mode (no `dashboardSlug`) — create projects with `crew-api.js create-project` instead.
 
-4. **Crons** — reads the manifest at `seed/crons.json` and makes the scheduler match it: missing jobs are created from the entry (title, enabled, mode, schedule, owner, timeout_secs, and the body built from the entry's template with `crewHome` and the dashboard slug substituted in); existing jobs are viewed and converged — drifted fields are updated, unchanged jobs are left alone. One exception: init never touches `enabled` on an existing job. `enabled` is a creation-time default only — a disabled job is a deliberate human decision, and re-init must not silently resurrect it. Jobs removed from the manifest are left alone; deletion is a human decision.
+4. **Crons** — reads the manifest at `seed/crons.json` and makes the scheduler match it: missing jobs are created from the entry (title, enabled, mode, schedule, owner, timeout_secs, and the body built from the entry's template with `crewHome` substituted in); existing jobs are viewed and converged — drifted fields are updated, unchanged jobs are left alone. The scheduler identity (`instanceId`, `cli:<instanceId>` owner) is chosen once at first init and never renamed by re-runs: the instance id comes from the existing `.cron-registry.json` when present, otherwise the crew-home basename. One exception: init never touches `enabled` on an existing job. `enabled` is a creation-time default only — a disabled job is a deliberate human decision, and re-init must not silently resurrect it. Jobs removed from the manifest are left alone; deletion is a human decision.
+
+5. **Update policy** — persists the automatic-update policy (`auto_update_crew`, `auto_update_dashboard`, `update_channel`) via the Crew API's `update-config`, with the re-init semantics above: explicit inputs win, existing values survive, defaults apply only on first init. Seeds `$CREW_HOME/.update-watch.json` as `{}` only when it does not exist (the watcher's idempotency record is never overwritten).
 
 ### Verification
 
@@ -93,7 +99,9 @@ After init completes, it returns a summary:
   "project": "registered",
   "crons": [
     { "id": "crew-poll", "action": "created", "updated_fields": [] }
-  ]
+  ],
+  "autoUpdate": { "crew": true, "dashboard": true, "channel": "latest" },
+  "announcement": "Your crew and dashboard will update themselves automatically; say the word if you'd rather approve each one."
 }
 ```
 
@@ -188,7 +196,7 @@ Create a task using the `createtask` action (see the [API reference](../API.md))
 Required: `title`. Everything else has defaults.
 
 - `project` — which registered project this task belongs to.
-- `workflow` — `"standard"`, `"bugfix"`, `"chore"`, or `"docs"` (default: assigned at triage).
+- `workflow` — `"standard"`, `"bugfix"`, `"chore"`, `"docs"`, or `"upgrade"` (default: assigned at triage).
 - `state` — `"todo"` (ready for dispatch), `"parked"` (held back), `"in_progress"`, or `"done"`.
 - `priority` — `"high"`, `"normal"`, or `"low"`.
 - `deps` — array of task IDs that must complete first (blocked until all deps are done).
@@ -228,6 +236,8 @@ Every 15 minutes, the `crew-poll` cron fires:
 
 7. **Task completes** — when all phases finish, the dispatcher marks the task `done` on the next tick.
 
+Every tick also records its own release identity: right after acknowledging the poll, the dispatcher appends one line — `{"seq": <n>, "release": "<active release id>"}` — to `$CREW_HOME/.tick-releases.jsonl`. `release` is the active release (the basename of the crew home's `current` symlink, the same resolution the Crew API uses), and `seq` is the file's non-empty line count plus one; the file is append-only and never rewritten. Ordering is the proof, not timestamps — deliberately, since workflow scripts may not read the clock. For the self-upgrade proof, a tick whose line names the new release is demonstrably running the newly built code. A failed write never fails the tick: the writer swallows its own errors, carries no schema, and is wrapped in try/catch.
+
 ### Failure handling and retry
 
 A phase that fails doesn't fail the task — it fails the *session*, and the dispatcher retries the phase on the next tick. The retry state is explicit and dashboard-owned, never inferred from prose:
@@ -295,11 +305,40 @@ Configuration (per project, via the existing `getconfig` / `updateconfig` action
 | bugfix | Triage → Capture → Reproduce → Map → Build → Review → Integrate → Publish → QA |
 | chore | Triage → Capture → Map → Build → Review → Integrate → Publish |
 | docs | Triage → Write → Review |
+| upgrade | Triage → Deploy → Verify |
+
+### Upgrading the crew
+
+The crew upgrades itself through the normal dispatch loop. An upgrade task carries a `source:` line in its description naming where the new release comes from:
+
+- `source: repo` (default when absent) — deploys the task project's repo at its current HEAD. This is how you ship repo changes to your running crew: change the code, merge to main, then file an upgrade task pointing at that repo.
+- `source: npm@x.y.z` — installs the published `muse-crew` package at that exact version from the public npm registry. Use this to move the crew onto a known-good release — including one that predates the upgrade workflow itself.
+
+Both paths deploy through the stable `crew-release.sh` on persistent disk (never the release under upgrade), then verify mechanically: the live release equals the target, the release registry parses, and `crew-api get-state` works. Handover is automatic — the next polling tick launches the dispatcher from the new release through the `current` symlink. In-flight runs finish on the old release via the per-task lib pin, so an upgrade mid-flight does not break running work.
+
+Four ways to start an upgrade:
+
+1. **Dashboard** — file an upgrade task against your crew's project.
+2. **Manual crew** — create a task with `workflow: "upgrade"` in any project, with or without a `source:` line.
+3. **Self** — the crew can file its own upgrade task: any workflow's work agent can create one once it knows a newer release exists (release discovery is a future capability — `lib/update-watch.js`).
+4. **External npm** — file an upgrade task with `source: npm@x.y.z` to install a published version from the registry.
+
+Fail-closed rules: an upgrade never mutates the crew repo (repo source always means the repo's current HEAD, never a checkout or pull), never publishes to npm, never touches the scheduler or retries, and never rolls back automatically. A failed deploy parks the task with the exact deploy output; `crew-release.sh rollback` is the human recovery path. If the crew is already on the target release, the task completes as an idempotent no-op.
 
 ### The visual verdict
 
 For tasks that change anything rendered and visible in the project's artifact ("experiential" tasks), QA owns the visual verdict. Capture runs right after Triage to collect pre-change baseline evidence (parent-driven — see `docs/visual-verdict.md`); Map cannot be written without it; final QA covers mechanical checks only and the task does not complete until a `visual_verdict: PASS` is recorded. A FAIL reworks at Build within the shared budget; a `rendering impossible:` FAIL parks for human attention. Hazel judges against the artist-eye rubric (alignment, spacing, hierarchy, composition, balance, finish, taste) in `identities/hazel.md`, from rendered evidence only — never from prose descriptions.
 
+### Reproduce at the bug's layer
+
+Bugfix tasks reproduce at the layer where the bug lives — not always in the browser. During Triage, Sage classifies the bug's layer with a machine-read marker line (`layer: artifact`, `layer: engine`, or `layer: docs`):
+
+- **artifact** — user-facing behavior of the rendered artifact (something a user sees or clicks). Reproduced with the experiential see-act browser loop, as today.
+- **engine** — the crew's own machinery: workflows, lib scripts, shell scripts, tests, scheduler. Reproduced deterministically with shell commands in the repo checkout — run the failing script, re-run the failing test suite (`bash tests/run.sh`), query crew state via the API.
+- **docs** — a documentation gap or error. Reproduced by reading the file and confirming the gap is actually there.
+
+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
 
 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: after the build lands it parks with `publish: verification-requested <commit> (build <agent_id|agent_id unobserved>)`. "Landed" requires positive evidence (canary 2026-09-15, task `1d692d91`): the build poll must have positively observed our build — a running build with the receipt `agent_id`, or a completed-build record matching it. Absence of a running build is not evidence our build ran; an unobserved "done" is an unknown outcome, parked fail-closed with an append-only `unknown` ledger entry — never parked as verification-requested. The parent protocol owns the independent content confirmation (parent-driven — see `docs/publish-verification.md`); the park message records the observed builder build identifier as `(build <agent_id|agent_id unobserved>)`, and the parent correlates the read-back's live build agent_id against it — a mismatch logs `publish: build-mismatch <commit> …`, stays parked, and is never stamped (parent-driven — see `docs/publish-verification.md` step 4b). The independent read-back step is currently unavailable: `artifact_inspect` was removed by the platform (2026-09-14) and no agent-callable replacement exists (`artifact.inspect` is malfunction diagnosis, not a read-back tool), so the parent cannot confirm content independently and tasks stay parked at verification-requested until a read-back path exists. QA's provenance check then enforces the stamp mechanically, so an unverified publish fails loudly in QA instead of passing silently.
@@ -418,6 +457,139 @@ Each release is identified by its source: a full Git commit hash for Git checkou
 crew-release.sh current
 ```
 
+### Automatic updates
+
+A daily deterministic script (`lib/update-watch.js`, run by the
+`crew-update-watch` cron) watches for new releases and files upgrade tasks
+through the normal loop — it never deploys, never touches the artifact,
+never mutates config. The loop applies.
+
+- **Crew:** the public npm registry (`npm view muse-crew version`, pinned to
+  `https://registry.npmjs.org/`) vs the live release (`crew-release.sh
+  current`). If a newer version is published and the policy/channel allow,
+  the watcher files a `workflow: "upgrade"` task with `source: npm@<version>`.
+  Non-npm releases (git-hash dev builds) are skipped — they cannot be
+  compared to registry versions.
+- **Dashboard:** `git ls-remote origin HEAD` on the first
+  `deploy_type=artifact` project vs the recorded sha in
+  `$CREW_HOME/.update-watch.json`. If the origin has a new ref, the watcher
+  files a `workflow: "chore"` task carrying the mechanical dashboard-upgrade
+  journey (fetch, ancestor check, review, let Publish carry the artifact update).
+
+#### Dashboard compatibility anchor (.crew-version)
+
+A dashboard release declares the crew version it needs in a `.crew-version`
+file at the repo root — one line, an exact version (`0.7.21`, strict semver,
+no ranges). Bump it in the same commit as any change that needs a new crew.
+The file is added on the dashboard-repo side at release time; the watcher
+only honors it.
+
+The watcher reads the declaration at the filed ref (`git fetch origin`, then
+`git show <sha>:.crew-version` — never the local working tree, which still
+sits at the recorded sha while a newer ref is being evaluated) and treats
+(dashboard ref, crew version) as one unit, ordered dashboard-led:
+
+- Declared crew newer than the running release: the crew upgrade task
+  (`workflow: "upgrade"`, `source: npm@<declared>`, `filed_by:
+  update-watch`) is filed first, and the dashboard task notes that it follows
+  the crew upgrade (old→new dashboard commits plus the required crew
+  version). The declaration is a requirement, not a preference: it bypasses
+  `update_channel`, but not the `auto_update_crew=false` opt-out — with the
+  opt-out, only the dashboard task is filed, noting the required version for
+  a human.
+  If the crew upgrade task cannot be filed (no `muse-crew` project
+  registered, or `create-task` fails): the whole dashboard leg is held —
+  nothing is filed, the old dashboard sha stays in the state file, and the
+  ref is re-evaluated on the next run, so the (dashboard ref, crew version)
+  unit is never ordered half-way.
+- Declared crew equal to the running release: the dashboard task is filed as
+  today, no crew task.
+- Declared crew older than the running release: the dashboard leg is skipped
+  and logged — a downgrade is a human decision, never automatic. State is
+  left untouched.
+- Missing, unreadable, or invalid file: silent with a log line, and the
+  dashboard leg proceeds as today. Updates are never blocked on a missing
+  declaration.
+
+**Policy** (crew config, set at setup, changeable later via the Crew API's
+`update-config`):
+
+- `auto_update_crew` — default `true`. `false` turns the crew check off.
+- `auto_update_dashboard` — default `true`. `false` turns the dashboard check off.
+- `update_channel` — `latest` (default) or `patch` (crew upgrades only for
+  patch releases). Any other value is logged and treated as `latest`.
+
+Setup announces the default with a one-word opt-out: "Your crew and
+dashboard will update themselves automatically; say the word if you'd
+rather approve each one." Opting out is a re-run with
+`autoUpdateCrew: false` / `autoUpdateDashboard: false`; a re-init that
+passes no inputs never resurrects a deliberate opt-out.
+
+**Trust anchors:**
+
+- Publisher + registry trust = install trust. The watcher adds no new
+  trust: it watches the same public registry the install came from.
+- The upgrade workflow's Verify phase is the real gate — nothing deploys
+  without it.
+- Fail-closed + retained rollback: a bad upgrade parks; `crew-release.sh
+  rollback` is the human recovery path.
+- Capability split: the watcher reaches the network but can never deploy —
+  it only files tasks. The deployer never reaches the network beyond the
+  package install the task explicitly names.
+
+**Idempotency:** `$CREW_HOME/.update-watch.json` records the last filed crew
+version and per-project dashboard sha (recorded at file time, so a parked
+upgrade stays visible in the loop instead of being silently re-filed).
+Check failures (npm unreachable, `ls-remote` auth friction) are silent with
+a log line in `$CREW_HOME/update-watch.log` — the script always exits 0 so
+a failed check never breaks the loop.
+
+## npm releases
+
+The npm Publish phase (`lib/publish-npm.sh`) releases the crew to the
+registry as `muse-crew@<target-version>`: it writes the workflow-computed
+target version into `package.json`, commits it, packs a tarball, publishes
+via the publish helper, verifies against the registry, pushes, and
+finalizes.
+
+### What the publish path needs
+
+Two things, both machine-local:
+
+1. **The publish helper** — `NPM_PUBLISH_PY`, defaulting to
+   `$HOME/workspace/skills/npm/bin/npm-publish.py`. The script invokes it
+   as `python3 <helper> <tarball>`; it only needs to be a readable file
+   (the executable bit is irrelevant).
+2. **The `custom.npm` credential** — the npm publish token in the secure
+   vault, under exactly that name. The helper probes it with
+   `python3 <helper> --check`, which reports presence/absence only and
+   never prints credential material.
+
+### How to configure it
+
+- Point `NPM_PUBLISH_PY` at your own helper (any script that takes a
+  tarball path, and optionally `--check` for the credential probe).
+- Store the publish token as `custom.npm` in the secure vault.
+
+A helper that predates `--check` still works: the probe's failure is
+treated as "unknown", not "absent", and the publish runs with today's
+fail-closed behavior.
+
+### What the skip means
+
+When the helper or the credential is absent, the preflight (which runs
+before any mutation — before the version write, the commit, the tarball)
+skips gracefully and the Publish agent reports:
+
+```
+PUBLISH_SKIPPED=no-npm-publish
+```
+
+This is a designed outcome, not a failure. The merge stands, the version
+was not cut, nothing was shipped — and the task completes normally. There
+is no retry and nothing to park: a missing credential is configuration,
+not a transient error, so one probe and one skip is the whole story.
+
 ## Current limitations
 
 1. **No global kill switch.** Only per-project pause/resume exists. Setting global `config.simultaneity` to 0 does not override projects with explicit nonzero values. A global stop requires pausing each project individually.

package/lib/AGENTS.md

@@ -7,7 +7,7 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `schema.sql` — the crew-owned state schema: projects, tasks, poll_state, config, agent_sessions, events. Vocabularies enforced by CHECK constraints; `rejected` is a valid event type (the 2026-09-11 crash was a stored session whose event was rejected). Column names match the historical dashboard tables for a verbatim migration.
 - `crew-release.sh` — immutable release manager: deploy, rollback, prune
 - `merge-lock.sh` — serialized merge lock for concurrent agents: time-based holder lease (bug 2fc8f52f — an unexpired lease is held regardless of process liveness; only an expired lease may be broken). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset). Lock file is key=value: task_id, opaque holder identity (never a PID), acquired_at epoch, lease_seconds (default 600, override via MERGE_LOCK_LEASE_SECONDS). acquire/refresh/release/status/force-release; holder-only refresh and release; every op appends to $CREW_HOME/.merge-lock.log
-- `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/verify-merge/status/post-deploy/terminal-cleanup/refresh-lock/lock-status over git worktrees (`integrate` reconciles `origin/main` under the merge lock after the task merge — canary `a6d8b0c8`, 2026-09-11 — so the push is a fast-forward; fail-soft with no remote, fail closed on conflict) (`.worktrees/<id>`, branch `task/<id>`). The crew registry (`<repo>/.worktrees/.registry/<id>`) is the source of truth for task→branch/path — never reconstruct it from git state. Prepare fails closed on dirty `main`; cleanup is forgiving. `terminal-cleanup` is the run's last act at every park/fail boundary (called from `parkTask` in standard/bugfix/chore): releases the merge lock unconditionally and reclaims the worktree+branch only when the task branch is fully merged into main — unmerged work is preserved for the human by design, and a dirty worktree is reported, never force-removed. `post-deploy` reports worktree removal honestly (a lying "removed" echo hid real leftovers — canary run 9, 2026-09-12). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset); `CREW_REPO` is exported so internal merge-lock.sh calls inherit the repo being worked on; `LIB_DIR` defaults to `$CREW_HOME/lib` (`CREW_LIB` override). `lock-status` reports the merge-lock state explicitly (`UNLOCKED`, or key=value: locked=true, task_id, holder, acquired_at, lease_seconds, age_seconds, remaining_seconds — always exit 0) so Publish can distinguish an empty-diff Integrate (no lock taken) from a refresh failure.
+- `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/verify-merge/status/post-deploy/terminal-cleanup/refresh-lock/lock-status over git worktrees (`integrate` reconciles `origin/main` under the merge lock after the task merge — canary `a6d8b0c8`, 2026-09-11 — so the push is a fast-forward; fail-soft with no remote, fail closed on conflict) (`.worktrees/<id>`, branch `task/<id>`). Branch resolution order: the crew registry (`<repo>/.worktrees/.registry/<id>`), then the canonical `task/<full-id>` ref, then a `task/<id-prefix>` ref matched by strict prefix enumeration (task 4e1a1bba — a Build agent may create the branch with raw git from an abbreviated id, bypassing prepare; prefix names are tolerated, never created; ambiguous prefixes fail closed). `resolve-branch` prints the resolved branch for agent-side one-liners. Nothing reconstructs the branch name — every command resolves it. Prepare fails closed on dirty `main`; cleanup is forgiving. `terminal-cleanup` is the run's last act at every park/fail boundary (called from `parkTask` in standard/bugfix/chore): releases the merge lock unconditionally and reclaims the worktree+branch only when the task branch is fully merged into main — unmerged work is preserved for the human by design, and a dirty worktree is reported, never force-removed. `post-deploy` reports worktree removal honestly (a lying "removed" echo hid real leftovers — canary run 9, 2026-09-12). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset); `CREW_REPO` is exported so internal merge-lock.sh calls inherit the repo being worked on; `LIB_DIR` defaults to `$CREW_HOME/lib` (`CREW_LIB` override). `lock-status` reports the merge-lock state explicitly (`UNLOCKED`, or key=value: locked=true, task_id, holder, acquired_at, lease_seconds, age_seconds, remaining_seconds — always exit 0) so Publish can distinguish an empty-diff Integrate (no lock taken) from a refresh failure.
 - `test-worktree-backend.sh` — regression tests for the lifecycle script (validate, prepare/reuse, inspect, status, cleanup, idempotent cleanup, dirty-main preflight, integrate remote-reconcile with fixture sensitivity + no-remote fail-soft) on scratch repos
 - `test-version-write.sh` — regression tests for the escape-preserving step-8 version write in publish-npm.sh (fixture: current package.json with the \\u2014 escape; extracts the shipped block by anchor)
 - `test-publish-verify.sh` — regression tests for the retry-tolerant step-12 verification in publish-npm.sh (canary 5a027278): extracts the shipped block by anchor and runs it against a fake npm whose read replica lags (non-zero exits, then the old version, then the target) — requires convergence on success, fail-closed `PUBLISH_FAILED=verify` on exhaustion, and `--prefer-online` on every read
@@ -25,3 +25,4 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `readback-disk.js` — deterministic publish content sensor (2026-09-16): reads the on-disk tree the artifact is built/served from and emits the machine-readable findings block (`FILE:`/`ADDED:`/`REMOVED:`/`END_FILE`) that `verify-publish.js` judges. The primary sensor — the LLM-inspector path (`build-readback-request.js`) is manual-fallback only since `artifact_inspect` was removed by the platform 2026-09-14.
 - `build-readback-request.js` — builds the LLM-inspector read-back `verbatim_request` from the merge commit's diff (2026-09-14): carries the merged diff as the expected change and asks for an independent read of the artifact's actual source. Retained as the manual fallback; the deterministic `readback-disk.js` is the primary sensor.
 - `verify-publish.js` — mechanical publish verification judge (2026-09-14/16): certifies the read-back findings block against `git diff` (strict `FILE:`/`ADDED:`/`REMOVED:`/`END_FILE` parsing, every added line PRESENT / every removed line ABSENT, HEAD==commit supersession check) and only then stamps provenance. Binary files, mode-only changes, and fully-colliding added hunks fail closed as `unverifiable-content` (2026-09-16, critic findings 1/5) — they can never vacuously stamp. Content-mismatch, unreadable-result, superseded, and stamp failures exit 1 with `publish: verification-failed` and no stamp. Collision exemption (2026-09-15): a removed line occurring in the old tree strictly more times than the diff removes is exempt from ABSENT (zero discriminating power); computed from `git show <base>:<path>`, never the working tree.
+- `update-watch.js` — deterministic automatic update watcher (2026-09-16, zero deps): `node update-watch.js --crew-home <path>` (missing arg → usage, exit 2; every other path exits 0). Watches the public npm registry (`npm view muse-crew version` pinned to `https://registry.npmjs.org/`) vs `crew-release.sh current` and files a `workflow: "upgrade"` task with `source: npm@<version>` when policy (`auto_update_crew`, `update_channel`) and channel gating allow; watches `git ls-remote origin HEAD` on the first `deploy_type=artifact` project vs `$CREW_HOME/.update-watch.json` and files a `workflow: "chore"` task carrying the mechanical dashboard-upgrade journey. Reads the `.crew-version` compatibility anchor at the new ref via `git fetch` + `git show <sha>:.crew-version` (never the working tree) and orders dashboard-led: a declared newer crew files the crew upgrade task FIRST and the dashboard task notes it follows the crew upgrade (declaration bypasses `update_channel`, not the `auto_update_crew=false` opt-out); a declared older crew skips the dashboard leg entirely as a human decision; a missing/invalid/unfetchable anchor fails open to the dashboard leg as today. Idempotency via the same state file (records at file time); check failures log to `$CREW_HOME/update-watch.log` and are never thrown. Safety: only files tasks — never deploys, never touches the artifact/config/scheduler. Run by the daily `crew-update-watch` cron through the `current` symlink (latest release); deliberately NOT in the lib-pinning `PIN_BASENAMES`.

package/lib/build-registry.js

@@ -2,7 +2,8 @@
 // build-registry.js — deterministic extraction of the workflow step registry.
 //
 // The workflow files (workflows/standard.js, workflows/bugfix.js,
-// workflows/chore.js, workflows/docs.js) are the single source of truth.
+// workflows/chore.js, workflows/docs.js, workflows/upgrade.js) are the
+// single source of truth.
 // This script generates workflows/registry.json at release time (invoked by
 // crew-release.sh cmd_deploy). The JSON is a build artifact and must never be
 // hand-edited — publish a new release instead.
@@ -14,7 +15,7 @@ const fs = require("fs");
 const path = require("path");
 const vm = require("vm");
 
-const WORKFLOWS = ["standard", "bugfix", "chore", "docs"];
+const WORKFLOWS = ["standard", "bugfix", "chore", "docs", "upgrade"];
 
 function fail(msg) {
   process.stderr.write("build-registry: " + msg + "\n");

package/lib/publish-npm.sh

@@ -27,6 +27,10 @@
 # When no merge lock is held (empty-diff Integrate), the publish path is
 # skipped gracefully: PUBLISH_SKIPPED=no-lock-held is printed, no version
 # is written or published, and PUBLISH_COMPLETE is omitted.
+# When npm publish is not configured on this machine (publish helper or
+# credential absent), the preflight skips gracefully before any mutation:
+# PUBLISH_SKIPPED=no-npm-publish is printed, no version is written or
+# published, and PUBLISH_COMPLETE is omitted (see docs/guide.md#npm-releases).
 
 set -euo pipefail
 
@@ -49,6 +53,35 @@ echo "PUBLISH_TARGET=$TARGET_VERSION"
 git -C "$REPO_PATH" rev-parse --git-dir >/dev/null 2>&1 \
   || fail "env" "REPO_PATH is not a git checkout: $REPO_PATH"
 
+# PREFLIGHT-ANCHOR: publish capability preflight (runs before ANY mutation).
+# publish-npm.sh assumed the author-machine publish helper path and failed
+# cryptically AFTER the version-bump commit when npm publish was not
+# configured, leaving a release commit for a version that never shipped.
+# Probe first: when the helper or the publish credential is absent, skip
+# cleanly with PUBLISH_SKIPPED=no-npm-publish — no commit, no tarball,
+# nothing mutated. Checks -f/-r only: the helper is invoked as
+# `python3 <path>`, so the executable bit is irrelevant (requiring it would
+# false-skip on files that are rw-rw----). An old helper that does not know
+# --check (nonzero exit without a CREDENTIAL_* marker) is "unknown", not
+# "absent": fall through to today's fail-closed behavior at step 11.
+# Placed before DRY_RUN on purpose: a dry run on an unconfigured machine
+# honestly reports "would skip". No wall-clock, no randomness, no new env
+# vars — the determinism scan stays clean. Never prints credential material.
+if ! [ -f "$NPM_PUBLISH_PY" ] || ! [ -r "$NPM_PUBLISH_PY" ]; then
+  echo "PUBLISH_SKIPPED=no-npm-publish"
+  echo "npm publish not configured on this machine — see docs/guide.md#npm-releases; code changes are merged, nothing was versioned or published"
+  exit 0
+fi
+PREFLIGHT_CHECK_CODE=0
+PREFLIGHT_CHECK_OUT="$(python3 "$NPM_PUBLISH_PY" --check 2>&1)" || PREFLIGHT_CHECK_CODE=$?
+if [ "$PREFLIGHT_CHECK_CODE" -ne 0 ] \
+   && printf '%s' "$PREFLIGHT_CHECK_OUT" | grep -q 'CREDENTIAL_MISSING=custom.npm'; then
+  echo "PUBLISH_SKIPPED=no-npm-publish"
+  echo "npm publish not configured on this machine — see docs/guide.md#npm-releases; code changes are merged, nothing was versioned or published"
+  exit 0
+fi
+# PREFLIGHT-END
+
 # 3. Dry run: markers only, no lock, no deploy, no mutation.
 if [ "${DRY_RUN:-0}" = "1" ]; then
   echo "PUBLISH_DRY_RUN=1"
@@ -179,7 +212,13 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
 
     # 11. Publish. "previously published versions" means a retried Publish
     # already landed this version (the merge lock guarantees no other task
-    # picked it) — continue. Any other failure is fatal.
+    # picked it) — continue. A "staged version" 409 means npm accepted the
+    # publish but staged it: the PUT returned 2xx yet the version is
+    # invisible in the packument until it finalizes (~7 min observed
+    # 2026-09-17). Never re-PUT a staged version — the registry rejects it
+    # and the re-PUT proves nothing. Poll the registry at step 12 until it
+    # finalizes or the budget exhausts (fail closed). Any other failure is
+    # fatal.
     if PUB_OUT="$(python3 "$NPM_PUBLISH_PY" "$TGZ" 2>&1)"; then
       echo "PUBLISHED=$TARGET_VERSION"
     else
@@ -187,6 +226,10 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
         *"previously published versions"*)
           echo "PUBLISHED_ALREADY=$TARGET_VERSION"
           ;;
+        *"staged version"*)
+          echo "PUBLISHED_STAGED=$TARGET_VERSION"
+          echo "publish staged by registry — polling for visibility, not re-PUTting"
+          ;;
         *)
           rm -f "$TGZ"
           fail "publish" "$(printf '%s\n' "$PUB_OUT" | tail -5)"
@@ -198,12 +241,20 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
     # 12. Verify: ground truth is the registry, not any agent's summary.
     # The registry is eventually consistent: a publish followed by an
     # immediate read can observe the pre-publish version (canary 5a027278
-    # hit a stale read replica ~6s after publish). A single stale read must
-    # never park a landed publish, so this block retries with backoff and
-    # client cache-busting instead of failing on the first mismatch.
+    # hit a stale read replica ~6s after publish). Worse, npm may STAGE a
+    # publish: the PUT returns 2xx but the version stays invisible in the
+    # packument until it finalizes (~7 min observed 2026-09-17) — a
+    # re-PUT then 409s as "previously staged". A short budget would park
+    # a landed publish, so the default budget covers staged finalization
+    # with headroom (30 x 30s = 15 min, still bounded). A single stale
+    # read must never park a landed publish, so this block retries with
+    # backoff and client cache-busting instead of failing on the first
+    # mismatch. Budget exhaustion fails closed: a publish that never
+    # becomes visible is not claimed — a human with 2FA investigates
+    # (e.g. `npm stage approve`) and the version is never re-PUT blind.
     # STEP-12-ANCHOR: publish verification (retry-tolerant)
-    VERIFY_ATTEMPTS="${VERIFY_ATTEMPTS:-12}"
-    VERIFY_SLEEP_SECS="${VERIFY_SLEEP_SECS:-10}"
+    VERIFY_ATTEMPTS="${VERIFY_ATTEMPTS:-30}"
+    VERIFY_SLEEP_SECS="${VERIFY_SLEEP_SECS:-30}"
     REG=""
     for attempt in $(seq 1 "$VERIFY_ATTEMPTS"); do
       # --prefer-online busts npm's client-side packument cache; the retry

package/lib/test-publish-preflight.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# test-publish-preflight.sh — regression tests for the npm publish
+# capability preflight (bugfix 2026-09-17): publish-npm.sh assumed the
+# author-machine publish helper path and failed cryptically AFTER the
+# version-bump release commit when npm publish was not configured.
+#
+# Covers:
+#   - structural: the PREFLIGHT block exists in lib/publish-npm.sh
+#     (extracted by anchor), sits after env validation and before the
+#     DRY_RUN block, checks the helper with -f/-r only (never -x — the
+#     helper is invoked as `python3 <path>`), and reads no wall clock or
+#     randomness.
+#   - full-script runs against a scratch repo:
+#       * NPM_PUBLISH_PY missing -> PUBLISH_SKIPPED=no-npm-publish + the
+#         actionable line, exit 0, HEAD unchanged, status clean, no tarball
+#       * fake helper whose --check reports CREDENTIAL_MISSING=custom.npm
+#         (exit 1) -> same skip outcome, exit 0, repo untouched
+#       * fake helper whose --check reports CREDENTIAL_OK=custom.npm
+#         (exit 0) with DRY_RUN=1 -> preflight passes through to
+#         PUBLISH_DRY_RUN=1 (asserts pass-through, not the mutation)
+#       * old helper that does not know --check (usage to stderr, exit 1,
+#         no CREDENTIAL markers) with DRY_RUN=1 -> no skip (fall-through
+#         preserved: unknown is not absent)
+#   - --check probe unit test against the real helper: on the author
+#     machine this expects exit 0 and exactly CREDENTIAL_OK=custom.npm.
+#     NOTE: this case depends on the `custom.npm` credential existing in
+#     the secure vault — on a machine without it the probe correctly
+#     reports CREDENTIAL_MISSING=custom.npm (exit 1) and this case fails.
+#     That is expected outside the author machine, not a regression.
+#   - bash -n syntax check on publish-npm.sh
+#
+# Anchors: `# PREFLIGHT-ANCHOR` ... `# PREFLIGHT-END` in lib/publish-npm.sh.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PUBLISH="$SCRIPT_DIR/publish-npm.sh"
+REAL_HELPER="$HOME/workspace/skills/npm/bin/npm-publish.py"
+
+pass=0
+fail_count=0
+ok() { echo "PASS: $1"; pass=$((pass + 1)); }
+no() { echo "FAIL: $1"; fail_count=$((fail_count + 1)); }
+
+TMPBASE="$(mktemp -d)"
+trap 'rm -rf "$TMPBASE"' EXIT
+
+# --- Scratch repo (Publish's REPO_PATH must be a git checkout) ---
+SCRATCH="$TMPBASE/repo"
+git init -q -b main "$SCRATCH"
+git -C "$SCRATCH" config user.email "test@crew"
+git -C "$SCRATCH" config user.name "crew-test"
+echo x > "$SCRATCH/f.txt"
+git -C "$SCRATCH" add -A && git -C "$SCRATCH" commit -qm init
+
+# --- Fake helpers ---
+cat > "$TMPBASE/helper-ok.py" <<'EOF'
+#!/usr/bin/env python3
+import sys
+if len(sys.argv) == 2 and sys.argv[1] == "--check":
+    print("CREDENTIAL_OK=custom.npm")
+    sys.exit(0)
+sys.exit(1)
+EOF
+cat > "$TMPBASE/helper-missing-cred.py" <<'EOF'
+#!/usr/bin/env python3
+import sys
+if len(sys.argv) == 2 and sys.argv[1] == "--check":
+    print("CREDENTIAL_MISSING=custom.npm")
+    sys.exit(1)
+sys.exit(1)
+EOF
+# An old helper that predates --check: usage to stderr, exit 1, no markers.
+cat > "$TMPBASE/helper-old.py" <<'EOF'
+#!/usr/bin/env python3
+import sys
+print("Usage: helper-old.py <tarball-path>", file=sys.stderr)
+sys.exit(1)
+EOF
+
+ACTIONABLE="npm publish not configured on this machine — see docs/guide.md#npm-releases; code changes are merged, nothing was versioned or published"
+
+# --- Structural: extract the shipped preflight block by anchor ---
+BLOCK="$TMPBASE/preflight.sh"
+sed -n '/# PREFLIGHT-ANCHOR/,/# PREFLIGHT-END/p' "$PUBLISH" > "$BLOCK"
+if grep -q 'PUBLISH_SKIPPED=no-npm-publish' "$BLOCK" \
+   && grep -q 'docs/guide.md#npm-releases' "$BLOCK" \
+   && grep -q 'exit 0' "$BLOCK"; then
+  ok "extracted PREFLIGHT block from publish-npm.sh"
+else
+  no "PREFLIGHT extraction failed (anchors missing)"
+fi
+
+# The helper is invoked as `python3 <path>`: -f/-r, never -x.
+if grep -q '\[ -f "\$NPM_PUBLISH_PY" \]' "$BLOCK" \
+   && grep -q '\[ -r "\$NPM_PUBLISH_PY" \]' "$BLOCK" \
+   && ! grep -q '\[ -x "\$NPM_PUBLISH_PY" \]' "$BLOCK"; then
+  ok "preflight checks -f/-r on the helper, never -x"
+else
+  no "preflight helper checks wrong (want -f/-r, no -x)"
+fi
+
+# No wall-clock or randomness in the preflight block.
+if ! grep -Eq '\$\(date|date \+|\$RANDOM' "$BLOCK"; then
+  ok "preflight block reads no wall clock and no randomness"
+else
+  no "preflight block contains clock/randomness"
+fi
+
+# Placement: after env validation, before the DRY_RUN block.
+VALIDATE_LINE="$(grep -n 'rev-parse --git-dir' "$PUBLISH" | head -1 | cut -d: -f1)"
+ANCHOR_LINE="$(grep -n '# PREFLIGHT-ANCHOR' "$PUBLISH" | head -1 | cut -d: -f1)"
+END_LINE="$(grep -n '# PREFLIGHT-END' "$PUBLISH" | head -1 | cut -d: -f1)"
+DRYRUN_LINE="$(grep -n 'DRY_RUN:-0}' "$PUBLISH" | head -1 | cut -d: -f1)"
+if [ -n "$VALIDATE_LINE" ] && [ -n "$ANCHOR_LINE" ] && [ -n "$END_LINE" ] \
+   && [ -n "$DRYRUN_LINE" ] \
+   && [ "$VALIDATE_LINE" -lt "$ANCHOR_LINE" ] \
+   && [ "$END_LINE" -lt "$DRYRUN_LINE" ]; then
+  ok "PREFLIGHT block sits after env validation, before DRY_RUN"
+else
+  no "PREFLIGHT placement wrong (validate=$VALIDATE_LINE anchor=$ANCHOR_LINE end=$END_LINE dryrun=$DRYRUN_LINE)"
+fi
+
+# Runner: full publish-npm.sh against the scratch repo. The preflight exits
+# before any mutation, so the repo needs no package.json.
+run_full() { # run_full <helper_path> [extra_env...]
+  local helper="$1"; shift
+  local run="$TMPBASE/run-$RANDOM"
+  mkdir -p "$run"
+  (
+    export TASK_ID="preflight-test" REPO_PATH="$SCRATCH" PKG="muse-crew" TARGET_VERSION="9.9.9"
+    export NPM_PUBLISH_PY="$helper"
+    # A bare `export` (empty "$@") would dump the environment to stdout and
+    # corrupt the captured run path — only export when extras are given.
+    if [ $# -gt 0 ]; then export "$@"; fi
+    bash "$PUBLISH" > "$run/out" 2>&1
+  )
+  local code=$?
+  echo "$code" > "$run/code"
+  echo "$run"
+}
+
+repo_state() { # prints "HEAD=<sha> STATUS=<porcelain-lines> TGZ=<count>"
+  local head status tgz
+  head="$(git -C "$SCRATCH" rev-parse HEAD)"
+  status="$(git -C "$SCRATCH" status --porcelain | wc -l)"
+  tgz="$(find "$SCRATCH" -maxdepth 1 -name '*.tgz' | wc -l)"
+  echo "HEAD=$head STATUS=$status TGZ=$tgz"
+}
+
+# --- Case 1: helper missing -> clean skip, exit 0, repo untouched ---
+BEFORE="$(repo_state)"
+RUN="$(run_full /nonexistent/path.py)"
+CODE="$(cat "$RUN/code")"; OUT="$(cat "$RUN/out")"; AFTER="$(repo_state)"
+if [ "$CODE" -eq 0 ] && [[ "$OUT" == *"PUBLISH_SKIPPED=no-npm-publish"* ]] \
+   && [[ "$OUT" == *"$ACTIONABLE"* ]] \
+   && [[ "$OUT" != *"PUBLISH_FAILED"* ]] && [[ "$OUT" != *"PUBLISH_COMPLETE"* ]] \
+   && [ "$BEFORE" = "$AFTER" ]; then
+  ok "helper missing: skips with marker + actionable line, exit 0, repo untouched"
+else
+  no "helper missing: code=$CODE state=$BEFORE/$AFTER out='$OUT'"
+fi
+
+# --- Case 2: helper present, credential missing -> same skip, repo untouched ---
+BEFORE="$(repo_state)"
+RUN="$(run_full "$TMPBASE/helper-missing-cred.py")"
+CODE="$(cat "$RUN/code")"; OUT="$(cat "$RUN/out")"; AFTER="$(repo_state)"
+if [ "$CODE" -eq 0 ] && [[ "$OUT" == *"PUBLISH_SKIPPED=no-npm-publish"* ]] \
+   && [[ "$OUT" == *"$ACTIONABLE"* ]] \
+   && [[ "$OUT" != *"PUBLISH_FAILED"* ]] && [[ "$OUT" != *"PUBLISH_COMPLETE"* ]] \
+   && [ "$BEFORE" = "$AFTER" ]; then
+  ok "credential missing: skips with marker + actionable line, exit 0, repo untouched"
+else
+  no "credential missing: code=$CODE state=$BEFORE/$AFTER out='$OUT'"
+fi
+
+# --- Case 3: credential present + DRY_RUN=1 -> preflight passes through ---
+RUN="$(run_full "$TMPBASE/helper-ok.py" DRY_RUN=1)"
+CODE="$(cat "$RUN/code")"; OUT="$(cat "$RUN/out")"
+if [ "$CODE" -eq 0 ] && [[ "$OUT" == *"PUBLISH_DRY_RUN=1"* ]] \
+   && [[ "$OUT" != *"PUBLISH_SKIPPED"* ]]; then
+  ok "credential present: preflight passes through to PUBLISH_DRY_RUN=1"
+else
+  no "credential present: code=$CODE out='$OUT'"
+fi
+
+# --- Case 4: old helper without --check -> no skip (fall-through) ---
+RUN="$(run_full "$TMPBASE/helper-old.py" DRY_RUN=1)"
+CODE="$(cat "$RUN/code")"; OUT="$(cat "$RUN/out")"
+if [ "$CODE" -eq 0 ] && [[ "$OUT" == *"PUBLISH_DRY_RUN=1"* ]] \
+   && [[ "$OUT" != *"PUBLISH_SKIPPED"* ]]; then
+  ok "old helper (no --check): unknown, not absent — falls through, no skip"
+else
+  no "old helper: code=$CODE out='$OUT'"
+fi
+
+# --- Case 5: real helper --check probe (author machine: credential present) ---
+CHECK_OUT="$(python3 "$REAL_HELPER" --check 2>&1)"
+CHECK_CODE=$?
+if [ "$CHECK_CODE" -eq 0 ] && [ "$CHECK_OUT" = "CREDENTIAL_OK=custom.npm" ]; then
+  ok "real helper --check: CREDENTIAL_OK=custom.npm, exit 0, nothing else printed"
+else
+  no "real helper --check: code=$CHECK_CODE out='$CHECK_OUT' (expected CREDENTIAL_OK=custom.npm — this case is credential-dependent; see header)"
+fi
+
+bash -n "$PUBLISH" && ok "publish-npm.sh syntax OK" || no "publish-npm.sh syntax"
+
+echo ""
+echo "$pass passed, $fail_count failed"
+exit $((fail_count > 0))