ace-overseer 0.28.1 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d96c79ae10f470e6358022f081234f5080eba56cd58353471a33aa6f187e0c5
-  data.tar.gz: 5e4eadc41222d3448b57f938ad5c2716b1941ddfe7b800479d69a6a3f72f3cb9
+  metadata.gz: 92f8ba410b2086914103a468bc9592cb2f1638f228e8f04bbc9050c1acb72eaf
+  data.tar.gz: acd533702789417b67b6f3c318f20256c5e0c0f62851f7f447b07fb9bf1368c1
 SHA512:
-  metadata.gz: f9fdda6024283fd16b8be35da318b7e4eb6a85574ef623cc1395c4c7af0d77fc1971a541bb2a28abe3a6ce7a6d52f1c04df442c69eaff53e09f7d3974b6b89e3
-  data.tar.gz: 4fe70abfe425a0c399763c790125f391bbca8099f5a96e4a24677047148fc4b7e1c578ae976853195a28f1e5306500e259de498a491601e241e1c82e1b514c91
+  metadata.gz: 4c6f234b40b3953e1106919d62a89ece41fb3acbae42d09476a1d6685eeb029ed691bb4d9007300aca87fc1eeb91e620fb5a50b45bde4b6f2c773863cd12a7e8
+  data.tar.gz: 8094e9edbd30cceca456ae18b8f768a956e60006188e617c9aa359efabd7a454b4e6fd2842d34fee39b12ccdc68bc844cf02156e408a2f5437e091791aa965b5

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-11-11
+
+### Added
+
+- Select installed toolchain from overseer configuration without shell setup; derive child Herdr socket from the configured session runtime.
+
+## [0.29.0] - 2026-11-10
+
+### Added
+
+- Start real workers from work-on/handoff, persist native executor identities on existing commissions, and require active observation before delegation. Accept reports before retirement and continuation through worker, reviewer and integrator roles; refuse duplicate or uncertain starts. Build explicit installed environments, select per-project observation credentials, and observe issue bodies/labels plus project sessions. Verify first-turn/eyes evidence on Linux and macOS; delegate configuration and diagnosis in packaged instructions.
+
 ## [0.28.1] - 2026-10-31
 
 ### Fixed

data/README.md

@@ -16,7 +16,7 @@
 
 > **State owner:** the private, gitignored overseer task list in
 > `.ace-tasks/_overseer/`, a normal task folder reached through
-> `ace-task --in _overseer …` (see [docs/lab-flow.md](../docs/lab-flow.md)).
+> `ace-task list --in _overseer` (see [docs/lab-flow.md](../docs/lab-flow.md)).
 > Task worktrees live in `.ace-wt/`; assignment plans and steps stay in
 > `.ace-local/assign/` (ace-assign) and are never copied into the overseer
 > list.
@@ -80,7 +80,7 @@ or create your own.
 > assignment sequence -- not available yet.
 >
 > **L6 (partial):** the private overseer queue is coordinated through the
-> gitignored `.ace-tasks/_overseer/` list (`ace-task --in _overseer`):
+> gitignored `.ace-tasks/_overseer/` list (`ace-task list --in _overseer`):
 > managing tasks with lifecycle subtasks (prepare, implement, review,
 > integrate), integration-gated dependencies, and one active executor per
 > worktree. See the

data/docs/getting-started.md

@@ -10,7 +10,7 @@ ace-docs:
 # Getting Started with ace-overseer
 
 > **State owner:** `.ace-tasks/_overseer/` (private, gitignored task folder
-> reached via `ace-task --in _overseer`) and `.ace-wt/` (one worktree per
+> reached via `ace-task list --in _overseer`) and `.ace-wt/` (one worktree per
 > project task). Assignment plans stay in `.ace-local/assign/`. See
 > [docs/lab-flow.md](../../docs/lab-flow.md).
 

data/docs/usage.md

