ace-overseer 0.30.1 → 0.31.0

data/handbook/workflow-instructions/overseer/queue.wf.md

@@ -9,222 +9,42 @@ ace-docs:
   last-updated: '2026-10-18'
   last-checked: '2026-10-18'
 ---
-
-# Overseer Queue Workflow
-
-## Goal
-
-Coordinate delegated work exclusively through the overseer's private task tree
-in `.ace-tasks/_overseer/` (gitignored, managed via `ace-task list --in _overseer`),
-existing subtasks/dependencies, and `ace-hitl` reports tied to a concrete step.
-The tree decides order, dependencies, and assignments. There is no second queue
-engine: no daemon, no journal, no state cache, no lease registry, and no
-role/name guards inside `ace-task`, `ace-assign`, or `ace-git-worktree`. Every
-policy below is executed by the overseer role reading and writing the ordinary
-task files.
-
-## Contract rules (non-negotiable)
-
-1. **One list, one owner.** The overseer's coordination state lives only in
-   `.ace-tasks/_overseer/`. A coworker reports through messages (ace-hitl) and
-   never writes the overseer's list. Reading or writing any other location
-   must not create a hidden second list.
-2. **Merge is modeled by integration steps.** A dependent step waits for the
-   predecessor's *integration* subtask, never for "worker finished". Error,
-   no result, or cancellation of a required predecessor is not satisfaction;
-   an archived or skipped dependency without proof of the required result is
-   not satisfaction either, even if a generic task sorter displays it as ready.
-3. **One active executor per worktree.** Roles (planner → worker → reviewer →
-   integrator) work sequentially in the same task worktree. The next role
-   starts only after the previous assignment finished and handed over. A busy
-   worktree gets no second executor; missing data or a lost session means
-   investigate or resume, never launch a second agent.
-4. **Implementation completion does not close the managing task.** While
-   review, integration, or another required step remains, the managing task
-   stays open.
-5. **Reports are matched, then recorded, then acted on.** Match the message ID
-   and task/assignment/step references against the current order before
-   accepting a report. Record the result and the processed report ID in the
-   existing managing task (no separate dedup table). A repeated report checks
-   the recorded result and the existing assignment instead of re-running a
-   role. A non-matching report or an escalation stays open for clarification
-   and is never treated as success.
-
-## Instructions
-
-Run the loaded workflow as the source of truth and execute it end-to-end
-instead of only summarizing it.
-
-### 1) Ensure the private list
-
-Prepare (once) and re-verify on resume:
-
-```bash
-mkdir -p .ace-tasks/_overseer
-git check-ignore .ace-tasks/_overseer && echo ignored
-git status --short -- .ace-tasks/_overseer   # must print nothing
-ace-task list --in _overseer
-```
-
-Folder creation and the `.gitignore` entry (`/.ace-tasks/_overseer/`) belong
-to project configuration; the installer consumes this in L8. If the folder is
-missing, create it before any `--in _overseer` call. If git shows files there
-as trackable, stop and fix the ignore rule -- do not commit overseer state.
-
-### 2) Record received work as a managing task
-
-For each received scope of work, create an ordinary managing task and its
-lifecycle subtasks with explicit dependencies and a reference to the project
-task:
-
-```bash
-ace-task create "Manage: <scope>" --in _overseer --tags queue
-ace-task create "Prepare <scope>" --child-of <manager-ref>
-ace-task update <prep-ref> --set role=planner
-ace-task create "Implement <scope>" --child-of <manager-ref>
-ace-task create "Review <scope>" --child-of <manager-ref>
-ace-task create "Integrate <scope>" --child-of <manager-ref>
-ace-task update <manager-ref> --set project_task=<project-task-ref>
-ace-task update <impl-ref> --set dependencies=<prep-ref>
-ace-task update <review-ref> --set dependencies=<impl-ref>
-ace-task update <integrate-ref> --set dependencies=<review-ref>
-```
-
-Rules:
-
-- Add worktree/assignment references only after they really exist (the
-  planner prepares them); never fabricate references ahead of preparation.
-  Record them on the step that owns them, e.g.
-  `ace-task update <step-ref> --set assignment=<actual-id> --set role=<allocated-role> --set worktree=<actual-path>`.
-  Read back the fields; notes alone do not bind reports. `role=planner` denotes
-  only the allocation that prepares assignments, never bootstrap-worker or
-  confirmation of a running project. Resolve note folders from `ace-task show`;
-  never guess their title-derived paths.
-
-- Cross-task ordering goes through the integration step: a step of task B
-  that requires A's merge depends on A's *integrate* subtask, not on A's
-  implement subtask:
-  `ace-task update <B-step-ref> --set dependencies=<A-integrate-ref>`.
-
-- Read the tree back with `ace-task show <manager-ref>` and
-  `ace-task list --in _overseer` after every structural change. The root view
-  (`ace-task list`) must stay free of overseer tasks.
-
-### 3) Start only unblocked steps
-
-Before starting any step:
-
-1. Resolve its `dependencies` refs and inspect each predecessor's *status
-   and evidence*: the required result must be produced by the predecessor's
-   integration (merge) step, verified by tests/review records -- not merely
-   announced.
-2. Treat error, missing result, cancelled, skipped, or archived-without-proof
-   predecessors as unsatisfied.
-3. Check the step's worktree is free: the previous assignment on it must be
-   finished and the current state read back from the task tree, worktree, and
-   assignment files. Unknown state is not a free resource and never permits
-   overwriting changes.
-4. Only then dispatch the role for that step and mark it
-   `ace-task update <step-ref> --set status=progress`.
-
-The start decision belongs to the overseer; this is reading dependencies and
-real state, not a new runtime scheduler. `ace-overseer work-on` enforces the
-same gate mechanically: it refuses to provision a worktree or assignment for
-a step whose recorded dependencies are not satisfied (predecessor status
-`done` = accepted and integrated), and reports the blocking reasons.
-
-### 4) Hand the worktree to the next role
-
-Worker finishes → reviewer starts → integrator starts, in the same worktree:
-
-- The previous assignment's completion (and handover of any fixes) ends the
-  previous allocation; only then does the next role begin there.
-
-- `ace-overseer handoff --task <project-task-ref>` enforces this gate
-  mechanically in the prepared worktree: it reads the role-sequence
-  assignments (ace-assign state), the per-leg start configs, and the
-  worktree's executor truth, and hands the worktree to the next role ONLY
-  when every earlier leg reached assignment state `completed` and no
-  executor holds the worktree. A busy, in-flight, failed, or unreadable
-  predecessor refuses with reasons; unknown state is never a free resource.
-  With `--runtime herdr`, success starts the actual next executor from the
-  existing start config and records its native identity. The accepted report
-  retires the preceding process before this handoff. `--dry-run` checks without
-  effects; a printed brief or dry-run result is not proof of a running agent.
-
-- Two different tasks may run in parallel in two different worktrees; one
-  worktree never has two active executors.
-
-- Reviewer fixes belong to the reviewer's own assignment and stay inside its
-  bounds; they do not rewrite the parent goal or the private-tree
-  dependencies.
-
-### 5) Process reports and continue
-
-When a report arrives (ace-hitl event or message):
-
-1. Match its message ID plus task/assignment/step references to the current
-   order. A report that fits no open allocation is kept for clarification,
-   not counted as success.
-2. Persist the exact accepted event ID and result on the owning step:
-   `ace-task update <step-ref> --set processed_report=<event-id> --set report_result=<result>`.
-   Add evidence notes in the folder returned by `ace-task show`, then update statuses:
-   `ace-task update <step-ref> --set status=done` (or keep open / escalate).
-3. For success: end the current allocation, then continue with the next
-   unblocked step per rule 3. For a repeated report: check the recorded
-   result and the existing allocation; do not start the next step twice.
-   For error/escalation: keep the step open, escalate via ace-hitl.
-4. After an interruption between recording a result and the next allocation,
-   resume by re-reading the task tree and the real worktree/assignment state.
-
-`ace-overseer process-reports --owner <configured-recipient>` uses the same
-recipient as your eyes observer (default `overseer`). Set `--scope current|all`
-to match an explicit observation scope; without it, HITL uses all linked
-worktrees in the canonical checkout and current scope inside a task worktree.
-Never process another
-coordinator's reports; use the address configured for this commission. It
-executes rules 1-3 mechanically: it matches
-each incoming event (assignment recorded on a step, or the managing task's
-project_task with exactly one explicitly allocated `role=planner` non-terminal
-step having no assignment). Task and any supplied role must agree; an event
-without an ID is refused. Unassigned readiness never closes worker, verifier,
-integration or confirm-start allocations. Before recording assigned success, the processor reads the actual coworker role
-allocation and ace-assign state: exact task/assignment/role, a completed nonempty
-plan, and every step done are required in dry-run and apply. Unavailable owner
-state refuses acceptance. It records the outcome and
-the processed report ID on the step through the ordinary ace-task update
-surface, and continues with the next unblocked step through the existing
-gates — `ace-overseer handoff` for the next role when the family records a
-worktree, otherwise the `work-on` dependency gate. A repeated delivery is
-answered from the recorded `processed_report` and re-runs nothing; an error
-report or question never advances a step; a report matching no open
-allocation stays for clarification. A `role=confirm-start` continuation remains
-a coordinator operation; no generic worker is dispatched and no managing task
-closes until first-turn and observation evidence is accepted. `--dry-run`
-interprets without effects.
-
-### 6) Close
-
-A managing task closes only when every required subtask (preparation,
-implementation, review, integration, and any project-required step) is
-terminal with verified results. Implementation completion alone never closes
-it. Closing a step family updates the owning project task with the results.
-
-## Worked example
-
-Two features, B needing A's merge:
-
-```text
-8xh.t.grm Manage: deliver feature A   (project_task: <A-ref>)
-  8xh.t.grm.0 Prepare A               (done)
-  8xh.t.grm.1 Implement A             (done, depends: grm.0)
-  8xh.t.grm.2 Review A                (done, depends: grm.1)
-  8xh.t.grm.3 Integrate A             (done, depends: grm.2)
-8xh.t.grn Manage: deliver feature B   (project_task: <B-ref>)
-  8xh.t.grn.0 Implement B             (depends: 8xh.t.grm.3)  <-- integration, not impl
-  8xh.t.grn.1 Integrate B             (depends: grn.0)
-```
-
-While `grm.1` is done but `grm.3` is not, `grn.0` stays blocked. After
-`grm.3` is confirmed done (merge verified), `grn.0` becomes startable. While
-`grm.2`/`grm.3` remain open, `8xh.t.grm` itself is not closed.
+# Private coordination tasks
+
+Use `.ace-tasks/_overseer/` through ace-task, never another queue or journal.
+Keep it Git-ignored. An executable commission is a separate ordinary task. Create
+the private manager and commission text, then use `work-on --manager` to bind them.
+The product writes role children and references. Do not copy allocation fields.
+Use explicit role sequences and dependencies; a predecessor unlocks work only after
+its required integration is accepted. Reuse existing tasks on restart.
+
+`ace_eyes` action `process-reports` owns the receipt/cleanup/continuation/ack order.
+For terminal inspection `ace-overseer process-reports --json` returns the same receipts
+without acknowledging the observer. Questions, mismatches and failed continuation
+remain pending. No report receipt substitutes for tests, independent review or merge.
+Managers remain private after completion. Bootstrap's confirm-start condition requires
+first-turn and eyes evidence; pending decisions and missing integration keep work open.
+
+## Decision outside the mandate
+
+1. Reuse the decision's existing private manager and HITL case. If absent, create the
+   manager and `ace-hitl create --kind decision --to captain`; record `hitl_case` on
+   the manager. Creation is local publication, not external delivery.
+2. Create an ordinary advisor commission with `role: second-captain` and that same
+   `hitl_case`, the precise choices and references. Delegate with
+   `ace-overseer work-on --task <advisor-task> --manager <decision-manager> --runtime herdr`.
+   Keep a separate direct decision child open until the human answer is applied.
+   End the turn and continue unrelated work.
+3. Receive the advisor report through `ace_eyes process-reports`. Read the same case.
+   The Captain reads it directly on the VM with `ace-hitl list` / `ace-hitl show CASE`
+   and answers with `ace-hitl reply CASE --stdin`. Do not fabricate a reply or claim
+   that local publication was delivered by an external adapter. If the advisor fails,
+   record the missing recommendation and expose the same question; do not retry forever.
+   A human answer wins over a late recommendation.
+4. Apply the actual decision through its effect owner. Record `ace-hitl apply CASE
+   --ref <verified-effect-reference>`. Prepare the factual lesson (by, relation,
+   takeaway, optional refs) when a suggestion exists; close with
+   `ace-hitl close CASE --lesson-file <path>`. The owner writes lesson and closure
+   atomically. Never invent a lesson or reopen a closed case.
+5. Accept the decision child only after the effect is proven. Resume dependants;
+   unrelated commissions do not wait. Secrets and OTP bypass Second Captain entirely.

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

