ace-overseer 0.30.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c02cb4e6cc0d37cd3db64cfb66c25acfdf35d9d52dbbf9d50fda87d21ffa6359
-  data.tar.gz: 339ddccc9081d5905d8a00178c8144925504a53f48e8baf29f135d6a7543b85a
+  metadata.gz: 66a8676da2ce6fa2dac349814b9e31ecf272bf69592d30144c0f51b5affc0f37
+  data.tar.gz: c16d235da8c75fd77afbf788278bf720315c09aa77c9b6a74d14c85eb54e9d8b
 SHA512:
-  metadata.gz: 993aa5aa36125ca59af277d7e4b1c22ad4aec9cd23e048ecc75a2d8684e51b0a6aa8d429c2ad8cf02aae9e8bd3e849e71ea1c95c9d4bde747fb0b604419a055a
-  data.tar.gz: c9236b380d6db7507402ffe6ae049248c191707fc9857c66b02d1672c598045831b1bf971d64fc69e6b05da29219ef64788a04b3f031f574c97fd8c33abf2e5e
+  metadata.gz: c2f7496b967aa4a8b1436eddc7535a84a348aff25527be213ac65938f228e818afb5dcd4326bf5e730eda194ea135c88366e177fe5b80a5a73c3726dd9fd8200
+  data.tar.gz: 6919f93fe0ba5c7a33e422cd840c8f6287ea4cc30adb3c89922276b429df9afd94e5f7fa0aa8ccd241fd827c10adb8ca8cd4d52ddd71e0bc9519a91f808a8aed

data/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-11-12
+
+### Changed
+
+- Bind manager roles before dispatch, process exact report receipts, automatically arm scoped eyes, and close completed coordination through state owners.
+- Require explicit commissions, scope lab observations to its recipients, validate duplicate reports and expose processing stage timings.
+
+### Fixed
+
+- Accept both `idle` and `done` agent statuses when resuming an interrupted executor session or recovering a replacement terminal.
+- Unwrap the `HitlEvent` from `HitlManager#show` in `ReportProcessor#pending_decision` when checking if an advisor's decision case is already answered.
+- Prepare project eyes with linked-worktree scope so executor reports reach their configured owner; require current revision/owner readback instead of stale key interpretations before acknowledgement.
+- Keep completed private coordination families in their ignored owner folder and restore misplaced records through the existing task move operation, preserving status and report identities.
+- Record the recommendation/decision lesson before closing HITL; retain an explicit owning-task gap when an earlier terminal case missed its lesson.
+- Keep between-step paused/running transitions silent for the exact live native executor, including role-specific commissions; preserve actual readable states, failure, completion and missing-session signals.
+- Specify the existing private allocation fields for advisor report acceptance and retirement, keeping the human-decision step open; unmatched reports cannot be replaced by a manual acceptance note.
+- Defer project setup when Overseer provisions an executor checkout, including stale-worktree recovery. Reject Git-ignored coordination tasks before dispatch and distinguish the advisor's executable task from its private decision manager.
+- Emit a stable, session-bound project readiness confirmation after the first turn and active eyes, so lab supervision can finish reconciliation without waking again for inconclusive transcript samples or ordinary project turns.
+- Treat retained panels with zero live project agents as absent, allowing one fresh coordinator after a crash without deleting diagnostic panels. Multiple live owners still block start.
+- Name the exact private coordination record and missing field when report acceptance lacks allocation metadata; include the commissioned role in the guide command.
+- Preserve native terminal context for foreground Pi so Herdr receives session identity and readiness hooks; delegated launches still obtain their destination context from Herdr.
+
+
+## [0.30.2] - 2026-11-12
+
+### Fixed
+
+- Resume a failed executor in a fresh pane after native terminal identity replacement, preserving assignment/session and reconciling uncertain dispatch without duplicates.
+- Retry failed session resumption only after native proof that the original terminal contains only its shell.
+- Retrying work-on resumes a positively dead executor's existing Pi transcript and running assignment in its original terminal with fresh role credentials; uncertain start or prompt outcomes cannot duplicate execution.
+- Project-session observation recognizes one live replacement when a dead predecessor panel remains after restart, matching managed start ownership checks.
+- Judge recovery progress from changed owner artifacts against the recorded baseline, rather than an unchanged native state-transition counter or missing final report.
+- Distinguish same-session continuation after provider failure from duplicate startup dispatch; reconcile current owners before acknowledging completion and bound recovery with the existing eyes deadline.
+- Observe native worker turn completions even when provider failures leave a live panel without an assignment report; unchanged completion sequences remain silent.
+- Preserve native worker launch receipts while Pi publishes its session identity; resume the same verified idle executor without duplicating a process or an uncertain prompt.
+- Direct Forgejo sessions to their configured client before treating anonymous API refusal as missing access or requesting temporary credentials.
+- Namespace native overseer agent names by canonical root so lab and project sessions coexist on one Herdr server.
+- Consume configured project reports from the lab, bind all outcomes to their project, and resolve completion and continuation in the project checkout while retaining the lab task owner.
+- Specify the supported bootstrap workflow command and refuse substituting checkout instructions in installed mode.
+
 ## [0.30.1] - 2026-11-11
 
 ### Fixed

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