@@ -10,7 +10,7 @@ ace-docs:
 # Usage
 
 > **State owner:** `.ace-tasks/_overseer/` (private, gitignored task folder
-> reached via `ace-task --in _overseer`) and `.ace-wt/` (one worktree per
+> reached via `ace-task list --in _overseer`) and `.ace-wt/` (one worktree per
 > project task). Assignment plans live in `.ace-local/assign/` and are not
 > copied here. See [docs/lab-flow.md](../../docs/lab-flow.md).
 
@@ -84,14 +84,16 @@ Behavior:
   `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.
+  Herdr's activity gate (`agent prompt --wait`) only confirms working
+  activity. Readiness also requires the completed first turn and fresh,
+  healthy eyes evidence tied to the current live Pi process and session. A
+  delivery failure after a started agent does not remove that agent:
+  the report stays `started` with `prompt_failed: true` and an uncertain
+  delivery warning. A later start never re-sends the prompt solely because a
+  reused agent is idle or done: either state can follow a delivered prompt.
+  A healthy reused session can become ready once its current observation is
+  verified; a blocked agent is never interrupted. Process identity evidence
+  currently supports Linux only; other systems remain 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
@@ -153,17 +155,14 @@ explicitly through `start --scope lab`:
   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
+  completed with live, healthy eyes — 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.
+  roles). Repeated start reuses live sessions and never closes manual panes.
+  A reused session remains unconfirmed without trustworthy first-turn and
+  current-process observation evidence. No first prompt is re-sent automatically.
 - `--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
@@ -174,7 +173,7 @@ explicitly through `start --scope lab`:
 ## `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
+8xs.t.pu0.3). The projection merges local source classes, each read
 from its state owner — never a second task/assignment state:
 
 - HITL events (semantic revisions; reports/questions toward this owner),
@@ -182,7 +181,10 @@ from its state owner — never a second task/assignment state:
 - 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).
+  commissioned assignment ids — never pane names),
+- configured project Overseer session states from `ace-lab` project locations
+  and Herdr. Session activity is a wake signal, not proof that project eyes
+  are armed; inspect the session for that evidence.
 
 Every row carries a stable `key` and a `revision` that changes only when the
 owner's data changes: identical state projects identical revisions (healthy
@@ -190,11 +192,13 @@ 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,
+projecting. Recovery revises the same row to `ok` and wakes the observer
+even if the work is unchanged. `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
+### Remote issue and 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:
@@ -203,11 +207,25 @@ Configure the observed pull requests in the same cascade (task 8xs.t.pu0.4)
 # .ace/overseer/config.yml
 observe:
   remote:
+    issues:
+      - server: forgejo-lab  # the configured project repository
     pull_requests:
       - server: github-cs3b   # configured git server (ace-git ServerRegistry)
         number: 398
 ```
 
+Each configured issue source observes the selected repository's open issues
+as one collection. New, changed and closed issues change its semantic
+revision, while reordered identical results do not. Read the current issue
+before acting. The revision covers issue identity, title, state, author, URL
+and available labels; issue comments are not observed by this source. A
+listing with more than 500 open issues, an unsupported
+provider, or an authentication failure degrades the source visibly rather
+than treating a partial or unavailable list as complete. Session credentials
+must be available to the observation command for the duration of observation.
+Currently the Forgejo provider implements issue listing; GitHub does not.
+The Forgejo listing does not currently expose labels to this observation.
+
 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:` —
@@ -221,8 +239,8 @@ 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
+provider adapters. After access returns, the source health revision wakes
+the observer. Remote data stays data: re-read the current
 state and evidence before any merge decision. CI check changes are
 information, never a merge gate.
 
@@ -348,9 +366,13 @@ Matching and outcome rules (enforced mechanically):
   it `done`, then continues with the next unblocked step (same
   `DependencyReadiness` gate as `work-on`): `ace-overseer handoff` for the
   next role when the family records a worktree, otherwise the `work-on`
-  gate. A refused continuation is reported as blocked with reasons. The
-  handoff outcome carries the actionable start command (the same one the
-  Handoff CLI prints); the window is ensured, the agent runs the command.
+  gate in local terminal mode. A refused continuation is reported as blocked
+  with reasons. Local handoff ensures the window and returns the start command.
+  With the Herdr backend, work-on and handoff start the actual executor with
+  an explicit environment and record its identity on the coworker commission.
+  Accepted reports retire that executor before continuation. A completed role
+  sequence does not close pending coordination steps. No authorization daemon
+  or isolated operating-system session is required.
 - A repeated delivery of an already-processed report is `duplicate`: the
   recorded result and existing allocation answer it; nothing re-runs
   (delivery repetition is never work repetition). A duplicate whose

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

@@ -8,6 +8,12 @@ purpose: Complete one lab-owned startup commission without the overseer doing th
 ---
 # Delegated project bootstrap
 
+If tool output truncates any instruction, reload this workflow with
+`wfi://overseer/bootstrap-delegation --output cache --compressor off` and read
+the returned file before proceeding. In installed mode run `ace-bundle`; in
+an ACE source checkout in auto mode use its `bin/ace-bundle`. Never infer a
+missing deadline or command.
+
 ## Commission and ownership
 
 The overseer reads owner state and public CLI contracts to establish scope,
