Conductor 0.4.0: Stage 3 attended single-ref apply

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # Contributing
 
-Conductor `0.3.0` is attended Stage 2 software for exactly Herdr `0.7.5`.
-Changes must stay fail-closed, preserve one runtime authority, and avoid claims
-beyond implemented and independently checked behavior.
+Conductor `0.4.0` is attended Stage 2 and Stage 3 software for exactly Herdr
+`0.7.5`. Changes must stay fail-closed, preserve one runtime authority, and
+avoid claims beyond implemented and independently checked behavior.
 
 ## Development requirements
 
@@ -30,7 +30,8 @@ manifest, historical evidence, and pinned Actionlint.
 ## Change boundaries
 
 - `scripts/stage1-runtime.mjs` remains the one implementation behind assemble,
-  board, status, harvest, and stand-down. Do not add a competing runtime.
+  board, status, harvest, preview, apply, and stand-down. Do not add a
+  competing runtime.
 - Task/outbox authority must be durable before pane/agent creation. Reports use
   only bounded stdin and one exact task-bound destination.
 - Preserve complete producer selection, collector-computed paths, deterministic
@@ -44,7 +45,13 @@ manifest, historical evidence, and pinned Actionlint.
 - Product runtime never removes worktrees, branches, tasks, outboxes, reports,
   gate sources, artifacts, recordings, logs, or state. Only the explicit live
   harness may delete its exact identity-bound disposable inventory.
-- Do not add Stage 3 preview/approval/apply/recovery, suite adapters, unattended
+- Stage 3 stays the documented attended single-ref apply: journal-only
+  fixed-statement approval receipts, durable consumption before any effect,
+  exactly zero or one fast-forward apply CAS per attempt, and uncertainty
+  resolution only for the apply publication by exact re-observation. Do not add
+  approval delegation, multi-ref or non-fast-forward apply, or resolution for
+  any other operation.
+- Do not add suite adapters, unattended
   launch, Browser/Guard/Swarm promotion, site changes, push/release automation,
   cleanup/prune/migration/expiry, or newer-Herdr claims.
 
@@ -91,8 +98,9 @@ A pull request must state:
    no-recovery limitations;
 5. whether package, manifest, README, SECURITY, private-state docs, roles,
    source definition, evidence inventory, and CI agree; and
-6. explicit confirmation that no Stage 3, adapter, unattended, product cleanup,
-   Browser, site, push, tag, or release change entered scope.
+6. explicit confirmation that no adapter, unattended, product cleanup,
+   Browser, site, push, tag, or release change entered scope, and that Stage 3
+   changes stay inside the single-ref attended apply boundary.
 
 Never include credentials, tokens, private paths/state, raw action output,
 prompts, transcripts, recordings, customer data, or unsanitized evidence.

README.md

@@ -1,13 +1,14 @@
 # Herdr Conductor
 
 > [!IMPORTANT]
-> Conductor `0.3.0` implements **Stage 2 attended strict task/report contracts**
-> on exactly Herdr `0.7.5`, protocol `17`, API schema `1`. An operator explicitly
-> invokes every transition. This is cooperative same-UID coordination, not
-> authentication, sandboxing, unattended orchestration, or Stage 3
-> approval/apply.
-
-Conductor coordinates task-bound producer and gate roles through five installed
+> Conductor `0.4.0` implements **Stage 2 attended strict task/report contracts**
+> and the **Stage 3 attended single-ref apply** on exactly Herdr `0.7.5`,
+> protocol `17`, API schema `1`. An operator explicitly invokes every
+> transition, records every approval receipt, and resolves every apply
+> uncertainty. This is cooperative same-UID coordination, not authentication,
+> sandboxing, or unattended orchestration.
+
+Conductor coordinates task-bound producer and gate roles through seven installed
 Herdr actions and one passive board pane. One runtime authority in
 `scripts/stage1-runtime.mjs` owns the complete lifecycle. It preserves the
 Stage 1 physical repository/workspace/run identity, hash-chained journal,
@@ -63,10 +64,53 @@ writable report outboxes remain outside source. This is an ordinary-write and
 review boundary, not malicious same-UID enforcement. Gate reports require empty
 changed paths and artifacts and exhaustive worker-asserted requirement results.
 
