ace-overseer 0.28.0 → 0.29.0

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

@@ -6,8 +6,8 @@ doc-type: workflow
 title: Lab Overseer Start Guide
 purpose: Define the lab overseer's coordination role across projects — readiness aggregation, cross-project escalation, delegation to project overseers — without taking over any project's tasks or private state.
 ace-docs:
-  last-updated: '2026-10-30'
-  last-checked: '2026-10-30'
+  last-updated: '2026-11-04'
+  last-checked: '2026-11-04'
 ---
 # Lab Overseer Start Guide
 
@@ -21,24 +21,38 @@ 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 and binstub generation are WORKER
-work. Create a commission and dispatch a separate lab worker even when the
+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.
+
 ## First turn after start
 
-`ace-overseer start` is the bootstrap entry point. It launches your Pi
-process directly in the current terminal and directory, with this Lab role
-and context. It performs no Herdr agent, owner or layout preflight. A missing `.ace/overseer/config.yml` is first-run setup, not a request
-for the Captain to write YAML. The packaged bootstrap profile is
-`pi`, `zai/glm-5.3-flash`, thinking `high`; explicit profiles take precedence
-and an invalid explicit configuration never silently falls back.
+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.
-On this first turn, establish your own configuration and the commissioned
-project overseers before resuming unrelated stored backlog. Read old
+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
@@ -47,31 +61,53 @@ 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` and follow
-   its complete task → worker → observation → verification → start procedure.
+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. Check enabled=true, breaker=null, errors=0 and
-   a successful observation before dispatch. A missing tool/configuration is
-   a readiness gap. Writing `/eyes` in prose does not arm observation.
-4. Use `ace-overseer start --reconcile` to inspect/start commissioned project
-   sessions. Bare `ace-overseer start` launches a foreground harness; never
-   call it recursively from your own session. Delegate preparation or repair
-   of blocked projects to a lab worker through the bootstrap procedure.
-5. After dispatch, record the real assignment and agent identity and END YOUR
+   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 is labeled `overseer-<project-root>`); you do not dispatch 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.
-- One project's failure never blocks the healthy ones: keep their work
-  flowing and report the failure separately.
+- 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
 

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

@@ -1,6 +1,6 @@
 ---
 name: overseer-queue
-description: Run the private overseer queue in .ace-tasks/_overseer with ace-task --in _overseer - record work as managing tasks with lifecycle subtasks, gate starts on integrated results, keep one active executor per worktree, and process ace-hitl reports
+description: Run the private overseer queue in .ace-tasks/_overseer with ace-task list --in _overseer - record work as managing tasks with lifecycle subtasks, gate starts on integrated results, keep one active executor per worktree, and process ace-hitl reports
 allowed-tools: Bash, Read
 doc-type: workflow
 title: Overseer Queue Workflow
@@ -15,7 +15,7 @@ ace-docs:
 ## Goal
 
 Coordinate delegated work exclusively through the overseer's private task tree
-in `.ace-tasks/_overseer/` (gitignored, managed via `ace-task --in _overseer`),
+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
@@ -80,6 +80,7 @@ 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>
@@ -94,7 +95,11 @@ 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 worktree=.ace-wt/<task>/`.
+  `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
@@ -142,11 +147,10 @@ Worker finishes → reviewer starts → integrator starts, in the same worktree:
   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.
-  On success it opens the next executor's window in the same worktree and
-  prints `ace-coworker start --config .ace-local/coworker/prepare/<role>.yml`
-  -- the next role starts from the existing start config, nothing is
-  re-prepared. `--dry-run` checks without effects. Use it before every
-  dispatch into a worktree that already served a previous role.
+  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.
@@ -162,8 +166,9 @@ 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. Record the outcome and the processed report ID in the managing task /
-   step (task-folder notes), then update statuses:
+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
@@ -172,16 +177,31 @@ When a report arrives (ace-hitl event or message):
 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` executes rules 1-3 mechanically: it matches