@@ -17,6 +23,9 @@ Record the known failure and desired outcome in the commission; discovering
 the root cause is part of the assigned work, never a prerequisite for dispatch.
 Use existing readiness state, or a startup dry run only when that state is
 otherwise unknown. Do not turn that check into a technical investigation.
+Run every `ace-*` command directly, without a pipe, redirection or output
+post-processing. Record its actual exit status; if it prints a path, read the
+file. A pipeline's exit status cannot establish that an ACE operation passed.
 Once the symptom is known, proceed to task creation/reconciliation, observation
 and worker dispatch, then end the turn.
 
@@ -26,15 +35,119 @@ 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
+From the lab root, use the explicit private-folder selector when creating
+the manager; a title or `lab-coordination` tag does not select its location:
+
+```bash
+ace-task list --in _overseer
+ace-task create "Bootstrap <project> readiness" --in _overseer --tags bootstrap,lab-coordination
+ace-task create "Prepare <project>" --child-of <manager-ref>
+ace-task create "Independently verify <project>" --child-of <manager-ref>
+ace-task create "Confirm start <project>" --child-of <manager-ref>
+ace-task update <verify-ref> --add dependencies=<prepare-ref>
+ace-task update <confirm-ref> --add dependencies=<verify-ref>
+ace-task show <manager-ref>
+ace-task list --in _overseer
+```
+
+Use the full task IDs returned by the commands, not abbreviated references.
+Children inherit the parent's location.
+Before dispatch, verify the manager and its three direct children resolve
+under `<lab>/.ace-tasks/_overseer/` and are gitignored. A manager in the public
+task root does not satisfy this contract. Reconcile its location through the
+task owner's public CLI before dispatch; do not create a duplicate commission
+or treat a successful worker report as proof that the manager is private.
+
+Create the executable bootstrap task through `ace-task` in the target project's
+canonical root, linking it as the private lab manager's `project_task` and
+recording `project_root`. Keep its specification in its project task folder.
+Run executable-task creation, lookup, coworker preparation and role handoff
+from that project. Run private coordination-task updates from the lab root.
+Shell calls do not retain a preceding call's working directory. The worker receives
+only the project mount and cannot read lab-private tasks. The lab's installed
+observation reads configured project assignments and reports from their owners;
+records remain in the project rather than being copied into lab state. Include the canonical target repository path, required
 configuration, observed failure, desired outcome, allowed changes, runtime
 mode, acceptance checks and report recipient. Assign diagnosis and reproduction
