ace-overseer 0.26.1 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec144ec980c58f2cf9fde48558e42ffdb7798d45c94897dcd28112d4cf348d1a
-  data.tar.gz: 95a59adbdc0244152f79c0d0cce6f4cd60e4b1a29b84e8a86d18ff3130a2c63c
+  metadata.gz: c0228801ebed27e7b1fca7fe8f580dc4fdc2a5a5be9e8d76d3c6cf59b1f8cf48
+  data.tar.gz: 2fae06ba1fc9174fc41f53f3ddcbcc1ee8dddd0152faaaa7e894a862d6f0e8c5
 SHA512:
-  metadata.gz: 30b3626aaf30e4297b6000aa0f00cc32320fb0b0eedbb98c33e26f1f867a60690dfdc6b008bcc737b59b80e0c87b28c616450763ad8c3c7acad22809435aba54
-  data.tar.gz: 397b3f3774a3e3f6d80aacf41bd8b2da542ee7597c08d48ce4d876d89b3dcd852f2a879fcead3f9ee511ea6ae2593ae596fc96ef7a622aa36ba77e5369205c2e
+  metadata.gz: 2ede68b20a4104eeb494014ca34a05627e8367aa5d1b6cf71cbd5f8fcfa0e4168e2029c3ca78be121e353e3e24a25bc0dd0c5ae153850b9797a7bff5bf504e6c
+  data.tar.gz: 611af27c6c2b7febc096cefeaff5545d8f3ce7fd1dd9e377932371359c850ec0e1f757476d9ffba937135f3ea021bd87f4c268007ab81b0e571c1723b48c4d88

data/CHANGELOG.md

