ace-overseer 0.28.1 → 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
 
@@ -31,18 +31,28 @@ 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, commission any missing configuration and project
-preparation through workers 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
@@ -51,35 +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. For a preparation commission, read existing readiness/session state; use
+   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` launches a foreground harness; never call it
-   recursively from your own session.
-5. After dispatch, record the real assignment and agent identity and END YOUR
+   `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
@@ -147,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.
@@ -178,7 +177,13 @@ 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 explicitly allocated `role=planner` non-terminal
 step having no assignment). Task and any supplied role must agree; an event

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/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

data/lib/ace/overseer/cli/commands/handoff.rb

@@ -50,6 +50,10 @@ module Ace
             end
 
             next_leg = result[:next]
+            if result[:execution]
+              puts "Executor #{result[:execution]['agent']} started for #{next_leg['assignment']}. End the turn; eyes observes its report."
+              return
+            end
             unless next_leg && next_leg["start_config"]
               raise Ace::Support::Cli::Error,
                 "handoff result is missing the next leg start config - refusing to print a guessed command"

data/lib/ace/overseer/cli/commands/process_reports.rb

@@ -9,6 +9,8 @@ module Ace
 
           desc "Process incoming ace-hitl reports and continue the overseer queue"
 
+          option :scope, type: :string, desc: "HITL scope: current or all (default: owner checkout scope)"
+          option :owner, type: :string, default: "overseer", desc: "Configured HITL recipient, matching the eyes observer"
           option :dry_run, type: :boolean, default: false, desc: "Interpret reports without writes or continuation"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
@@ -18,10 +20,10 @@ module Ace
             @processor = processor
           end
 
-          def call(dry_run: false, **options)
+          def call(dry_run: false, owner: "overseer", scope: nil, **options)
             Atoms::RepoGuard.ensure_repo!
 
-            processor = @processor || Organisms::ReportProcessor.new
+            processor = @processor || Organisms::ReportProcessor.new(owner: owner, scope: scope)
             result = processor.call(
               dry_run: dry_run,
               on_progress: options[:quiet] ? nil : ->(msg) { puts msg }

data/lib/ace/overseer/cli/commands/start.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "shellwords"
 
 module Ace
   module Overseer
@@ -9,8 +10,8 @@ module Ace
         # `ace-overseer start [--dry-run] [--format table|json]`
         # (task 8xs.t.pu0.1): starts or reuses the project overseer
         # session from the directory's explicit start configuration.
-        # Exit 0 only for started/reused (dry-run reports the plan with
-        # exit 0 but creates nothing); a blocked start is a CLI error.
+        # Ready starts and dry runs exit 0; blocked or partial starts
+        # are CLI errors. A dry run creates no session.
         class Start < Ace::Support::Cli::Command
           include Ace::Support::Cli::Base
 
@@ -27,7 +28,7 @@ module Ace
             super()
             @orchestrator = orchestrator
             @config = config
-            @launcher = launcher || ->(argv) { Kernel.exec(*argv) }
+            @launcher = launcher
           end
 
           def call(dry_run: false, format: "table", scope: nil, reconcile: false, **options)
@@ -45,7 +46,7 @@ module Ace
             else
               operation.bootstrap(dry_run: dry_run)
             end
-            return @launcher.call(report.fetch("command")) if report["status"] == "foreground"
+            return launch_foreground(report) if report["status"] == "foreground"
 
             if options[:quiet]
               # quiet still fails loudly on a blocked start
@@ -55,11 +56,16 @@ module Ace
               render_table(report)
             end
 
+            if report["prompt_failed"] == true
+              raise Ace::Support::Cli::Error, report["message"] || "first turn or readiness is unconfirmed"
+            end
             case report["status"]
             when "started", "reused", "ready", "dry_run" then nil
             else
               raise Ace::Support::Cli::Error, report["message"] || "start blocked"
             end
+          rescue Interrupt
+            raise Ace::Support::Cli::Error.new("start interrupted; inspect existing sessions before retrying", exit_code: 130)
           rescue Ace::Support::Cli::Error
             raise
           rescue => e
@@ -68,6 +74,25 @@ module Ace
 
           private
 
+          def launch_foreground(report)
+            return @launcher.call(report.fetch("command")) if @launcher
+
+            role = report["scope"] == "lab" ? "lab-overseer" : "project-overseer"
+            directory = nil
+            Molecules::SessionEnvironment.new.with_environment(root: report.fetch("root"), role: role) do |path, credentials, _args|
+              directory = credentials
+              environment = JSON.parse(File.read(path))
+              system(environment, *report.fetch("command"), unsetenv_others: true)
+              status = $?
+              unless status&.success?
+                raise Ace::Support::Cli::Error.new("coordinator process exited unsuccessfully",
+                  exit_code: status&.exitstatus || 1)
+              end
+            end
+          ensure
+            Molecules::SessionEnvironment.cleanup(directory) if directory
+          end
+
           def orchestrator(scope: nil)
             @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config, scope: scope)
           end
@@ -83,9 +108,16 @@ module Ace
             end
             puts "  workspace:     #{report["workspace"] || "-"}"
             puts "  pane:          #{report["pane"] || "-"}"
-            puts "  agent:         #{report["agent"]}"
+            puts "  agent:         #{report["agent"] || "-"}"
+            puts "  command:       #{Shellwords.join(report["command"])}" if report["command"]
             puts "  replaced pane: #{report["replaced_pane"] || "-"}" if report["replaced_pane"]
             puts "  #{report["message"]}" if report["message"]
+            Array(report["projects"]).each do |project|
+              status = project["status"] || "unknown"
+              status += " (first turn unconfirmed)" if project["prompt_failed"]
+              puts "  project #{project["id"]}: #{status} (#{project["path"] || "-"}, pane: #{project["pane"] || "-"})"
+              puts "    #{project["message"]}" if project["message"]
+            end
           end
         end
       end

data/lib/ace/overseer/cli/commands/work_on.rb

@@ -37,7 +37,7 @@ module Ace
             end
 
             progress = options[:quiet] ? nil : ->(msg) { puts msg }
-            @orchestrator.call(
+            result = @orchestrator.call(
               task_ref: task_refs.first,
               task_refs: task_refs,
               cli_preset: preset,
@@ -46,7 +46,11 @@ module Ace
 
             return if options[:quiet]
 
-            puts "Done. Switch to tmux window and run /ace-assign-drive"
+            if result[:execution]
+              puts "Executor #{result[:execution]['agent']} started for #{result[:assignment_id]}. End the turn; eyes observes its report."
+            else
+              puts "Done. Switch to the task window and run /ace-assign-drive"
+            end
           rescue Ace::Support::Cli::Error
             raise
           rescue => e

data/lib/ace/overseer/cli.rb

@@ -20,6 +20,7 @@ module Ace
       PROGRAM_NAME = "ace-overseer"
 
       REGISTERED_COMMANDS = [
+        ["start", "Start the lab or project overseer"],
         ["work-on", "Start local task work"],
         ["handoff", "Hand the task worktree to the next role"],
         ["process-reports", "Process ace-hitl reports and continue the queue"],
@@ -31,6 +32,7 @@ module Ace
       ].freeze
 
       HELP_EXAMPLES = [
+        "ace-overseer start                    # Start in the current directory",
         "ace-overseer work-on 148              # Launch task in worktree",
         "ace-overseer handoff --task 148       # Hand the worktree to the next role",
         "ace-overseer process-reports          # Interpret reports, continue the queue",