-as well as preparation to the worker. This is lab infrastructure work, not a project product task.
-Workers must not edit the private coordination tree. Resolve each task folder
-from `ace-task show <ref>` before writing commission, dispatch or receipt notes;
-never construct a folder from a guessed or expanded title slug.
+as well as preparation to the worker. This task describes infrastructure setup within the project, separate from its product issue backlog.
+
+The preparation and verifier acceptance checks stop at a validated project
+configuration and readiness to start. Do not require a running project
+Overseer, a first turn, or active project eyes in either worker assignment:
+those are the coordinator's confirm-start checks after verification. Workers
+must not start the project Overseer themselves. This prevents a circular gate.
+Worker/verifier checks must be executable with their commissioned session's
+permissions. Validate the prepared configuration, installed CLI/gem paths and
+owned project files. `ace-lab prepare`, `ace-lab install` and `ace-lab verify`
+operate on the host deployment manifest even from the project directory.
+The host operator owns them. Never include these commands in a project
+commission or dispatch prompt, including as a dry run or acceptance check.
+Name the exact project configuration files to prepare or validate and the
+installed executable paths to check. If host convergence is required, record
+the missing capability and route it to the host operator.
+Do not require host D-Bus or systemd inspection, reading either overseer's
+private task tree, or a healthy full `ace-overseer observe` projection from a
+worker session. Those checks belong to the host or overseer role. The private
+task tree is the coordinator's responsibility; ordinary same-user sessions do
+not promise operating-system isolation from it.
+Commission task-store checks for the worker or verifier in the execution
+worktree. The project Overseer can audit its canonical private task store
+after start. A worker reports
+missing authority and the exact blocked check instead of repairing host services
+or attempting to access the coordinator's private state. The coordinator proves
+full observation from the authorized project Overseer during confirm-start.
+`ace-coworker status` describes one commissioned executor, not whether a
+project can host an Overseer. A canonical project without a default coworker
+commission is not a bootstrap defect. Do not require or create a canonical
+`.ace-local/coworker/config.yml` merely to make that query ready, and never copy
+a worktree commission into another checkout where its assignment cannot resolve.
+Read an executor's status in its returned worktree with its returned `--config`.
+A configuration parse, exit zero or absence of the words "not ready" is not
+proof of readiness: require the intended identity and resolved assignment.
+Do not require a worker or verifier to rerun `prepare` as an acceptance check
+while its assignment is active. Preparation coordinates executors; its active
+executor conflict is not a configuration validation result. Accept project
+configuration through its own documented schema and installed runtime checks.
+
+The commission must include the target project's eyes configuration path
+`<project>/.ace-local/overseer/eyes.json` and
+the project Overseer's configured HITL recipient for its own eyes, separately
+from the lab recipient that receives bootstrap reports: the worker prepares the configuration
+and the independent verifier checks it before project start. Missing or
+ambiguous recipient information is a blocker, never a guessed address. The
+project Overseer arms the prepared configuration; it does not create or edit it.
+Describe the required project observation and recipient in the commission.
+Leave configuration syntax to the executor and its installed validator.
+`scope: project` belongs to the Overseer start configuration. For the eyes
+JSON, use `"scope": "current"` to observe the current project and set
+`"recipient"` to that project's configured recipient. Add sync routes only
+when the commission requires them.
+The project's private task directory is `<project>/.ace-tasks/_overseer`;
+never require or create a top-level `<project>/_overseer` directory.
+
+Put all commission and supporting files in the executable task's own tracked
+folder, never in the private `_overseer` tree. Before preparing its worktree,
+commit those files and the task specification using the task/commit tools.
+
+Resolve the executable task in its owner checkout and use the returned
+file's parent directory:
+
+```bash
+cd "<canonical-project-root>" && ace-task show "<project-task-id>" --path
+```
+
+If lookup reports not found, check the command's working directory and the
+task ID from the create result. Correct the lookup once. If it still fails,
+record the blocker on the private coordination task and end the turn.
+Check `git status --short -- <task-directory>` in the project: uncommitted
+or untracked supporting files will not appear in the new worktree.
+
+After preparation, verify every referenced commission file exists in the
+returned worktree before launch. If one is missing, report a preparation
+failure and keep the worker unstarted.
+Workers must not edit the private coordination tree. Resolve each task
+folder from its owner's checkout before writing commission, dispatch or
+receipt notes. Use the returned path even when it differs from the title slug.
 
 Explicit `ACE_TOOLCHAIN=installed` remains installed in every subprocess,
 worker and resumed session. The project checkout is domain data. Never modify