+`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 non-terminal step), records the outcome and
+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. `--dry-run` interprets without effects.
+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
 

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

@@ -6,8 +6,8 @@ doc-type: workflow
 title: Project Overseer Start Guide
 purpose: Define the started project overseer's role boundaries, observation and delegation loop, HITL escalation, and completion semantics; the overseer coordinates and never substitutes for a missing coworker.
 ace-docs:
-  last-updated: '2026-10-30'
-  last-checked: '2026-10-30'
+  last-updated: '2026-11-06'
+  last-checked: '2026-11-06'
 ---
 # Project Overseer Start Guide
 
@@ -21,14 +21,30 @@ a missing coworker — you report the gap and escalate.
 
 ## First turn after start
 
-1. Read your private task list: `ace-task --in _overseer list` (your
-   coordination tasks live there; you own them).
-2. Read project truth from the state owners — never a second cache:
-   `ace-task list`, `ace-overseer status`, `ace-git-worktree list`,
-   `git status --short`, and pending escalations with `ace-hitl list`.
-3. Continue EXISTING commissioned work before choosing anything new.
-4. When the lists are empty and no report awaits processing: record that state
-   and remain idle. Silence is a correct state; do not invent work.
+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
 
@@ -42,26 +58,161 @@ a missing coworker — you report the gap and escalate.
 - 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.
-- Answers return through the same case; apply them once and close the case.
+- 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, arm `/eyes` with the project's eyes configuration (interval 15s is
-the default reconcile cadence). `ace-overseer observe` — what eyes polls —
-projects the six local source classes from their owners: project tasks,
+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 and HITL events. A real
+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. After a restart, reconcile pending revisions first — a report
-that arrived in your absence surfaces as an unacknowledged revision — then
-choose work by the existing plan/dependency order (`ace-overseer
-process-reports`, `ace-overseer work-on`). Acknowledge (`/eyes ack KEY
+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.
 
@@ -70,10 +221,36 @@ settlement alone is not proof of handling.
 - 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 files.
-- Remote PR observation (observe.remote.pull_requests) and the HITL reply
+  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.

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Ace
+  module Overseer
+    module Atoms
+      module ObservationSources
+        PROJECT_TASKS = "project_tasks"
+        OVERSEER_TASKS = "overseer_tasks"
+        WORKTREES = "worktrees"
+        COWORKERS = "coworkers"
+        HITL = "hitl"
+        PROJECT_SESSIONS = "project_sessions"
+        REQUIRED = [PROJECT_TASKS, OVERSEER_TASKS, WORKTREES, COWORKERS, HITL].freeze
+      end
+    end
+  end
+end

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

@@ -15,7 +15,7 @@ module Ace
       #   assignment that matches no step is :unmatched), or — only for
       #   reports without an assignment (planner readiness) — by the
       #   managing task's project_task plus exactly one non-terminal
-      #   step whose own assignment is blank (the preparation role). An
+      #   step explicitly allocated to role planner with no assignment. An
       #   event that fits no open allocation is :unmatched, kept
       #   for clarification, never success (an ambiguous cross-manager
       #   match is also :unmatched).
@@ -45,6 +45,8 @@ module Ace
         #      recorded_result:}
         #   {status: :unmatched, reason:}
         def self.evaluate(event:, managers:)
+          return {status: :unmatched, reason: "event has no report identity"} if event["id"].to_s.strip.empty?
+
           matched = match(event, managers)
           return {status: :unmatched, reason: unmatched_reason(event)} unless matched
 
@@ -142,16 +144,11 @@ module Ace
         # because a stale report for a different assignment must never
         # complete whichever step happens to remain.
         #