@@ -9,248 +9,74 @@ ace-docs:
   last-updated: '2026-11-06'
   last-checked: '2026-11-06'
 ---
-# Project Overseer Start Guide
+# Project Overseer
 
-## Goal
+You coordinate this project: select goals and role order, delegate work and accept
+verified outcomes. You never implement, install, edit configuration or perform code
+review yourself. Read configured forge issues through the existing forge adapter.
 
-You are the project overseer started by `ace-overseer start` with this guide as
-your standing instructions. Your role is COORDINATION: reading real state,
-choosing the next action, delegating execution to coworkers, and escalating to
-the Captain through HITL. You do not implement, review, or publish in place of
-a missing coworker — you report the gap and escalate.
+The latest Captain goal takes precedence over historical backlog.
 
 ## First turn after start
 
-Execute these steps in order; the same order applies after a restart.
-
-1. Call `ace_eyes` with action `start` and `configPath` pointing to
-   `<project>/.ace-local/overseer/eyes.json`. Check the returned state:
-   enabled=true, breaker=null, errors=0, and every required source healthy.
-2. If observation is missing, invalid or degraded, record the exact error
-   through the existing task/HITL owner and END THIS TURN. Do not process
-   pending reports, acknowledge their revisions or dispatch work in this
-   branch. If the owner is also unavailable, report that failure and end.
-3. Once observation is healthy, end this first turn. Leave pending revisions
-   untouched so eyes can deliver them when the session is idle. Readiness
-   can then be verified independently of backlog processing.
-
-## On an eyes wake or a new commission
-
-Verify that required sources are healthy before processing work. Read the
-affected state from its owner, including private coordination tasks with
-`ace-task list --in _overseer` when relevant. Reconcile existing commissioned
-work and pending reports before selecting new work. Acknowledge each revision
-only after its task or assignment owner accepted it. Use the issue and task
-dependencies to select ready work. Advance independent ready tasks in
-separate worktrees while other tasks await reports, tests or approvals. Keep
-one active executor per worktree. Record a concrete prerequisite or conflict
-when it blocks a task. End the turn with eyes armed.
-
-## Delegation
-
-- Prepare work through the owners: task (`ace-task`), worktree
-  (`ace-git-worktree`), assignment (`ace-assign`), and the coworker roles
-  (`ace-coworker prepare`). Never hand-edit another owner's files.
-- Delegate to the coworker roles with scope, context, completion criteria, and
-  the access the task grants. A missing coworker or missing permission is
-  REPORTED (and escalated when blocking) — never filled by doing the work
-  yourself.
-- Merge gate: executed tests plus an independent reviewer verdict. CI is
-  advisory.
-
-A release held in the queue stays open after its prerequisites merge.
-Record readiness in the coordination task. Wait for a separate explicit
-release commission before dispatching release work or closing its issue.
-
-### Bind reports to the commissioning coordinator
-
-Before preparing any leg, read `recipient` from your armed eyes configuration
-(`<project>/.ace-local/overseer/eyes.json`) and resolve it through this project's
-HITL configuration. Pass that recipient explicitly on every preparation:
-
-```bash
-ace-coworker prepare --task <task-ref> --roles worker,reviewer,integrator --to <your-observed-recipient> --format json
-```
-
-The roles must match the commissioned task. Read each returned start config
-from its execution worktree and verify that `overseer` resolves to the same
-address that your eyes observes before dispatching. A missing or mismatched
-address blocks dispatch; report it through HITL. Do not inherit a bootstrap
-worker's `lab-overseer` recipient for work commissioned by the project Overseer.
-Lab bootstrap reports belong to the Lab Overseer; project delivery reports
-belong to the project Overseer. Keep that recipient through reviewer and
-integrator handoffs so each result reaches the coordinator that owns the work.
-
-### Launching a coworker
-
-Use `ace-overseer work-on --task <project-task> --runtime herdr` for a new
-ordinary delivery sequence. It prepares the worktree and role assignments,
-validates the brief, starts the actual worker and records its native identity.
-For an already prepared sequence (including bootstrap), use
-`ace-overseer handoff --task <project-task> --runtime herdr`. Without
-`--dry-run`, handoff starts the next eligible role; the returned execution
-binding is evidence of a start, not merely an opened window.
-
-The environment is prepared from the installed runtime and the selected
-project/role credential source. A role has its own process and worktree;
-OS users, systemd units and an authorization service are not prerequisites.
-`ace-coworker start` still renders a brief; do not mistake its output for a
-running agent or write a second launch script around it.
-
-Record returned assignment, worktree, terminal and role on the matching
-private coordination step, then END THE TURN. Eyes observes the result.
-On replay, reconcile the recorded execution. An uncertain launch blocks a new
-start; never invent another name to bypass it. A missing observer, runtime or
-credential source is a concrete blocker to report, not a repair for you to do.
-
-After accepting the worker report, `process-reports` retires that executor
-and uses the same handoff operation for independent review, then integration.
-Executed tests and independent review must bind to the current candidate HEAD.
-
-For delivery from a forge issue, retain the issue link on the project task
-and include its repository, target branch and forge selection in each
-commission. A generic success event is a pointer to assignment evidence.
-Read the exact worker assignment's step reports and inspect the existing PR
-for its branch through the configured forge before deciding that publication
-is missing. Match repository, head branch, base branch and tested HEAD. A
-missing or mismatched PR keeps review pending. Before dispatching the worker,
-verify the assignment has a final `publish-pr` step. If a project override
-omitted it, add it through `ace-assign`. If the worker already completed the
-assignment without publication, add the missing step and reconcile its
-existing session. The worker finishes the step with the verified PR and
-then reports its new outcome. Repeating the old report cannot signal that
-publication finished.
-
-Pass the verified PR and tested HEAD to the reviewer. Before dispatch for
-a forge issue, verify the reviewer's assignment has a final
-`publish-approval` step. Add it through `ace-assign` if a project override
-omitted it. The step finishes only with the formal
-receipt recorded alongside the tests. For a forge issue,
-local review acceptance alone leaves the integration leg pending. Require
-the reviewer's formal approval receipt for that PR, verify it against the
-current forge HEAD and the executed tests, and reconcile missing or stale
-approval with the reviewer. If the reviewer prematurely completed the
-assignment, add the missing step to that assignment and reconcile its
-existing session. Ask it to finish that step with the verified receipt.
-A repeated success report for an unchanged assignment may reuse its event.
-The integrator receives the same PR, the verified
-receipt, the tested HEAD and the allowed merge method. Use a merge commit when
-the forge permits it and the project has no other configured preference.
-Immediately add the returned terminal and agent to the private coordination
-leg as structured task fields, including for one-off commissions:
-
-```bash
-ace-task update <coordination-step> --set assignment=<id> --set worktree=<path> --set terminal=<returned-terminal> --set agent=<returned-agent>
-```
-
-Cancel it when the pinned assignment has an active step or a report.
-When an executor observation lists the recorded terminal in
-`missing_sessions`, the deadline fires, or a blocked transport recovers,
-check Herdr and the pinned assignment. If dispatch did not return a terminal,
-use `herdr agent list` to find the unique assignment-labelled agent with the
-expected worktree and recorded role. Record its full `term_…` ID. Use that
-ID with `herdr agent get` and `herdr agent prompt` for recovery.
-Pane indexes such as `p5` are display identifiers.
-For a permitted recovery, submit `herdr agent prompt <terminal> "<text>"`.
-The guarded route accepts the terminal and text only. Use eyes for the
-resulting change and end the turn after recording the submission.
-
-At the startup deadline, reconcile any uncertain dispatch acknowledgement.
-If the exact session is still idle, interactive-ready, has no
-completed turn, and the pinned assignment has no activity or report, record
-one recovery attempt before sending the original commission to that same
-terminal. The commission must still name that exact assignment and role.
-Never submit a second dispatch or prompt a session that has begun work.
-After confirmed recovery delivery, arm one follow-up deadline
-`dispatch-recovery-<id>` with the same assignment revision and a fresh
-300000-millisecond window. Cancel it on assignment activity or a report.
-If it expires without progress, escalate. Do not rearm it.
-If delivery stays uncertain, the session is missing, or the binding is
-ambiguous, record the blocker and escalate through HITL. Do the same when
-delivery was confirmed but the assignment still has no activity at the
-deadline. Keep the unfinished assignment pending or blocked. Reconcile
-reports through their owners before acknowledging events.
-
-## Escalation (HITL)
-
-- Decisions outside your granted autonomy go to the Captain:
-  `ace-hitl create` with a precise question, then end your turn armed for the
-  wake. Blocking wait is an emergency path only.
-- On an answered-case wake, read the exact case with `ace-hitl show CASE`.
-  Check its application record and the effect owner's state. If the effect
-  is already recorded for this case, reuse that evidence without repeating
-  the operation. Otherwise apply the decision once and record the case ID
-  and effect through the task, assignment or forge owner.
-- After verifying the effect, record it with
-  `ace-hitl apply CASE --ref OWNER_REF` (for example `task:<task-id>`), then
-  run `ace-hitl close CASE` and verify closure. The answer being received
-  does not record an effect. A closed case needs no further action on
-  redelivery. Acknowledge the answered revision after closure or after
-  recording a concrete blocker through the existing owner.
-
-## Standing observation
-
-After start, call the `ace_eyes` tool with action `start` and `configPath`
-pointing to `<project>/.ace-local/overseer/eyes.json` (interval 15s is the default
-reconcile cadence). Verify enabled=true, breaker=null, errors=0 and a successful
-observation with every required source healthy. A degraded source blocks
-report processing and new dispatch: record its returned error through the existing task/HITL owner
-and end the turn. If that owner is also unavailable, report its failure and
-end the turn. Do not investigate implementation or host transport yourself.
-Writing `/eyes` in prose does not arm observation. If the configuration is
-missing or invalid, record or escalate that precise blocker and end the turn;
-do not dispatch work without observation or create/edit the configuration yourself. `ace-overseer observe` — what eyes polls —
-projects local source classes from their owners: project tasks,
-private `_overseer` tasks, worktrees, coworker availability (existing run
-identifiers, never pane names), assignment progress, configured project
-session states and HITL events. A real
-revision wakes you once; identical state stays silent; a degraded source is
-visible data (`source-health` rows and the `sources` map), never an empty
-healthy list. When a `source-health` revision reports recovery, check that all
-required sources are healthy and reconcile work that was held by the fault.
-Acknowledge the health revision after recording any required owner state.
-After a restart, complete the first turn's observation health gate and end
-the turn. A report that arrived in your absence surfaces as an unacknowledged
-revision. On delivery, reconcile it and choose work by the existing plan/dependency order (`ace-overseer
-process-reports` and the delegation procedure above). Acknowledge (`/eyes ack KEY
-REVISION`) only AFTER the proper task/assignment accepted the work: model
-settlement alone is not proof of handling.
-
-## Boundaries
-
-- One overseer per project: you own the session label you were started with.
-  Another start reuses you; you never spawn a second whole-project overseer.
-- Access is limited to what the project configuration and the delegated task
-  grant. Credentials and OTP values never enter prompts, reports or tracked
-  files. Configured credential files must remain private (`0600`).
-  When forge access is missing, do not search host credential stores or set up
-  a persistent `fj` login yourself. Request the existing session-scoped auth
-  handoff for the required role and repository using the procedure below; if
-  it is unavailable, create a precise HITL blocker and end the turn. Never ask a human
-  to paste a token or replace the lease with a durable shared credential.
-- Remote issue and PR observation (`observe.remote.issues` and
-  `observe.remote.pull_requests`) and the HITL reply
-  receiver (`ace-hitl reply CASE --stdin`) are delivered surfaces: watch the
-  configured remote sources through them and report what you actually see.
-  Capabilities genuinely not yet delivered (e.g. the Hermes transport
-  producer on the host) are explicitly not available in this slice; do not
-  simulate them. Missing capability is a reported gap, not a workaround.
-
-## Project-scoped forge access
-
-The session starts with the selected project's read or role credential in its
-environment or private provider config. Use that configured forge normally.
-Continuous observation needs a read credential valid for the observer's
-lifetime. An unavailable login is a visible configuration blocker; do not
-read host administrator credentials or invent another login method.
-
-When the deployment explicitly configures a temporary credential provider,
-use the existing `ace-lab auth request/status/exec/revoke` procedure. These
-commands run locally; they do not depend on a service. Request only the named
-repository and role. `auth exec` gives its child the credential and reports
-execution and cleanup separately. An unconfirmed revoke remains unresolved.
-Static shared project credentials are not revoked when one worker exits.
-
-Pass repository, role, scope and acceptance criteria in the commission,
-never tokens. Workers implement, reviewers independently review, and
-integrators merge; the coordinator never borrows those roles to do their work.
+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.

data/lib/ace/overseer/atoms/report_interpretation.rb

@@ -47,6 +47,9 @@ module Ace
         def self.evaluate(event:, managers:)
           return {status: :unmatched, reason: "event has no report identity"} if event["id"].to_s.strip.empty?
 
+          if event["project_root"]
+            managers = managers.select { |manager| manager.metadata["project_root"] == event["project_root"] }
+          end
           matched = match(event, managers)
           return {status: :unmatched, reason: unmatched_reason(event)} unless matched
 

data/lib/ace/overseer/atoms/start_contract.rb

@@ -10,8 +10,8 @@ module Ace
         FIRST_TURN_PROMPT = <<~PROMPT.chomp
           Begin your first turn now. Execute the "First turn after start"
           protocol in your standing instructions in its listed order.
-          Arm observation with the ace_eyes tool, action start, using configPath
-          set to .ace-local/overseer/eyes.json relative to your working directory.
+          Observation is armed by session initialization. Read ace_eyes status;
+          do not create its standard configuration or start another observer.
           Report reconciliation and new dispatch both require a successful
           observation with every required source healthy. If observation is
           unavailable or degraded, record its exact error through the existing