@@ -44,8 +157,12 @@ 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>"}`.
+Use the lab's existing eyes JSON configuration, including its configured
+project observations. Start it once with the `ace_eyes` tool using
+`{"action":"start","configPath":"<absolute eyes JSON path>"}`. If eyes is
+already armed for the same configuration, read `{"action":"status"}`
+and reuse the running observer. A worker-to-verifier handoff does not
+require rearming an observer that remains healthy.
 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.
@@ -54,8 +171,28 @@ 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,
+Read the lab's armed eyes configuration to identify the commissioning
+coordinator's recipient, then resolve that address in the target project's
+HITL configuration. Use the target configuration's key for THAT same lab
+address, not its project Overseer address. Lab and project coordinators must
+have distinct configured addresses, with absolute folder paths when using
+folder-form addresses. A relative `.ace-local/hitl` repeated across roots does
+not identify which coordinator owns the report. The task specification, `--to`, and returned start configs
+must agree; do not invent an address or append a machine suffix. If no valid
+recipient is configured, report a blocking gap before dispatch.
+
+Bootstrap uses `reporting.delivery: observe`. The recipient is
+a report address, not permission to edit the coordinator's private tasks. Executors publish
+with `ace-coworker report` in their assignment worktree. Lab eyes observes that
+publication on the project side and the Lab Overseer accepts it. Neither
+commission may require the worker or verifier to find, touch, or write the
+Lab Overseer's inbox (for example `/lab/.ace-local/hitl`). Check the configured
+address in the start brief, and prove publication and acceptance at the
+report handoff after execution. Do not turn inbox access into a prerequisite
+for project preparation.
+
+From the target project root, use `ace-coworker prepare --task <executable-task> --roles bootstrap-worker,bootstrap-verifier
+--to <configured-lab-recipient> --format json`. Read its returned worktree,
 assignment IDs and start-config paths; record these on the matching private
 steps before launch through the task API, not only in prose:
 