@@ -7,6 +7,144 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-10-31
+
+### Fixed
+
+- Delegate lab bootstrap to workers and independent verification; distinguish
+  preparation/printed briefs from running agents and confirmed first turns.
+- Preserve installed operational runtime across project starts.
+- Normalize local observation identities for the eyes wire contract.
+
+## [0.28.0.pre.3] - 2026-10-31
+
+### Fixed
+
+- Child project bundles no longer inherit a forced Lab `ACE_TOOLCHAIN` mode;
+  project-selected path/source dependencies and explicit child policies remain
+  authoritative. The Lab role may perform routine project startup setup without
+  taking over project deliverables.
+- `ace-overseer start` bootstraps missing start settings and becomes the Lab
+  coordinator in the current terminal without Herdr preflight. Explicit
+  `start --reconcile` manages project children after agent initialization. The coordinator can configure itself using the packaged guide.
+- Lab and project workspaces use `overseer` and topology ids such as `ace`,
+  independently of session ownership labels. Project startup executes each
+  project's own Gemfile/lock and binstub in a separate process; project panes
+  use their own bundle instead of inheriting the Lab's gem runtime.
+
+## [0.27.0] - 2026-10-30
+
+### Fixed (review rounds 3/3b)
+
+- Start hardening: herdr failures surface as blocked reports on project and
+  lab paths; the first prompt is a separate step (a prompt failure never
+  strands a started agent); installed toolchain resolution never falls back
+  to the checkout; the lab space is `lab-overseer` (no basename collision);
+  nested lab scopes are refused; malformed observe.remote entries degrade
+  to per-source health markers.
+
+### Added
+
+- Remote PR observation (task 8xs.t.pu0.4): `observe.remote.pull_requests`
+  configuration projects configured PRs through the existing forge provider
+  adapters — lifecycle rows (new HEAD, merge/close/reopen) and activity rows
+  (review/approval/comment identity sets) with semantic revisions, wake
+  payloads (forge, number/title, event kind, author, link), and per-source
+  degradation on API failures with one wake per failure class.
+
+- `ace-overseer observe` projects the six local source classes (task
+  8xs.t.pu0.3): project and `_overseer` tasks, worktrees, coworker
+  availability and assignment progress alongside HITL events — every row
+  read from its state owner with stable key/revision semantics, per-source
+  health (`ok`/`degraded`), and degraded-source markers that wake once per
+  failure class while healthy sources keep projecting.
+
+- `ace-overseer start [--dry-run] [--format table|json]` (task 8xs.t.pu0.1):
+  starts or reuses the project overseer session from an explicit `start`
+  section (scope/profile/instructions) in the `.ace/overseer/config.yml`
+  cascade. Canonical project-root resolution (subdirectory, symlink, and
+  worktree share one owner), Herdr-backed session identity
+  (`overseer-<project>` label) with reuse/conflict/dead-replacement
+  semantics, guide resolution through the handbook chain, and the packaged
+  project-overseer start guide (`wfi://overseer/start`).
+
+### Fixed
+
+- Lab scope starts the lab's OWN overseer session (review 8xte508e): `lab_start`
+  previously created the `overseer-lab` space and only started project sessions,
+  so the lab-start guide reached no agent (`pane` stayed nil). The lab session
+  now boots or is reused in the lab space with the same identity rules as a
+  project session (label from the lab root, cwd at the lab root, live owner
+  reused, foreign owner refused, empty configured list still runs the lab
+  overseer).
+- The lab starts each project in its OWN herdr space (review 8xte508b /
+  readiness F2): the lab space hosts only the lab overseer session; each
+  configured project gets a space titled by its session label
+  (`overseer-<project>`), created/reused by title and passed into the nested
+  start through an explicit workspace factory seam. Project sessions are
+  isolated from each other and from the lab overseer, never re-resolve the
+  caller's ambient workspace (a plain terminal without a herdr pane works),
+  and a live session found in another workspace is reused and reports that
+  workspace without leaving an empty space behind.
+- Installed toolchain isolation for start instructions (readiness F4): the
+  `wfi://` guide resolution now selects the `ace-nav` executable through
+  `Ace::Support::Cli::Toolchain` — under `ACE_TOOLCHAIN=installed` the
+  installed gem launcher is always used, never the checkout's `bin/`
+  binstubs even when the project contains an executable ACE checkout; auto
+  mode is unchanged. An unavailable installed executable is a blocked
+  start, never a fallback to source.
+- Lab-level failures keep their lab context (review 8xte508k): a raise
+  during lab start (e.g. herdr unavailable while resolving the lab space)
+  previously collapsed into the generic project-style blocked report with
+  `scope: nil`; `lab_start` now maps it to `status: blocked` with the lab
+  `scope`/`root`/`label` intact and a "lab start failed: …" message. A
+  herdr workspace entry that carries the title but no id is treated as the
+  space itself (reused by title) instead of falling through to
+  `workspace_create`, which would duplicate the `overseer-lab` space.
+- `start` sends the first prompt after `herdr agent start` (review F3):
+  `agent start` success only means the interactive agent is ready for input, so
+  a session booted without a prompt sat idle (no state read, no `/eyes`
+  arming). `boot_session` now submits a first-turn prompt (the standing
+  instructions' "First turn after start" contract) right after the agent
+  starts; a reused session is never prompted again. The prompt is a separate
+  step from the boot (review 8xtiatf0): a delivery failure after a started
+  agent stays `started` with `prompt_failed: true` and a repairable warning —
+  a live idle agent is never reported as a failed start.
+- herdr failures surface as blocked starts, never raw exceptions (reviews
+  8xth38bw/8xtiatez): the project path's rescue now covers every
+  `Ace::Herdr::ExecutorError` (pane list, agent probe, session boot) with a
+  "herdr failed while preparing the overseer session: …" message, and the
+  lab-level rescue covers `CommandError` from workspace/pane calls with the
+  lab context intact ("lab start failed: …"). Dry-run probes no herdr state.
+- Readiness requires a CONFIRMED first turn, and a failed delivery is
+  repaired on restart (re-review R7): the first-turn prompt is submitted
+  through herdr's activity gate (`agent prompt --wait` — new `wait:`/
+  `timeout_ms:` options on `HerdrExecutor#agent_prompt`), so success proves
+  observed working activity rather than a mere submission. A lab is `ready`
+  only when every session (lab overseer included) has its first turn
+  confirmed; an unconfirmed delivery keeps `prompt_failed: true` with a
+  visible reason instead of a ready declaration. On a repeated start, a live
+  reused agent is distinguished from a completed start through the existing
+  herdr session state: working/blocked = mid-conversation (never
+  interrupted); idle/done = the first-turn prompt is re-delivered through
+  the existing session, repairing missing initialization without restarting
+  anything; an unclassifiable state stays visibly unconfirmed.
+- The lab space title is namespaced to `lab-overseer` (review 8xtiatf4): a
+  project rooted at a directory literally named `lab` owns the session/space
+  title `overseer-lab`; the old lab space title collided with it. Session
+  labels (`overseer-<root>`) are unchanged.
+- Workspace ids dig with exactly ace-herdr's canonical keys
+  (`workspace_id`/`workspaceId`, review 8xtiatf2) — no broader key guessing.
+- Auto-mode binstub use is again root-guarded (review 8xtiatf3): `start`
+  passes `prefer_project: !Process.uid.zero?` to the toolchain executable
+  resolver, so root never executes a project-owned `bin/` binstub (installed
+  mode ignores the flag).
+- A project cascade declaring `scope: lab` is refused per-project (review
+  8xthrjsm) — a nested lab start never recurses. The topology read rescue is
+  narrowed to `Ace::Lab::InvalidConfigurationError` (review 8xthrjsn) so
+  programming errors surface instead of becoming "topology could not be
+  read" blocks.
+
 ## [0.26.1] - 2026-10-25
 
 ### Changed