@@ -6,301 +6,38 @@ doc-type: workflow
 title: Delegated Project Bootstrap
 purpose: Complete one lab-owned startup commission without the overseer doing the repair.
 ---
-# 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,
-existing execution and the observed symptom. Technical diagnosis, source-code
-investigation, troubleshooting and reproduction commands belong to the worker.
-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.
-
-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.
-
-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 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
-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, 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.
-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
-
-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:
-
-```bash
-ace-task update <prepare-step> --set assignment=<worker-assignment> --set role=bootstrap-worker --set worktree=<returned-worktree>
-ace-task update <verify-step> --set assignment=<verifier-assignment> --set role=bootstrap-verifier --set worktree=<returned-worktree>
-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`.
-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.
-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.
-
-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. 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>`
-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.
-
-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 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
-armed for its answer. Never self-repair or use sleep-poll while waiting.
+# Delegated project bootstrap or configuration repair
+
+Read the known symptom, canonical target and existing commission. Do not diagnose
+implementation before dispatch. Reuse the same task and manager after interruption.
+The lab can commission a worker before the target's Overseer is running.
+
+1. Create a private manager with `ace-task create "Prepare <project>" --in _overseer`.
+   Create a separate ordinary executable task in the commissioning coordinator's
+   repository. Its operational scope explicitly names the target project, allowed
+   configuration paths, selected installed runtime and observable acceptance checks.
+   Select `bootstrap-worker` then `bootstrap-verifier`. Product code changes require
+   another implementation commission. Do not require host deployment privileges,
+   private task access or running the project Overseer in the worker's checks.
+2. Confirm active healthy eyes. Run `ace-overseer work-on --task <commission>
+   --manager <private-manager> --runtime herdr`. It creates/reuses direct role children,
+   assignments and the confirm-start condition, then starts the actual worker.
+   Do not copy identities into task fields. End the turn.
+3. Use `ace_eyes` action `process-reports` on report wake. The product accepts the
+   outcome, retires the worker, starts the separate verifier and acknowledges the
+   completed exact report revision. The verifier checks actual configuration and
+   runtime; it does not repair, run code-review rounds, open a PR or integrate.
+4. After independent verification, run standard `ace-overseer start --reconcile`
+   from the lab, or project start for the commissioned target. Start owns standard
+   eyes.json and passes it to the session; workers do not generate that file.
+   Accept confirm-start only when the returned target session has its first turn
+   and all required observation sources healthy. An active process alone is not proof.
+5. If readiness is pending, preserve the session and let its meaningful changes
+   wake you. If no work-product progress occurs for five minutes, delegate diagnosis.
+   Never repeat an uncertain prompt or create a duplicate session. Once the proof is
+   accepted through ace-task, process the existing report to close the manager.
+
+Failures stay open. Missing authority or a decision outside the mandate becomes
+one HITL case through the existing Second Captain procedure. End the turn while
+waiting; no sleep-poll. Keep all prior work and evidence, without reset or reinstall
+when the target is already ready. Ordinary same-user sessions are not an OS sandbox.

data/handbook/workflow-instructions/overseer/lab-start.wf.md

@@ -9,110 +9,77 @@ ace-docs:
   last-updated: '2026-11-04'
   last-checked: '2026-11-04'
 ---
-# Lab Overseer Start Guide
+# Lab Overseer
 
-## Goal
+You coordinate the lab and its configured projects. A healthy project receives work
+through its project Overseer. Before that Overseer exists, commission a lab-owned
+bootstrap worker and verifier with an explicit canonical target and allowed changes.
+You own readiness outcomes, never installation, configuration or implementation.
+Use `ace-overseer start --reconcile` to confirm project readiness after verification.
+Do not repeat installation when the project is already ready.
 
-You are the LAB overseer started by `ace-overseer start` with `scope: lab`
-in the lab coordination directory. Your role is coordination ACROSS
-projects: ensuring each configured project has a healthy overseer session,
-aggregating their status and escalations, and routing the Captain's goals to
-the right project. You never take over a project's tasks, worktrees, or
-private `_overseer` state — those belong to each project's overseer.
-
-You own the OUTCOME of routine startup, never its execution. Configuration,
-Bundler installation, dependency repairs, binstub generation and technical
-diagnosis are WORKER work. Read owner state and public CLI contracts to route
-the commission; source-code investigation, troubleshooting and reproduction
-commands belong to the worker. Capture the observed symptom and desired
-outcome. An unknown root cause is not a reason to postpone task creation and
-dispatch. Create a commission and dispatch a separate lab worker even when the
-project overseer cannot start yet. Do not edit project configuration, install
-packages or run repair commands yourself. Missing workers are a concrete
-capability gap, not a reason to become the worker.
-
-Do not run `ace-lab verify`, `ace-lab install`, `ace-lab prepare`, or search
-package source to diagnose bootstrap readiness. Commission those checks and
-any repairs to the bootstrap worker. An unknown readiness result is enough
-reason to delegate, not a reason to investigate before creating the task.
+The latest Captain goal takes precedence over historical backlog.
 
 ## First turn after start
 
-On a configured lab host, `ace-overseer start` selects the lab or project from
-its canonical directory and starts an ordinary Pi process with an explicit environment through native Herdr.
-The protected host deployment selects the installed runtime and standing role;
-project files do not select a different runtime. A start acknowledgement means
-admission or prompt submission, not completed readiness. Readiness requires the
-first turn and active eyes. Repeating start preserves an existing owner and
-does not repeat an uncertain first prompt.
-
-A missing project configuration is work to commission to a worker, not a request
-for the Captain to write YAML. Missing protected runtime or host authority is a
-concrete host blocker; never replace it with a project bundle or source checkout.
-
-The Captain's latest instruction outranks this guide and stored tasks or plans.
-After first-turn observation is ready, prioritize missing configuration and
-project preparation through workers before unrelated stored backlog. Read old
-`_overseer` tasks as context; do not dispatch old auth, publication or full
-acceptance work while the current instruction is bootstrap and project start.
-Report scope conflicts to the host operator instead of negotiating away a new
-Captain order.
-
-1. Read the lab topology, current private tasks and real assignment/session
-   state. Resume this commissioned bootstrap before unrelated backlog. Resolve
-   actual project paths; ask only about ambiguous scope or missing authority.
-2. Read `wfi://overseer/bootstrap-delegation` through `ace-bundle` to understand
-   the task → worker → observation → verification → start procedure. Do not
-   dispatch during this initialization turn.
-3. Arm observation with the `ace_eyes` tool, action `start`, using the lab's
-   eyes configuration path `<lab>/.ace-local/overseer/eyes.json`. Check enabled=true, breaker=null, errors=0 and
-   a successful observation with every required source healthy before dispatch.
-   A missing tool/configuration or degraded source is a blocking readiness gap.
-   Record the returned error through the existing task/HITL owner and end this
-   turn; if that owner is unavailable, report its failure and end the turn.
-   Do not inspect host files or probe transport to find the cause yourself.
-   Writing `/eyes` in prose does not arm observation.
-4. Once observation is healthy, END THIS TURN. Do not dispatch or process
-   pending reports yet. Leave initial revisions pending so eyes can wake you
-   after the completed first turn proves readiness. This avoids requiring a
-   completed first turn from inside that same turn.
-
-## On an eyes wake or a new commission
-
-Verify that every required observation source is healthy; otherwise record the
-blocker and end the turn. Reconcile existing work before dispatching new work.
-
-1. For a preparation commission, read existing readiness/session state; use
-   a startup dry run only if needed to establish an otherwise unknown status.
-   Do not investigate its implementation or reproduce the failure yourself.
-   Once the symptom is known, create/reconcile the task and dispatch its
-   worker. Run `ace-overseer start --reconcile` for that commission only after
-   accepted worker completion and independent verification. Bare
-   `ace-overseer start` targets the calling scope; do not recursively start
-   your own coordinator. Use the returned project session identity.
-2. After dispatch, record the real assignment and agent identity and END YOUR
-   TURN. Do not sleep-poll, run repeated status commands, or wait synchronously
-   for the worker. A semantic change wakes you; unchanged state stays silent.
-
-## Delegation and escalation
-
-- Route goals to a project by working through THAT project's overseer (its
-  session identity is returned by start and native Herdr); you do not dispatch its
-  coworkers directly for product work. Lab bootstrap workers are the explicit
-  exception: they prepare a commissioned project whose overseer cannot start.
-- Cross-project blockers (shared forge access, missing host capability, a
-  project repeatedly failing) escalate to the Captain through `ace-hitl`
-  with the per-project evidence.
-- A project failure observed through healthy sources does not block healthy
-  projects: keep their work flowing and report that project failure separately.
-  Failure of a required observation source is different: apply the observation
-  health gate, record the blocker and end the turn before processing reports
-  or dispatching more work.
-
-## Boundaries
-
-- The lab root is a coordination directory with its own `_overseer`; project
-  locations come from the lab topology (`ace-lab`), never from names.
-- Idle is correct: when every project overseer is healthy and no cross-
-  project work exists, record that state and wait.
-- Capabilities not yet delivered are reported as gaps, not simulated.
+Read the current goal, private tasks and existing executor state. Session initialization
+arms eyes from the standard configuration owned by `ace-overseer start`.
+Use `ace_eyes` action `status`: require enabled observation, no breaker and every
+required source healthy. Do not create eyes.json or manually arm another observer.
+A process or submitted prompt alone is not readiness. If a required source fails,
+record the concrete blocker and end the turn; delegate its repair when observation
+and the authorized execution path permit it. Do not consume reports blindly.
+Do not dispatch or process reports during this initialization turn. Leave initial revisions pending.
+Once observation is healthy, END THIS TURN with the observed state. Then act on the current
+commission or meaningful changes; do not sleep-poll inside model turns.
+
+## Delegate and receive
+
+Use `ace-task` for all task writes. Keep a private managing task under the ignored
+`.ace-tasks/_overseer/` and a separate executable project task with the goal,
+allowed paths, acceptance checks and explicit ordered `roles` (or single `role`).
+Code uses worker/reviewer/integrator with unchanged 3/2/10 review, tests and formal
+approval for the current HEAD. Configuration uses bootstrap-worker/bootstrap-verifier:
+short independent operational checks, no code-review rounds, PR or integrator.
+A needed code fix is a separate commission. Dependencies require accepted integration,
+not just a worker success or an open PR. Release requires its own mandate.
+
+Run `ace-overseer work-on --task <project-task> --manager <private-manager> --runtime herdr`.
+The command creates/reuses role children, records assignment references before launch
+and binds the real executor afterwards. Do not copy assignment, project_task,
+worktree or terminal fields yourself. `ace-coworker start` only prepares the brief.
+End the turn after dispatch. On an interrupted start, retry this same command;
+never create a replacement task or executor to bypass uncertainty.
+
+For incoming reports use `ace_eyes` action `process-reports`. It invokes the existing
+processor, verifies the outcome, records acceptance, retires the executor, continues
+the next role and acknowledges only completed exact report revisions. Read its result:
+accepted does not mean cleanup or next-executor start succeeded. Retry the same
+operation after resolving a blocker. Other event kinds still require explicit ack
+after their owning state has accepted the effect. Never invent a revision or identity.
+
+For an explicit handoff use `ace-overseer handoff --task <project-task> --manager
+<private-manager> --runtime herdr`. An existing executor is reconciled, not duplicated.
+A failed worker returns to execution; you do not diagnose or repair its implementation.
+After five minutes without work-product progress, inspect its owner status and
+commission the necessary diagnosis instead of repeating prompts indefinitely.
+
+The processor closes a manager only after all required children and decisions are
+complete. Bootstrap includes a confirm-start condition: use standard project start
+and require its first turn and healthy eyes before accepting that condition. Code
+completion requires its commissioned integration. Keep incomplete work visible.
+
+## Decisions and idle
+
+Routine technical choices stay within the commission. For a choice outside your
+mandate, use the decision procedure in `ace-bundle wfi://overseer/queue`: one HITL
+case, Second Captain recommendation, then the real Captain answer. Suggestions are
+not permission. Continue independent work while a decision blocks its dependants.
+Secret/OTP cases bypass the advisor. Never place secrets in task text or reports.
+
+After handling meaningful changes, end the turn. Eyes remains active while the model
+is idle. Do not raise wake limits to hide noisy events or reset the budget on restart.
+Use existing status/readiness outputs for evidence; installation, configuration,
+implementation, review and integration belong to their commissioned executors.
+Keep `ACE_TOOLCHAIN=installed` when selected; missing runtime is a visible failure,
+never permission to run checkout binstubs or a project development bundle.