@@ -65,6 +202,12 @@ ace-task update <verify-step> --set assignment=<verifier-assignment> --set role=
 ace-task update <confirm-step> --set role=confirm-start
 ```
 
+Start-config paths returned by preparation are relative to the returned
+execution worktree, not the canonical project root. Pass the returned path with
+that worktree as cwd, or join it to that worktree for an absolute path. Verify
+that exact file exists before dispatch; use the same rule for the verifier's
+handoff config. Never replace its base directory with the canonical project.
+
 Read back the steps with `ace-task show` and verify exact returned identities.
 A preparation readiness report is not worker completion. It does not complete
 any of these three steps; never label bootstrap execution as `role=planner`.
@@ -72,47 +215,91 @@ Only a separate, explicitly commissioned planner preparation allocation may
 accept an unassigned readiness report.
 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.
+`ace-coworker start --config <returned-path>` validates and prints a brief.
+Launch the first prepared leg with `ace-overseer handoff --task <executable-task>
+--runtime herdr` from the target project. This operation starts the actual
+process in the returned worktree with the role's explicit environment and
+records its native identity on the existing commission. No prompt file,
+service setup or shell workaround is needed from the coordinator.
 
-End the overseer's turn immediately after dispatch. The eyes timer observes
-assignment and HITL revisions without invoking the model on unchanged state.
+Record the returned terminal and assignment on the matching private step.
+End the turn with eyes armed. A repeated command reuses recorded work or
+reports an explicit blocker; an uncertain start must not be bypassed by
+another dispatch. Worker or observation failure is delegated/escalated,
+never repaired by the Lab Overseer.
 
 ## 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.
+unmatched message is not success. The observation carries `project_root` and
+the original report ID; read the report and `ace-coworker status` through their
+public CLI in that project/worktree. Only accept worker success with a completed
+non-empty assignment and the promised evidence. The private coordination tree
+stays in the lab: do not run a project-local report processor against lab task
+IDs or infer completion from a report file alone.
 Record the actual accepted HITL event ID and result in step metadata through
 `ace-task update <step> --set processed_report=<event-id> --set report_result=<result>`
-(or let `process-reports` perform that same write after its dry run is checked).
-Mark done only after acceptance; errors keep the step open. Receipt notes in
+using the lab task owner.
+Mark done only after acceptance; errors keep the step open. If the executor
+observation loses the recorded terminal while its assignment is incomplete,
+verify the absence in Herdr and record the interruption before reconciling
+that assignment. A disappeared session cannot complete a bootstrap leg. Receipt notes in
 the path returned by `ace-task show` supplement these fields, never replace them.
 Read back the recorded identity before acknowledging the eyes revision.
 Never put a preparation readiness ID on a worker, verifier or confirm-start step.
 
-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 accepting the worker's report, use `ace-overseer process-reports` to
+retire its recorded executor and continue the prepared sequence. Preserve
+the exact report and assignment identity before starting the verifier.
+Do not launch a second executor while a predecessor is active or unknown.
+Repeated reports reconcile the same commission; they do not repeat the work.
 
 Only after accepted worker completion and independent verification does the
 overseer perform this commission's project-start 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.
+turn and active eyes through that command's native-session readiness result.
+For the target project, `ready=true` proves the matching session's
+first turn and active eyes; a terminal's `done` or `interactive_ready` alone
+does not. Record the returned target identity and readiness on confirm-start.
+
+When the target returns `ready=false`, preserve its session. Arm one eyes
+first-turn deadline (`key=confirm-start-<project-id>`, `revision=<terminal-id>`,
+`at=now_unix_ms + 60000`) and end the turn. On a project-session revision or
+that deadline, rerun `ace-overseer start --reconcile` from the lab root once.
+It reuses the existing session and checks its evidence without resending the
+prompt. Cancel the deadline when readiness is confirmed. The deadline is an
+observation checkpoint, not a startup failure threshold. If it fires while
+readiness remains false, reconcile the actual session activity through Herdr's
+public agent state. A matching session still working on its first turn remains
+pending: record that fact, acknowledge the handled project-session revision,
+cancel the consumed deadline and keep project-session observation armed.
+At this first pending checkpoint, arm one separate startup watchdog
+(`key=confirm-stall-<project-id>`, `revision=<terminal-id>`,
+`at=now_unix_ms + 1800000`) and record its identity on confirm-start before ending the turn. Never
+rearm it on subsequent revisions or after session resume. On its expiry,
+reconcile readiness and, if still unconfirmed, delegate diagnosis while
+preserving the existing session; elapsed time alone never authorizes restart.
+Cancel this watchdog when readiness is confirmed or diagnosis takes ownership.
+On the next project-session revision, check authenticated readiness again.
+Do not ask the Captain whether to keep
+waiting for an active session, repeatedly rearm deadlines or poll.
+
+If the session has finished its turn without readiness, exited, or is blocked,
+delegate diagnosis with the observed state and readiness result. Unknown
+activity or unavailable observation is an explicit unresolved state, never
+permission to launch a duplicate or declare success. Escalate only an actual
+decision or missing authority; ordinary first-turn latency needs neither.
+
+Do not read implementation files, inspect another session's private files, or
+infer another agent's eyes from your own `ace_eyes status`. The public readiness
+result is the proof boundary; inability to obtain it is a blocker for the
+executor to diagnose. Close the confirmation step and managing task only with
+these proofs; the worker report alone cannot close the family.
+If first-prompt delivery is unconfirmed, preserve the existing session and do
+not submit the prompt again. Inspect its actual activity and escalate an
+unresolved delivery through HITL. The project-session observation can wake you
+on a configured project's Herdr state change; that state alone does not prove
+the project has armed eyes.
 
 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