data/docs/usage.md

@@ -16,8 +16,9 @@ ace-docs:
 
 ## Command Surface
 
-Local work uses five primary commands (`projects` lists configured lab projects):
+Local work uses six primary commands (`projects` lists configured lab projects):
 
+- `ace-overseer start` - start or reuse the project overseer session from configuration.
 - `ace-overseer work-on` - prepare a worktree, assignment, and terminal.
 - `ace-overseer handoff` - hand the task worktree to the next role in the prepared sequence.
 - `ace-overseer process-reports` - interpret ace-hitl reports and continue the queue.
@@ -29,6 +30,217 @@ launcher are removed in L1 and are not normal paths. Status and prune read
 local assignment/task/worktree/Git state only; there is no journal, attempt or
 authority execution model. tmux and Herdr are transports, never state owners.
 
+## `ace-overseer start`
+
+Run `ace-overseer start` at a shell in the Lab's existing Herdr `overseer`
+space. The command becomes the Lab's Pi agent directly in that same terminal
+and cwd, without any Herdr environment, agent, owner or layout preflight. The agent receives the packaged Lab guide
+and a first-turn prompt to delegate configuration of commissioned projects
+using installed CLI, skills and normal configuration editing.
+
+No local start YAML is required for first run. The packaged bootstrap profile
+is `pi`, `zai/glm-5.3-flash`, thinking `high`, in Lab scope. An explicit start
+section overrides bootstrap and is validated without fallback. For an
+explicit project start use:
+
+```yaml
+# .ace/overseer/config.yml (project tier of the cascade)
+start:
+  scope: project            # project | lab
+  profile: overseer-default # reference into the profiles map below
+  instructions: wfi://overseer/start  # handbook source (or absolute file path)
+profiles:
+  overseer-default:
+    harness: pi
+    model: zai/glm-5.3-flash
+    thinking: high
+```
+
+| Option | Purpose |
+|--------|---------|
+| `--dry-run` | Show the start plan; no session, no sync, no model call |
+| `--format` | `table` (default) or `json` |
+| `--reconcile` | Explicitly reconcile project children after the agent configures the Lab; never restart the coordinator |
+| `--scope` | Explicit `lab` or `project` role; an unconfigured bare start bootstraps the Lab |
+
+Behavior:
+
+- The project root is canonical: a subdirectory, a symlinked checkout, and a
+  linked worktree of one repository resolve to the SAME owner, so one project
+  never runs two whole-project overseers.
+- Session identity is Herdr's: the tab/pane label `overseer-<project>` on the
+  caller's herdr workspace. A live owner pane is REUSED (`status: reused`); a
+  live pane whose cwd resolves elsewhere is a conflict (`status: blocked`,
+  never taken over); a dead owner pane is replaced and the new identity is
+  reported (`replaced_pane`).
+- The guide resolves through the normal handbook chain (`wfi://` sources via
+  the project's `ace-nav`; absolute paths verbatim) and boots the harness
+  agent as standing instructions with the configured profile. The `ace-nav`
+  binary follows the repo toolchain policy: auto mode prefers the project's
+  `bin/` binstub for a NON-ROOT caller and falls back to PATH, while
+  `ACE_TOOLCHAIN=installed`
+  always uses the installed gem launcher — a checkout inside the project is
+  data, never the runtime source. Because
+  `herdr agent start` success only means the interactive agent is ready for
+  input, the start submits a first-turn prompt right after the agent starts —
+  the session actually begins its first turn (state read, `/eyes` arming).
+  Delivery is confirmed through herdr's activity gate (`agent prompt
+  --wait`): success means observed working activity, so the turn began. A
+  delivery failure after a started agent never reports the start as failed:
+  the report stays `started` with `prompt_failed: true` and a repairable
+  warning. On a later start, a live reused agent ready for input gets the
+  first-turn prompt re-delivered through the same gate (repairing a missing
+  initialization without restarting anything); a working/blocked agent is
+  never interrupted, and an unclassifiable state stays visibly unconfirmed.
+- The report carries `status` (`started|reused|blocked|dry_run`), `scope`,
+  `root`, `label`, `workspace`, `pane`, `agent`, `profile`, `instructions`
+  (`source` + resolved `path`) and a `message`. Exit 0 only for a ready
+  start/reuse (dry-run included); a blocked start is a CLI error naming the concrete invalid configuration
+  or unavailable capability.
+- The started overseer coordinates and delegates (guide:
+  `wfi://overseer/start`); it never substitutes for a missing coworker.
+
+### Project-local bundles
+
+In auto mode each project owns its Gemfile/lock and binstubs. Child starts
+clear parent Bundler/Ruby injection and select the project's bundle.
+
+Explicit `ACE_TOOLCHAIN=installed` is preserved instead: the installed
+Toolchain launcher and gem closure start the child without reading its
+Gemfile or executing its binstub. Missing installed dependencies fail visibly;
+there is no fallback to checkout code. Terminal backend selection does not
+change toolchain mode.
+
+The lab overseer delegates bundle/configuration preparation to a lab worker;
+it never edits the project's binstub or installs gems itself. Follow
+`wfi://overseer/bootstrap-delegation` for the task, worker, independent
+verification and observed completion cycle. `ace-coworker start` prints a
+brief; a separate Herdr agent launch and first prompt are required.
+
+### Lab scope (8xs.t.pu0.a)
+
+`scope: lab` in the LAB coordination directory's own `.ace/overseer/config.yml`
+selects the Lab role. Bare `start` launches the foreground harness;
+`start --reconcile` is the explicit tool the agent uses after configuring its
+projects. Reconciliation manages project children without restarting or probing
+the Lab coordinator. The older full orchestration operation remains available
+explicitly through `start --scope lab`:
+
+
+- The project list and CANONICAL locations come from the existing ace-lab
+  topology (`topology.projects` id/path, read internally — the public
+  projection keeps its no-paths allowlist; locations are never derived from
+  an id/label/repo name). The lab root is a coordination directory with its
+  own `_overseer`; a directory declaring itself as both lab and project is
+  refused, and a project whose own cascade declares `scope: lab` is refused
+  per-project (a nested lab start never recurses). An unreadable topology
+  (missing or unparseable `.ace/lab/config.yml`) is a blocked start with
+  the concrete cause.
+- The lab creates/reuses its own herdr space (`overseer`, reserved for the Lab) and boots or
+  reuses the lab's OWN overseer session there (label `overseer-<lab-root>`,
+  cwd at the lab root, the lab guide as standing instructions, first-turn
+  prompt included) — the lab-start instructions always reach a real agent,
+  and an empty configured project list still runs the lab overseer (idle).
+- EACH project then starts or is found through its own bundle and the SAME operation as a
+  standalone start (its own cascade, root, and session identity) in its OWN
+  herdr space, titled by its topology id (for example `ace`) and
+  created/reused by title by the lab flow — project sessions are isolated
+  from each other and from the lab overseer, never share one space, and
+  never re-resolve the caller's ambient workspace (a plain terminal without
+  a herdr pane works). The per-project report carries its space id; a live
+  session found in another workspace is reused and reports that workspace
+  without creating an empty space. herdr spaces are flat (no parent/child
+  nesting): the lab context owns the per-project spaces by creating and
+  reusing them from this one start flow.
+- Statuses: `ready` (all projects started/reused AND every first turn
+  confirmed delivered — the lab overseer's included; an empty configured
+  list is a valid idle lab once its own session is initialized), `partial`
+  (an unhealthy project — or a session whose first turn failed or stays
+  unconfirmed — is reported with its concrete reason while healthy projects
+  run — never false success), `blocked` (unreadable topology / conflicting
+  roles). A repeated start repairs only what is missing: healthy sessions
+  are reused, manual panes are never closed, nothing healthy is restarted,
+  and a reused session that is ready for input gets its first-turn prompt
+  re-delivered through herdr's activity gate (`agent prompt --wait`) to
+  confirm or repair initialization; a working/blocked agent is never
+  interrupted, and an unclassifiable one stays visibly unconfirmed.
+- `--dry-run` lists the plan (space + per-project would_start) and creates
+  nothing. The report carries per-project results (`projects`), the count,
+  and the lab-level readiness; exit 0 for ready, non-zero for partial and
+  blocked. The lab guide (`wfi://overseer/lab-start`) binds the lab
+  overseer to cross-project coordination, delegation to project overseers,
+  and per-project escalation.
+
+## `ace-overseer observe`
+
+Read-only standing observation the started overseer's eyes poll (task
+8xs.t.pu0.3). The projection merges the six local source classes, each read
+from its state owner — never a second task/assignment state:
+
+- HITL events (semantic revisions; reports/questions toward this owner),
+- project tasks and private `_overseer` tasks (`ace-task`),
+- worktrees (`ace-git-worktree`),
+- coworker availability and assignment progress (`ace-coworker` probe over the
+  `ace-assign` inventory; live/stale judged by existing run identifiers —
+  commissioned assignment ids — never pane names).
+
+Every row carries a stable `key` and a `revision` that changes only when the
+owner's data changes: identical state projects identical revisions (healthy
+silence consumes zero model turns), and a real change wakes the observer once.
+A failing source degrades ONLY itself — it contributes a `source-health` row
+whose revision is keyed by the failure class (an identical repeated failure
+never re-wakes; a new failure mode wakes once) while the healthy sources keep
+projecting. `sources` maps each source to `ok`/`degraded`. After a restart,
+pending revisions reconcile before new work is chosen, so a report that
+arrived during the overseer's absence is recognized exactly once.
+
+### Remote PR observation
+
+Configure the observed pull requests in the same cascade (task 8xs.t.pu0.4)
+— the project's own declarations, never a scan of every accessible account:
+
+```yaml
+# .ace/overseer/config.yml
+observe:
+  remote:
+    pull_requests:
+      - server: github-cs3b   # configured git server (ace-git ServerRegistry)
+        number: 398
+```
+
+Rows project through the EXISTING forge provider adapters (Forgejo and
+GitHub — `Ace::Git::Providers.for`; no separate HTTP client, no webhook
+service). Each configured PR contributes two rows: its lifecycle (`pr:` —
+new HEAD via `head_sha`, merge, close, reopen, title/draft) and its activity
+(`pr-activity:` — the sorted identity set of reviews and comments, so a new
+review, formal approval or comment revises once while re-ordered payloads and
+volatile counters never do). Row payloads carry the wake facts: forge, PR
+number/title, event kind, author and link. Technical polling of identical
+state projects identical revisions — zero model turns.
+
+A failing forge (401/403, rate limit, timeout, malformed payload) degrades
+only its source (`source-health` marker keyed by failure class: one wake per
+failure mode, never an empty healthy list); retry/backoff stays inside the
+provider adapters. After access returns, the changed state is recognized
+through its normal revision. Remote data stays data: re-read the current
+state and evidence before any merge decision. CI check changes are
+information, never a merge gate.
+
+### Cold-cycle acceptance (8xs.t.pu0.e)
+
+`wfi://overseer/cold-cycle-acceptance` binds the end-to-end acceptance of
+the whole family: explicit preconditions (a fresh runtime from the
+PUBLISHED set — a missing dependency is a readiness failure, never a
+binstub fallback), the run's non-interference contract (the operator only
+answers decisions/OTP), the ONE identity axis every acceptance record
+captures (task → assignments/roles + auth leases → HITL case/suggestion/
+decision/lesson → PR+HEAD → head-bound review/tests → publish versions+
+digests → installed runtime paths + target-account result → record PR), the
+mandatory negative flow (refuse one install step after publish: no done, no
+record, correct escalation; resume the same cycle without re-publishing),
+and re-run idempotence (a start after closure re-publishes, re-delegates
+and re-applies nothing).
+
 ## `ace-overseer work-on`
 
 Create or reuse local worktrees and prepare one assignment.