+## Stage 3 apply
+
+With configuration v3 declaring a non-null `apply.target_ref`, a run whose gate
+reports are collected (or a gateless harvested run) may be applied through an
+attended four-operation attempt:
+
+- `preview` journals one zero-effect document binding the exact run,
+  integration entry, byte-ordered completed gate assertions, and the observed
+  apply target. The target ref must exist, must differ from the integration
+  branch, must not be checked out in any worktree, and must sit exactly at the
+  run's integration base, so the proposed move is a pure fast-forward with a
+  non-empty rename-free change summary. Any drift fails closed with zero
+  recorded authority and zero Git mutation.
+- The operator records one approval receipt through `npm run apply:approve`,
+  which accepts at most 16384 canonical bytes on stdin, requires the fixed
+  approve/reject statement token bound to the exact preview journal entry
+  digest, and stores the receipt only in the hash-chained journal. An approve
+  receipt requires the preview to still be live; a reject receipt records on a
+  drifted target too, so an attempt can always close. Approval receipts remain
+  unauthenticated same-UID operator records, never signatures or authorization
+  proof.
+- `apply` first journals a durable consumption marker spending the receipt
+  before any Git effect, then publishes the attempt's single outcome: a live
+  target moves with exactly one double-preflighted compare-and-swap from the
+  previewed SHA to the integrated final SHA, and a drifted target records a
+  durable `unapplied` outcome with zero target CAS, closing the attempt so the
+  run can always progress. A spent receipt never authorizes a second
+  compare-and-swap. The attended `apply` action may reclaim the repository
+  mutation lock only from a dead process that held exactly its own apply
+  operation id; every other retained lock keeps refusing.
+- A crash between consumption and publication observation leaves the run
+  apply-uncertain, and every other surface keeps refusing with
+  `recovery_required`. The attended `apply` action alone resolves it by exact
+  re-observation of the target ref: exactly the final SHA is applied, exactly
+  the previewed SHA voids the attempt, and any other observation fails closed
+  permanently. Resolution exists only for the apply publication; no other
+  operation gains it.
+
+A closed attempt (reject receipt or voided publication) permits one fresh
+preview; an applied attempt is terminal; at most 8 attempts may exist.
+Configuration v2 runs never enter Stage 3 states.
+
 Lifecycle scanning derives one disjoint state or fails with
 `bookkeeping_unknown`/`recovery_required`. Stable states cover provisioning,
 waiting reports, terminal rejection, nonprogressable delivery, ready/integrated
-results, gate provisioning/waiting/refusal/collection, every stand-down close
+results, gate provisioning/waiting/refusal/collection, apply
+preview/approval/consumption/void/applied, every stand-down close
 prefix, and archive. Attended stand-down is available from every stable state,
 binds a deterministic exact pane close set, closes only the next full live tuple,
 and archives only after every close is observed. It never removes product
@@ -75,11 +119,16 @@ artifacts.
 
 ## Configuration
 
-Commit `.herdr-conductor.json` in the invoking repository:
+Commit `.herdr-conductor.json` in the invoking repository. Configuration v3 is
+exactly v2 plus one required `apply` member — `null` to declare Stage 3
+disabled, or an exact `{ "target_ref": "refs/heads/…" }` object naming the
+single apply target. Configuration v2 remains accepted with unchanged meaning
+and no Stage 3 operations:
 
 ```json
 {
-  "version": 2,
+  "version": 3,
+  "apply": { "target_ref": "refs/heads/release" },
   "state_root": { "kind": "default" },
   "worktree_root": ".conductor-worktrees",
   "roles": [
@@ -140,13 +189,18 @@ herdr plugin action invoke assemble --plugin structupath.conductor
 herdr plugin action invoke board --plugin structupath.conductor
 herdr plugin action invoke status --plugin structupath.conductor
 herdr plugin action invoke harvest --plugin structupath.conductor
+herdr plugin action invoke preview --plugin structupath.conductor
+herdr plugin action invoke apply --plugin structupath.conductor
 herdr plugin action invoke stand-down --plugin structupath.conductor
 ```
 
 `assemble` returns exact task paths, source roots, outbox slots, and publisher
 commands. A worker sends canonical report bytes to that publisher through stdin.
 `harvest` is explicitly invoked and attended; producer report collection and
-gate report collection may require separate invocations. Board/status are passive
+gate report collection may require separate invocations. `preview` prints the
+journaled preview document, its entry digest, and the exact approval command;
+`apply` consumes the recorded approve receipt and performs or resolves the
+single target compare-and-swap. Board/status are passive
 and infer no missing input. `stand-down` closes only panes that were observed;
 each exact workspace/pane/cwd/generation identity must still match, and the full
 attached-agent tuple is also required when an agent was observed.
