muse-crew 0.6.6 → 0.6.8

package/AGENTS.md

@@ -5,7 +5,7 @@ Muse Crew source repository. The repo is the product; the personal instance (`$C
 ## Structure
 
 - `API.md` — the Crew API contract: every action a task service must implement
-- `.orchestration/` — crew configuration notes (deploy config lives in the dashboard's project record — the single source of truth)
+- `.orchestration/` — crew configuration notes (deploy config lives in the crew's project record — the single source of truth, read via the Crew API)
 - `identities/` — crew member character files and portraits
 - `lib/` — shell scripts for release, merge, worktree, and cleanup
 - `personas/` — QA perspective costumes for Hazel

package/API.md

@@ -2,7 +2,7 @@
 
 The contract between Muse Crew and any task service implementation. The dispatcher and task workflows call these actions. A conforming task service must implement all of them.
 
-The current implementation is the `orchestra-dashboard` web artifact.
+The crew owns its state. The reference implementation is `lib/crew-api.js` — a Node CLI backed by SQLite at `$CREW_HOME/crew-state.db`. The dashboard is a pure client of this API; it never owns crew state.
 
 ---
 
@@ -101,6 +101,16 @@ Create or update an agent session record. Sessions track which identity is worki
 | `failure_reason` | string (≤ 3000) or null | no | |
 | `caveats` | array of `{text, severity}` | no | |
 
+### `heartbeat-session`
+
+Update the `last_heartbeat` timestamp for a running session. Workflows call this periodically during long phases to signal liveness and prevent the zombie sweep from marking the session as `timed_out`. The sweep (in `getdispatchstate`) marks a `running` session as `timed_out` only if its `last_heartbeat` (or `started_at` for pre-migration sessions) is older than one hour.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | uuid | yes | Session ID; must be `running` |
+
+Returns the updated session. Fails with `not_found` if the session does not exist, `conflict` if the session is not `running`.
+
 ---
 
 ## Events
@@ -111,7 +121,7 @@ Log an event to the activity timeline.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `type` | `dispatched` · `completed` · `failed` · `blocked` · `created` · `note` · `release_activated` · `deployed` | yes | |
+| `type` | `dispatched` · `completed` · `failed` · `blocked` · `created` · `note` · `release_activated` · `deployed` · `rejected` | yes | `rejected` records a Review/QA rejection as an event, the same word the workflow stores as the session's `status` — one vocabulary for both, so a rejection can never store the session but fail the event (canary 2026-09-11). |
 | `message` | string (1–1000) | yes | |
 | `task_id` | uuid or null | no | Associate with a specific task |
 | `identity` | slug or null | no | Which crew member logged it |
@@ -126,6 +136,22 @@ Read the event timeline.
 | `task_id` | uuid | no | Return only events for this task |
 | `limit` | integer (1–100) | no | Defaults to 50 |
 
+### `recordphase` (composite)
+
+Atomically record a workflow phase outcome: writes the agent session (with its verdict status) and the corresponding event in a single transaction. This is the only safe way to record a phase result — writing the session and event as two separate calls can leave the session stored but the event rejected (or vice versa), crashing the workflow mid-run. The `rejected` vocabulary is valid for both the session `status` and the event `type`.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `task_id` | uuid | yes | |
+| `identity` | slug | yes | The crew identity that ran the phase |
+| `step` | string (1–120) | yes | Workflow phase (e.g. `Review`, `QA`) |
+| `status` | `completed` · `failed` · `rejected` · `timed_out` · `stalled` | yes | The phase verdict |
+| `notes` | string (≤ 3000) | no | Phase summary |
+| `event_type` | event type | no | Defaults to the `status` value; use `note` for non-verdict events |
+| `event_message` | string (1–1000) | no | Defaults to "`<identity>` `<step>` `<status>`" |
+
+The CLI exposes this as `record-phase`. All CLI commands use kebab-case (`create-task`, `get-dispatch-state`, etc.) mapping to the action names documented here.
+
 ---
 
 ## Dispatch
@@ -182,6 +208,7 @@ Register a new project.
 | `description` | string (≤ 3000) | no | |
 | `simultaneity` | integer (1–100) | no | Max concurrent tasks; defaults to 2 |
 | `quiesced` | boolean | no | Start paused; defaults to false |
+| `visual_protocol` | boolean or null | no | Tri-state: `null` = inherit crew default (off), `true` = enable for this project, `false` = explicit off. Defaults to null. |
 
 ### `updateproject`
 
@@ -189,6 +216,8 @@ Update project fields. Only `id` is required; all others are optional patch fiel
 
 **Context-change guard:** changing `repo_path`, `deploy_type`, or `deploy_slug` is blocked while any task in the project has an active run (an agent session with status `running` that started within the last hour): the call throws, because live runs keep the old project config and the change would split the project context mid-run. Wait for the runs to finish, or recover/park those tasks first, then retry.
 
+**`visual_protocol`:** accepted values are `true`, `false`, `null`; anything else is a validation error. `null` clears the override and returns the project to inherit. It is **not** covered by the context-change guard: the dispatcher reads the value once into launch args at dispatch time, so changing it mid-run only affects future launches. Effective value rule: `null` (inherit) and `false` (explicit off) both resolve to off — the visual protocol only runs when the project record carries `true`. The dispatcher passes the resolved boolean to launched workflows as the `visual_protocol` launch arg; workflows receive a plain boolean and never see the tri-state.
+
 ### `deleteproject`
 
 Remove a project registration.
@@ -269,7 +298,7 @@ Stamp publication provenance. Called by the crew Publish phase after rebuilding
 
 ### `getprovenance`
 
-Read the last publication provenance. Returns `{ "provenance": { "source_commit", "crew_release", "published_at" } }`, or `{ "provenance": null }` when nothing has been published yet.
+Read the last publication provenance. Returns `{ "provenance": { "source_commit", "crew_release", "published_at", "task_id" } }`, or `{ "provenance": null }` when nothing has been published yet. `task_id` is the publishing task, for traceability — present when `setprovenance` was called with one, absent otherwise.
 
 ---
 
@@ -287,12 +316,27 @@ Phases whose outcome drives control flow (Build, Review, QA, Reproduce, Integrat
 
 ### Artifact publish verification
 
-Artifact Publish passes only when both are true:
-
-1. The worker declares success.
-2. Mechanical verification confirms the artifact's provenance matches the integrated Git commit: the workflow reads `getprovenance` and compares `provenance.source_commit` against `git rev-parse HEAD` of the project repo.
-
-Verification fails closed. If the provenance is missing, unreadable, or points at a different commit than the integrated HEAD, the workflow parks the task — it does not trust the worker's prose. Narrative remains useful but cannot independently establish deployment truth.
+Artifact Publish passes only when the parent has verified content independently:
+
+1. The workflow carries the merged diff to the artifact builder, polls the
+   build to completion, triggers an independent `artifact_inspect` read-back
+   of the changed regions, and parks with
+   `publish: verification-requested <commit>` — it never stamps provenance
+   and never treats the builder's applied-changes report as verification.
+   The applied report is derived from the carried diff and demonstrated an
+   unreliable false-negative mode (2026-09-12: `applied:[]` for a diff the
+   builder had applied); it is logged as observation only. The read-back
+   request carries the observed builder build identifier (`build.agent_id`)
+   so the read-back can be correlated to the exact builder run that built
+   this attempt.
+2. The parent compares the read-back against the merged diff mechanically
+   (every added line present, every removed line absent), correlates the
+   builder build identifier, and stamps provenance via `set-provenance` only
+   on a match. A mismatch, a build-id mismatch, or an unobtainable read-back
+   never stamps; the task stays parked.
+
+Verification fails closed. The loop never retries a verification and never
+issues a blind re-publish on an unknown outcome.
 
 ### Integrate merge verification
 

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 3 minutes via Muse's scheduling, even when nobody's in the conversation) and an orphan sweep (every 30 minutes, cleaning merged worktrees and breaking stale merge locks; it never touches worktrees belonging to tasks with a running dashboard session). 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 3 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.
 
 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.
 
@@ -55,7 +55,7 @@ Required arguments:
 
 Optional arguments:
 - `dashboardName` — display name for the project registration (default: `"Muse Crew"`).
-- `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", "crew-orphan-sweep": "crew-sweep-canary"}`.
+- `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"}`.
 
 ### What init creates
 
@@ -67,7 +67,7 @@ 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`. The dashboard becomes its own first project, so the crew can work on the dashboard itself.
 
-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 (the orphan sweep ships disabled as a holding state), 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` 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.
 
 ### Verification
 
@@ -83,8 +83,7 @@ After init completes, it returns a summary:
   "scaffold": { "created": 23, "skipped": 0 },
   "project": "registered",
   "crons": [
-    { "id": "crew-poll", "action": "created", "updated_fields": [] },
-    { "id": "crew-orphan-sweep", "action": "created", "updated_fields": [] }
+    { "id": "crew-poll", "action": "created", "updated_fields": [] }
   ]
 }
 ```
@@ -268,6 +267,10 @@ Configuration (per project, via the existing `getconfig` / `updateconfig` action
 
 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.
 
+### 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 triggers an independent `artifact_inspect` read-back of the changed regions and parks with `publish: verification-requested <commit> (build <agent_id|agent_id unobserved>)`. The parent compares the read-back against the merged diff and stamps provenance only on a match (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). QA's provenance check then enforces the stamp mechanically, so an unverified publish fails loudly in QA instead of passing silently.
+
 ## Identities
 
 Each phase has an assigned identity — a character with a defined personality:
@@ -280,7 +283,7 @@ Each phase has an assigned identity — a character with a defined personality:
 | Build | **Wren** | Quietest one, trusts the plan |
 | Review | **Cass** | Fair but exacting — holds the spec as the contract |
 | Integrate | **Wren** | Merges the work, pushes `main` to the repo (succeeds vacuously when the task branch is empty — runtime-state deliverable) |
-| Publish | **Wren** | Ships the merged code to the publish target (skipped when none). The workflow verifies the side effect mechanically — npm via registry version, artifact via `getprovenance` matching the integrated commit — and fails closed if the worker's report and system state disagree |
+| Publish | **Wren** | Ships the merged code to the publish target (skipped when none). The workflow verifies the side effect mechanically — npm via registry version; artifact via an independent content read-back before the parent stamps provenance (see `docs/publish-verification.md`) — and fails closed if the worker's report and system state disagree |
 | QA | **Hazel** | Code-blind, persistent, wears persona costumes |
 | Reproduce | **Hazel** | Reproduces bugs before fixing |
 | Write | **Tate** | Docs writer, observational voice |

package/docs/publish-verification.md

@@ -0,0 +1,205 @@
+# Publish content verification — parent protocol
+
+Provenance is the artifact's claim that its live content came from a specific
+repo commit. The workflow used to stamp it; it no longer does. This document
+is the parent-side runbook. The workflow script handles the mechanical
+halves; the parent handles the stamp.
+
+## Why the parent stamps
+
+The builder's `applied` report is derived from the diff the workflow carries
+to it — so `verifyAppliedChanges` (report vs. diff) is circular: a fabricated
+report passes by construction. Canary run 8 (2026-09-11) proved it: the build
+was hollow, the report matched the diff, the workflow stamped provenance, and
+all eight phases went green on stale content. The old post-hoc check
+(get-provenance vs. HEAD) only verified the stamp, not the content.
+
+Task `23ca8f3f` (2026-09-12, canary `orchestra-dashboard-2`) proved the report
+is unreliable in the other direction too: the builder applied the one-line
+diff, the applied-report came back `applied: []`, and the workflow's old
+applied-report gate parked the task fail-closed as unverified — on a publish
+that had actually landed. A later independent read-back of the live artifact
+showed the change present.
+
+The rule: **the builder's applied report is never a verification signal, in
+either direction.** A matching report certifies nothing (it is derived from
+the carried diff — circular by construction, canary run 8). A mismatching or
+empty report blocks nothing (false-negative mode demonstrated by `23ca8f3f`).
+The workflow computes the report comparison as an observation only — it
+never parks on it. The parent ignores the applied report entirely when
+deciding whether to stamp: an `applied:[]` or mismatched report with a
+matching independent read-back stamps normally.
+
+The contract is split on purpose:
+
+- **Workflow-owned:** carrying the merged diff to the builder, the
+  applied-report observation (logged, never a park), the build-completion
+  poll, post-deploy cleanup, triggering an independent `artifact_inspect`
+  read-back of the changed regions (carrying the observed builder build
+  identifier for correlation), recording the Publish session completed, and
+  parking with `publish: verification-requested <commit>` instead of
+  stamping.
+- **Parent-owned:** reading back the artifact's actual content, comparing it
+  mechanically against the merged diff, checking for supersession, stamping
+  provenance only on a match, reading the stamp back exactly, and re-queuing
+  the task to `in_progress`. In standard/bugfix, QA's provenance check then
+  enforces the stamp — an unstamped publish fails loudly in QA instead of
+  passing silently. Chore has no QA: the parent's stamp read-back is the
+  final gate.
+
+No artifact publish completes without parent-stamped provenance. A missing or
+mismatched read-back never stamps.
+
+## The park
+
+When the artifact build lands, the workflow parks the task with the message:
+
+```
+publish: verification-requested <commit> (build <agent_id|agent_id unobserved>) — artifact build landed, post-deploy
+finalized, provenance NOT stamped. Parent: run docs/publish-verification.md
+(content read-back inspection <inspection_id> already triggered).
+```
+
+or, if the workflow's inspect trigger failed:
+
+```
+publish: verification-requested <commit> (build <agent_id|agent_id unobserved>) — ... (read-back inspect trigger
+failed: <reason> — parent: trigger artifact_inspect manually).
+```
+
+The parked message is stored as `Parked: publish: verification-requested
+<commit> …`. Match on the contained exact string
+`publish: verification-requested`. The `<commit>` is the merged commit whose
+content must be verified. The `(build …)` suffix carries the
+`build.agent_id` the workflow observed for this publish attempt (the
+artifact system's durable build identifier — the parent uses it for the
+build-ID correlation in step 4b); `agent_id unobserved` means the edit was
+accepted but the workflow never correlated it to a builder run. The merge
+lock is already released (post-deploy ran before the park), so the parked
+task holds no resources.
+
+## Parent verification procedure
+
+For a task parked with `publish: verification-requested <commit>`:
+
+1. **Resolve the project.** Read the task's project via the Crew API
+   (`getproject`); you need `repo_path` (the git checkout) and the artifact
+   slug (the project's publish target).
+2. **Expected change.** Run `git show <commit>` (or
+   `git diff <commit>^1 <commit>`) in `repo_path`. This is the expected
+   content — the same diff the workflow carried to the builder.
+3. **Actual content.** Get the read-back:
+   - If the park message names an `inspection_id`, read that inspection's
+     result (async `artifact_inspect` results are delivered to the parent,
+     like the visual-verdict inspections).
+   - If the trigger failed, call `artifact_inspect` yourself with
+     `repair_authorized: false` and the `verbatim_request` rebuilt from the
+     workflow source: `buildPublishReadbackRequest(taskId, commit, diff,
+     buildAgentId)` in `workflows/standard.js` (identical in `bugfix.js`
+     and `chore.js`) — pass the task id, the commit, the diff from step 2,
+     and the agent_id from the park message's `(build …)` suffix (ledger
+     lookup from step 4b if the suffix says `agent_id unobserved`; null if
+     neither is available).
+   - If no read-back can be obtained at all, log
+     `publish: verification-blocked <commit> <reason>` and leave the task
+     parked for human attention. Never stamp without a read-back.
+4. **Compare mechanically.** For every added (`+`) line in the diff, the
+   read-back must report it PRESENT in the artifact's current source. For
+   every removed (`-`) line, the read-back must report it ABSENT. Quote the
+   observed lines; do not infer from prose.
+4b. **Build-ID correlation.** Prove the read-back inspected the live build
+   of THIS publish attempt — not a different build's output:
+   1. **Expected** = the agent_id in the park message's `(build …)` suffix.
+      If the suffix says `agent_id unobserved`, look up the workflow's
+      durable publish ledger at `$CREW_HOME/.publish-ledger/<slug>.jsonl`
+      for the `submitted` entry with this `<commit>` and use its
+      `agent_id` field (it may still be null — then this step is vacuous).
+   2. **Live** = the build agent_id the read-back reports for the live
+      build (the request asks for it explicitly; the inspector may state
+      that no build/agent_id is visible).
+   3. If expected and live are both non-null and DIFFER, the read-back may
+      have inspected a different build's output — log
+      `publish: build-mismatch <commit> expected <expected> observed <live>`,
+      stay parked, never stamp, never re-queue. This is not a retry signal:
+      a later inspection of the right build can be recorded by the human
+      if desired; the loop never re-drives the verification itself.
+   4. Otherwise the content match from step 4 decides; log the correlation
+      outcome (expected/live compared, or vacuous) in the `publish:
+      verified` note.
+5. **Supersession check.** Before stamping, prove the inspected live
+   artifact still represents the commit being certified. Read the crew's
+   current provenance record (`get-provenance`): if `source_commit` names a
+   commit NEWER than `<commit>` (a later Publish already landed), the
+   read-back is stale — do NOT stamp `<commit>` on top of it. Log
+   `publish: superseded <commit> by <newer_commit>` and leave the task
+   parked for human attention. Never claim commit A after commit B changed
+   the artifact.
+6. **Stamp, verify the stamp, then re-queue:**
+   - **Match** — stamp provenance with the Crew API CLI `set-provenance`
+     (the crew-owned store). Do NOT use the artifact's `setprovenance`
+     action — it writes a different, non-authoritative store that QA never
+     reads, so the stamp would be invisible to every gate:
+     `set-provenance --json '{"source_commit":"<commit>","crew_release":"<basename of $crewHome/current>","published_at":"<date -u +%Y-%m-%dT%H:%M:%SZ>","task_id":"<task>"}'`.
+     Then read the stamp back with `get-provenance`
+     and confirm all four fields match exactly what was sent — a stamp
+     that cannot be read back is not a stamp. Only then log the task note
+     event `publish: verified <commit> (<inspection_id>)` and re-queue
+     with `update-task` → state `in_progress` (never `todo` — `todo`
+     restarts Triage and resets retry accounting). The dispatcher resumes
+     at QA from the completed Publish session (standard/bugfix); chore has
+     no QA — it proceeds to terminal completion. QA's provenance check
+     (standard/bugfix) enforces the stamp mechanically.
+   - **Mismatch** — do NOT stamp. Log the exact FAIL evidence with
+     `publish: content-mismatch <commit> <details>` (quote the observed
+     lines from the read-back) and leave the task parked. Never stamp
+     provenance on a mismatch; never re-queue a mismatched publish into
+     QA — QA would fail it and burn rework budget communicating a Publish
+     problem that is not QA's to solve. The task stays parked for human
+     attention; the loop does not retry the verification.
+   - **Stamp failure** — if `set-provenance` fails after a matched read-back,
+     log `publish: stamp-failed <commit> <reason>` and leave the task parked
+     for human attention. Never re-queue an unstamped-but-verified task into
+     QA — QA would fail it and burn rework budget on a stamping problem.
+
+## Exact note-event prefixes
+
+Case-sensitive, exact-prefix matches — match on prefixes, never on English
+meaning:
+
+- `publish: verification-requested <commit>` — workflow park; contained in
+  the stored `Parked: …` message.
+- `publish: verified <commit> (<inspection_id>)` — parent, after stamping
+  AND reading the stamp back exactly; re-queued to `in_progress` (never
+  `todo`).
+- `publish: content-mismatch <commit> <details>` — parent; exact FAIL
+  evidence quoted; stays parked, never stamped, never re-queued to QA.
+- `publish: build-mismatch <commit> expected <expected> observed <live>` —
+  parent; the read-back inspected a different build's output than the
+  publish attempt (step 4b); stays parked, never stamped, never re-queued.
+- `publish: superseded <commit> by <newer_commit>` — parent; a later Publish
+  already landed; stays parked for human attention.
+- `publish: verification-blocked <commit> <reason>` — parent; no read-back
+  obtainable; stays parked for a human.
+- `publish: stamp-failed <commit> <reason>` — parent; read-back matched but
+  the stamp call failed; stays parked for a human.
+
+## Workflow differences
+
+- **standard / bugfix:** after `publish: verified`, the dispatcher resumes
+  at QA from the completed Publish session. QA's provenance check enforces
+  the stamp mechanically — an unstamped publish fails loudly there.
+- **chore:** there is no QA phase. After `publish: verified` (stamp +
+  exact stamp read-back), the dispatcher proceeds to terminal completion.
+  The parent's stamp read-back is the final gate — no downstream phase
+  re-checks it.
+
+## Recovery: rebuilding the read-back request
+
+If the park message names no inspection and you must trigger the read-back
+manually, the request is deterministic — rebuild it from the workflow source
+(`buildPublishReadbackRequest` in `workflows/standard.js`, identical in
+`bugfix.js` and `chore.js`) with the task id, the `<commit>` from the park
+message, the diff from `git show <commit>` in the project's `repo_path`,
+and the agent_id from the park message's `(build …)` suffix (use the ledger
+lookup from step 4b if the suffix says `agent_id unobserved`; pass null if
+neither is available).

package/lib/AGENTS.md

@@ -3,14 +3,14 @@
 Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, and the release system.
 
 - `build-registry.js` — deterministic extractor that generates `workflows/registry.json` (workflow step registry) from the workflow files' `meta` blocks at release time; invoked by `crew-release.sh` deploy
+- `crew-api.js` — the crew-owned task-service API (dependency inversion, 2026-09-11): a zero-dependency Node CLI implementing the API.md contract against `$CREW_HOME/crew-state.db` (schema in `schema.sql`). Workflows call it through their agents' shell; the dashboard delegates to it. All state-machine invariants live as CHECK constraints in the schema, never in client prose. Includes the `record-phase` composite (session + event in one transaction) and a one-time `migrate` import from a dashboard app.db.
+- `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). 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/refresh-lock/lock-status over git worktrees (`.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. `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) on a scratch repo
+- `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.
+- `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
 - `test-publish-skip.sh` — regression tests for the no-lock graceful publish skip (park 2026-09-11): `lock-status` returns exact `UNLOCKED`/`LOCKED by <holder> since <ts> (pid <pid>)`; a fake empty-diff integrate takes the MERGED_EMPTY branch and never takes the lock; the shipped step-5 block from publish-npm.sh (extracted by anchor) skips gracefully on UNLOCKED (no park, no `PUBLISH_COMPLETE`), follows the refresh path when a lock is held, and fails closed on a `lock-status` query failure; the gate sits inside the ALREADY_PUBLISHED=0 branch and mutation steps are gated on NO_LOCK_HELD=0
-- `orphan-sweep.sh` — find and clean stale worktrees and merge locks: parses `merge-lock.sh status` key=value fields (never a PID); a lock whose task has a running session is untouched regardless of lease age; a lock with no running session is broken only when its lease is expired (via merge-lock.sh release so the break lands in the audit log); reaps a lifecycle pin only after N consecutive clean-mode observations (default 3, `ORPHAN_SWEEP_REAP_AFTER`) with the task absent from the active-run list — a single negative observation only plants a tombstone, so a daemon-restart window can't reap a live task's pin
 - `publish-npm.sh` — deterministic npm publish: lock refresh, release install, version write/commit, pack, registry publish, verify, push, post-deploy. Takes TARGET_VERSION as input; idempotent on retry/resume.
 - `compose-evidence.py` — deterministic visual-evidence compositor (Pillow): pairs identical PNG stems from baseline/ and postchange/ dirs, emits `<stem>-sidebyside.png` and amplified-difference `<stem>-overlay.png` into composites/, prints `PAIR`/`SKIP` manifests. Byte-deterministic; nonzero exit on errors.
-- `test-orphan-sweep.sh` — regression tests for orphan-sweep.sh (active-run guard, verified removal, fail-closed)