@@ -348,3 +560,15 @@ ace-overseer prune --dry-run
 ace-overseer prune --yes
 ace-overseer prune --dry-run
 ```
+
+### Workspace names and foreground instructions
+
+Topology IDs reserve workspace titles for the commissioned lab projects.
+Reconciliation may reuse an existing workspace with that title, but never
+replaces its manual panes; project ownership is the stable overseer tab label
+plus canonical cwd, not the mutable terminal title. Ambiguous ownership blocks.
+
+Foreground bootstrap pins the two built-in start guides to their packaged
+files. An explicit custom instruction source remains configurable; missing
+files block before launching Pi. Project development dependencies do not select
+the operational runtime when installed mode is chosen.

data/handbook/workflow-instructions/overseer/bootstrap-delegation.wf.md

@@ -0,0 +1,88 @@
+---
+name: overseer-bootstrap-delegation
+description: Delegate project startup to lab workers and accept their observed results
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Delegated Project Bootstrap
+purpose: Complete one lab-owned startup commission without the overseer doing the repair.
+---
+# Delegated project bootstrap
+
+## Commission and ownership
+
+Read existing tasks and assignments first. Reuse the open commission for the
+same project and goal; unknown execution state never means free capacity.
+Create one lab coordination task in `_overseer`, with three direct children:
+prepare, independently verify, confirm start. The latter two depend on their
+predecessor. Only the lab overseer updates this private tree.
+
+Create a separate executable lab task through `ace-task` for the bootstrap
+work, linking it as the manager's `project_task`. Keep its specification in
+its task folder. Include the canonical target repository path, required
+configuration, allowed changes, runtime mode, acceptance checks and report
+recipient. This is lab infrastructure work, not a project product task.
+Workers must not edit the private coordination tree.
+
+Explicit `ACE_TOOLCHAIN=installed` remains installed in every subprocess,
+worker and resumed session. The project checkout is domain data. Never modify
+tracked binstubs to bypass this selection. In auto mode retain the project's
+own dependency model. If package code is defective, commission its repair;
+do not patch installed gems. Preserve unrelated changes.
+
+## Arm eyes before dispatch
+
+Use the lab's existing eyes JSON configuration. The `ace_eyes` tool accepts
+`{"action":"start","configPath":"<absolute eyes JSON path>"}`.
+Inspect the returned state: enabled=true, breaker=null, errors=0 and at least
+one observation. Read pending revisions from their original owners, reconcile
+existing commissions, and ack each exact key/revision only after acceptance.
+A missing extension, invalid configuration or degraded source blocks dispatch;
+report that capability gap. Do not claim that mentioning `/eyes` armed it.
+
+## Prepare and actually launch a worker
+
+Use `ace-coworker prepare --task <executable-task> --roles bootstrap-worker,bootstrap-verifier
+--to <configured-overseer-address> --format json`. Read its returned worktree,
+assignment IDs and start-config paths; record these on the matching private
+steps before launch. A preparation readiness report is not worker completion.
+The task must be present in the execution worktree before any agent starts.
+
+`ace-coworker start --config <returned-path>` validates and prints a brief;
+it does NOT launch an agent. Use the configured Herdr provider/profile to
+start a separate worker agent in the returned worktree, load the returned
+role instructions, and send its first prompt. The prompt commissions only
+that task and pinned assignment, requires the worker to read its start brief,
+drive that assignment, and finish with `ace-coworker report`. These operational roles explicitly allow the commissioned canonical target
+outside the lab task worktree; ordinary product worker/reviewer roles do not.
+Use CLI help for
+Herdr's current arguments. Record the returned pane/agent identity and verify
+first-turn delivery. Never replace a missing executor with your own work.
+
+End the overseer's turn immediately after dispatch. The eyes timer observes
+assignment and HITL revisions without invoking the model on unchanged state.
+
+## Receive, verify, start
+
+On wake, read the original report and current assignment. Require matching
+report ID, task, assignment and role; a preparation report, process exit or
+unmatched message is not success. Use `ace-overseer process-reports --dry-run`
+to inspect the matching and continuation before applying it. Only accept
+worker success with a completed non-empty assignment and the promised evidence.
+Record receipt through task APIs before acknowledging the eyes revision.
+
+Use the existing role handoff gate to prepare the independent reviewer after
+worker completion. As with the worker, a printed start command is not a live
+agent: launch the reviewer separately with its own returned role/config and
+confirm first-turn delivery. Do not launch a second executor while an earlier
+one is active or its state is unknown. On repeated delivery, reconcile existing
+assignments and agents instead of dispatching again.
+
+After accepted independent verification, the overseer performs its coordination
+operation `ace-overseer start --reconcile`. Confirm the target's session, first
+turn and active eyes from actual session evidence. A ready process alone is
+not initialized observation. Close the confirmation step and managing task
+only with these proofs; the worker report alone cannot close the family.
+
+On error, keep the step open and route repair to the worker. Missing authority
+or an actual Captain decision becomes a precise HITL question; end the turn
+armed for its answer. Never self-repair or use sleep-poll while waiting.

data/handbook/workflow-instructions/overseer/cold-cycle-acceptance.wf.md

@@ -0,0 +1,95 @@
+---
+name: overseer-cold-cycle-acceptance
+description: The repeatable cold-start full-cycle acceptance scenario — two projects, one delegated task, HITL with a Second Captain suggestion, independent review, merge, publish, install, record; negative install refusal and idempotent re-run
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Cold-Cycle Acceptance Scenario
+purpose: Bind the end-to-end acceptance of the autonomous lab family (8xs.t.pu0): explicit preconditions, one identity axis for every handoff, the operator's non-interference contract, a negative install flow, and re-run idempotence — executed on the installed, published set only.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Cold-Cycle Acceptance Scenario (8xs.t.pu0.e)
+
+## Goal
+
+Prove that every handoff composes into ONE autonomous cycle on the
+INSTALLED lab: a cold start with at least two configured projects, a task
+carried by real delegation through spec/planning, worker execution, an HITL
+question carrying a Second Captain suggestion, independent review, merge,
+publication, installation, runtime acceptance under the target account, and
+the integrated record. The operator presses START and answers ONLY the
+decisions/OTP the Captain must give — no further prompts, no pasted
+answers, no manual deploy.
+
+## Preconditions (explicit, NOT hidden autonomy)
+
+- A fresh runtime from the PUBLISHED set: every component (core, wake
+  extension projection, all three auth plugins) comes from installed gems —
+  a missing dependency/runner/projection is a readiness FAILURE, never
+  permission to fall back to the checkout's binstubs (`ACE_TOOLCHAIN=installed`).
+- `ace-lab install` converged the manifest (gem closure, exact versions,
+  extension projections); `ace-lab verify` passes under the target accounts.
+- At least two configured projects (one carries the task; the other proves
+  isolation); accounts, keys and auth profiles prepared by install.
+
+## Run
+
+1. `ace-overseer start` in the lab directory (scope lab). Expect: lab space,
+   both project overseers started/reused, per-project statuses.
+2. State the goal with acceptance criteria to the lab overseer (one explicit
+   message). From here the operator only answers HITL.
+3. The overseer accepts the goal, delegates spec/planning through the
+   EXISTING roles, records the task, and drives dependencies to acceptance —
+   delegation is proved by role/assignment evidence, not by the overseer
+   doing the work.
+4. Worker executes with a developer lease (`ace-lab auth request → use →
+   revoke`); reviewer with a reviewer lease (identity DISTINCT from the
+   author); integrator with an integrator lease and the formal approver
+   account from the configured lane.
+5. The required HITL decision carries a marked Second Captain suggestion in
+   the SAME case BEFORE the Captain answers; only the human answer releases
+   the gated step (the suggestion never does). An OTP ask is `--secret`: the
+   value never appears in any wake, log, or argv.
+6. Merge only through the gate: HEAD-bound tests, HEAD-bound independent
+   review verdict, HEAD-bound formal approval by a different account; the
+   adapter's expected-head condition refuses drift.
+7. Publisher releases from the published queue (resume by version+digest);
+   install converges the runtime; runtime acceptance runs UNDER THE TARGET
+   ACCOUNT with the actually installed paths/versions.
+8. The record (`wfi://release/cycle-record`) integrates through a reviewed
+   record-only PR; the task closes only after acceptance AND record.
+
+## The one identity axis (the acceptance record)
+
+Every handoff names the SAME verifiable chain — capture the real values, no
+fabricated suffixes: task id → assignments/roles (worker/reviewer/integrator
++ auth lease ids per role with principal/scope/use_until/expiry_mode) →
+HITL case id (suggestion id, decision revision, lesson) → PR + merged HEAD →
+review/tests evidence (heads, commands, results) → publish versions +
+digests → installed runtime paths/versions + target-account result → record
+PR. Producer → consumer at every step; command success alone proves
+nothing.
+
+## Negative flow (mandatory)
+
+After a successful publish, REFUSE one required install step (e.g. remove
+one manifest dependency or the extension projection). Expect: no done, no
+ready, no record; the blocked state names the concrete missing dependency
+and the correct escalation addressee; healthy parts keep reporting. After
+restoring the cause, resume THE SAME cycle without re-publishing (matching
+version+digest = already published).
+
+## Re-run idempotence
+
+After the cycle closes, run `ace-overseer start` again: no re-delegation, no
+re-publication, no re-application of a closed decision; previously
+started/reused sessions stay; the answer-only replay of an applied decision
+is refused by the lifecycle.
+
+## Boundaries
+
+- Tests and scenarios live with their existing owners (ace-lab,
+  ace-overseer); no separate test service.
+- The scenario is repeatable: a second cold run produces the same evidence
+  shape with fresh identifiers.