-        # Without an assignment (a planner readiness report carries task
-        # + result only) the report binds to the PREPARATION role alone:
-        # the managing task's project_task must match the reported task
-        # AND leave exactly one non-terminal step whose own assignment is
-        # blank (the preparation step). A sole remaining step that is
-        # bound to a role assignment belongs to that role, not to the
-        # report — absence of an assignment is never evidence that
-        # whichever role remains just finished. A match that is ambiguous
-        # across managers (or across steps) fits no open allocation and
-        # returns nil.
+        # Unassigned readiness can complete only an explicitly allocated
+        # planner step. A missing assignment says nothing about the role:
+        # confirm-start and bootstrap execution also have unassigned windows.
+        # Task identity and any supplied role must agree with the allocation.
+        # Ambiguous allocations never advance.
         #
         # @return [Hash{manager:, step:, terminal:}, nil]
         def self.match(event, managers)
@@ -161,8 +158,10 @@ module Ace
           assignment = event["assignment"].to_s
           if assignment != ""
             matches = managers.flat_map do |manager|
+              next [] unless task_agrees?(event, manager)
+
               steps_of(manager).filter_map do |step|
-                {manager: manager, step: step} if step.metadata["assignment"].to_s == assignment
+                {manager: manager, step: step} if step.metadata["assignment"].to_s == assignment && role_agrees?(event, step)
               end
             end
             # No step records this assignment: unmatched, never a
@@ -182,7 +181,9 @@ module Ace
             next unless manager.metadata["project_task"].to_s == task && task != ""
 
             active = steps_of(manager).reject { |step| terminal?(step) }
-            preparation = active.reject { |step| step.metadata["assignment"].to_s != "" }
+            preparation = active.select do |step|
+              step.metadata["assignment"].to_s.empty? && step.metadata["role"] == "planner" && role_agrees?(event, step)
+            end
             {manager: manager, step: preparation.first} if preparation.size == 1
           end
           return nil if matches.size > 1
@@ -201,7 +202,9 @@ module Ace
         def self.recorded_match(event, managers)
           matches = managers.flat_map do |manager|
             steps_of(manager).filter_map do |step|
-              {manager: manager, step: step} if step.metadata[PROCESSED_REPORT_KEY] == event["id"]
+              {manager: manager, step: step} if step.metadata[PROCESSED_REPORT_KEY] == event["id"] &&
+                task_agrees?(event, manager) && role_agrees?(event, step) &&
+                (event["assignment"].to_s.empty? || step.metadata["assignment"].to_s == event["assignment"].to_s)
             end
           end
           return nil if matches.size != 1
@@ -210,6 +213,17 @@ module Ace
            terminal: terminal?(matches.first[:step])}
         end
 
+        def self.task_agrees?(event, manager)
+          expected = manager.metadata["project_task"].to_s
+          actual = event["task"].to_s
+          expected.empty? || expected == actual
+        end
+
+        def self.role_agrees?(event, step)
+          role = event["role"].to_s
+          role.empty? || step.metadata["role"].to_s == role
+        end
+
         # @return [String] why the event fit no open allocation
         def self.unmatched_reason(event)
           refs = []

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

@@ -7,6 +7,26 @@ module Ace
       # first-run profile when no start section exists. A malformed explicit
       # configuration never falls back to another model or harness.
       class StartContract
+        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 your configured eyes path.
+          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
+          task/HITL owner and END THIS TURN without processing pending reports.
+          If that owner is unavailable, report its failure and end the turn.
+          When observation is healthy, follow the role's first-turn protocol
+          through its stopping point. When that protocol calls for work,
+          reconcile existing commissions before choosing new work and
+          acknowledge revisions only after their owner accepted them.
+          Do not diagnose implementation, inspect host
+          credential stores, probe transports or repeat status/help commands.
+          Installation, configuration and diagnosis belong to workers.
+          End the turn after delegation; remain idle when there is no work.
+        PROMPT
+
         SCOPES = %w[project lab].freeze
         SECTION_KEYS = %w[scope profile instructions].freeze
         PROFILE_KEYS = %w[harness model thinking].freeze