@@ -187,7 +241,8 @@ bash -n scripts/*.sh
 shellcheck --shell=bash scripts/*.sh
 python3 -m py_compile scripts/harness-fs-helper.py
 go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7
-node --test tests/stage1-runtime-*.test.mjs tests/stage2-*.test.mjs
+node --test tests/stage1-runtime-*.test.mjs tests/stage2-*.test.mjs \
+  tests/stage3-*.test.mjs
 ```
 
 The live harness requires an explicit candidate, review record, empty canonical
@@ -219,15 +274,19 @@ npm run evidence:stage2:finalize -- \
   TOCTOU windows.
 - Worker results are unauthenticated assertions. The retained external-review
   record uses only fixed independent-human/independence/GO tokens and requires
-  zero findings; those closed assertions remain unauthenticated.
+  zero findings; those closed assertions remain unauthenticated. Stage 3
+  approval receipts remain unauthenticated same-UID operator records.
 - Product resources are retained indefinitely and consume cumulative disk.
-- A crash after a possible external effect remains uncertain; Stage 2 has no
-  ambiguous-operation recovery or replay.
+- A crash after a possible external pane/agent effect remains uncertain; Stage
+  2 has no ambiguous-operation recovery or replay. The only resolvable
+  uncertainty is the Stage 3 apply publication, whose single-ref outcome is
+  exactly observable; resolution exists only for the apply publication.
 - Guard is observational and cannot prove prevention. Conductor does not invoke
   Swarm and makes no Browser, suite-adapter, site, sandbox, promotion, or
   unattended-readiness claim.
-- Stage 3 preview, approval, approval consumption, apply, and recovery are not
-  implemented.
+- Stage 3 applies exactly one configured local ref by fast-forward. It does not
+  push, publish remotely, deploy, tag, release, delegate approval, or apply
+  multiple refs.
 
 See [SECURITY.md](SECURITY.md), [CONTRIBUTING.md](CONTRIBUTING.md), and
 [docs/private-state-v1.md](docs/private-state-v1.md) for the authoritative

SECURITY.md

@@ -2,18 +2,21 @@
 
 ## Supported scope
 
-Conductor `0.3.0` provides Stage 2 **attended-operational** strict task/report
-contracts on exactly Herdr `0.7.5`, protocol `17`, API schema `1`, under one
-cooperative OS user. The five actions preserve physical repository/workspace/run
-identity, strict private state, one repository mutation lock, journaled crash
-truth, deterministic zero-or-one target compare-and-swap, exact-SHA gate sources,
+Conductor `0.4.0` provides Stage 2 **attended-operational** strict task/report
+contracts and the Stage 3 attended single-ref apply on exactly Herdr `0.7.5`,
+protocol `17`, API schema `1`, under one cooperative OS user. The seven actions
+preserve physical repository/workspace/run identity, strict private state, one
+repository mutation lock, journaled crash truth, deterministic zero-or-one
+target compare-and-swap for integration and for apply, exact-SHA gate sources,
 and exact-identity stand-down/archive.
 
 These controls prevent accidental authority confusion; they are not
 authentication, sandboxing, signatures, or remote attestation. Worker-reported
 `delivered`, `approve`, `pass`, command/criterion results, identity, evidence, and
 external reviewer identity/independence/findings are unauthenticated assertions.
-They do not authorize apply, release, or any other effect.
+They do not by themselves authorize apply, release, or any other effect. Stage 3
+approval receipts are unauthenticated same-UID operator records: fixed-statement
+journal entries, not signatures, credentials, or delegated authority.
 
 ## Preserved boundaries
 
@@ -33,10 +36,20 @@ They do not authorize apply, release, or any other effect.
 - Stand-down binds one deterministic close set and closes only an exact live
   pane/agent/cwd tuple. It retains every product worktree, branch, task, outbox,
   report, gate source, artifact, recording, log, and operation record.
-- No product cleanup, prune, migration, expiry, adoption, ambiguous recovery,
-  preview, approval receipt, approval consumption, apply, suite adapter,
-  unattended launch, Browser promotion, site repin, push, or deployment is
-  implemented.
+- Stage 3 preview performs zero Git mutation; an approve receipt is durably
+  consumed before any apply effect and never authorizes a second
+  compare-and-swap; the apply moves exactly one configured local ref by
+  fast-forward from its previewed SHA, or durably records an unapplied outcome
+  with zero CAS when the target drifted. An uncertain apply publication is
+  resolved only by attended exact re-observation of that ref, and any foreign
+  observation fails closed permanently. The attended apply may reclaim a
+  repository lock only from a dead process holding exactly its own apply
+  operation id; the pid-liveness check remains cooperative, not
+  authentication.
+- No product cleanup, prune, migration, expiry, adoption, suite adapter,
+  unattended launch, Browser promotion, site repin, push, remote publication,
+  or deployment is implemented. Ambiguous-operation resolution exists only for
+  the Stage 3 apply publication.
 
 ## Residual risks
 
@@ -45,8 +58,10 @@ They do not authorize apply, release, or any other effect.
   authenticate it.
 - Final filesystem/Git checks and Herdr pane-ID close retain same-user TOCTOU
   windows. Herdr `0.7.5` offers no conditional close tuple.
-- A crash after possible Git CAS, pane close, archive publication, or evidence
-  unlink remains uncertain. Stage 2 does not infer success or replay it.
+- A crash after possible pane close, archive publication, or evidence unlink
+  remains uncertain; Stage 2 does not infer success or replay it. A crash
+  around the Stage 3 apply CAS is resolved only by attended exact
+  re-observation, never inferred or replayed.
 - Retained product state consumes cumulative disk; no product expiry or cleanup
   API exists.
 - Only 40-hex SHA-1-width Git repositories are supported.
@@ -100,5 +115,6 @@ npm run test:stage2
 shellcheck --shell=bash scripts/*.sh
 python3 -m py_compile scripts/harness-fs-helper.py
 go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7
-node --test tests/stage1-runtime-*.test.mjs tests/stage2-*.test.mjs
+node --test tests/stage1-runtime-*.test.mjs tests/stage2-*.test.mjs \
+  tests/stage3-*.test.mjs
 ```

docs/herdr-plugins-cheatsheet.md

@@ -4,13 +4,14 @@ The canonical cross-plugin guide lives in the
 [`herdr-suite-site` documentation](https://github.com/StructuPath/herdr-suite-site/tree/main/docs-src).
 That separate site is not changed or promoted by Conductor Stage 2.
 
-For Conductor `0.3.0`, use this repository's [README](../README.md) as the
+For Conductor `0.4.0`, use this repository's [README](../README.md) as the
 operational authority. Its bounded support is exactly Herdr `0.7.5`, protocol
-`17`, API schema `1`, five attended actions, and one passive board pane.
+`17`, API schema `1`, seven attended actions including `preview` and `apply`,
+and one passive board pane.
 
 Key boundaries:
 
-- configuration v2 has no launch arguments;
+- configuration v2 and v3 have no launch arguments;
 - immutable task and empty private outbox authority precede pane/agent creation;
 - reports use only the exact task-bound bounded-stdin publisher;
 - every worker/reviewer result is an unauthenticated assertion;

docs/private-state-v1.md

@@ -1,6 +1,6 @@
 # Conductor private state v1
 
-**Status:** Stage 2 in Conductor `0.3.0`. All five actions use this state
+**Status:** Stage 2 and Stage 3 in Conductor `0.4.0`. All seven actions use this state
 exclusively through `scripts/stage1-runtime.mjs`. Tasks/outboxes precede agents;
 report collection, deterministic integration, exact-SHA gates, stand-down close
 prefixes, and archive share the same journal authority.
@@ -254,16 +254,18 @@ Herdr `0.7.5`, protocol `17`, schema `1`.
 
 Private state remains cooperative same-user coordination. The repository lock
 does not stop unrelated Git or same-UID mutation after final checks, and Herdr's
-pane close accepts only pane ID, leaving documented TOCTOU. Stage 2 has no
-ambiguous-operation recovery, product cleanup/prune/migration/expiry, Stage 3
-preview/approval/apply, suite adapter, unattended trigger, Browser promotion,
-push, or deployment.
+pane close accepts only pane ID, leaving documented TOCTOU. Stage 3 preview,
+approval, consumption, and apply authority live only in the hash-chained
+journal; the sole ambiguous-operation resolution is the attended apply
+publication, resolved by exact target-ref re-observation. There is no product
+cleanup/prune/migration/expiry, suite adapter, unattended trigger, Browser
+promotion, push, or deployment.
 
 ## Verification
 
 ```bash
 node --test tests/private-state-schema.test.mjs tests/state-kernel.test.mjs \
-  tests/stage1-runtime-*.test.mjs tests/stage2-*.test.mjs
+  tests/stage1-runtime-*.test.mjs tests/stage2-*.test.mjs tests/stage3-*.test.mjs
 npm run check
 ```