ace-overseer 0.30.2 → 0.31.0

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

@@ -9,306 +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 repeat the original startup dispatch or commission after a session 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.
-
-### Interrupted executor processes
-
-When native Herdr positively reports that a previously running executor is
-absent, preserve its assignment and worktree. Assess unfinished work with
-`ace-coworker resume --config <recorded-prepare-config> --dry-run` from that
-worktree. For a running assignment, retry
-`ace-overseer work-on --task <same-project-task> --runtime herdr` from the
-project root. This resumes the recorded Pi transcript with fresh role credentials
-and a continuation prompt. Normally it uses the original terminal. After a failed
-resume and native terminal replacement, the product may verify executor absence
-and resume that same transcript in a fresh pane, leaving the old pane untouched.
-It preserves the assignment and does not advance to the next role. Record the
-returned pane/session identity and any explicit previous-terminal receipt; arm a
-single five-minute recovery deadline and cancel on verified progress.
-Do not use `handoff` to bypass an unfinished role. Missing transcript, unverified
-terminal replacement or uncertain start/prompt remains a blocker: preserve the
-binding and escalate; never clear it or mark steps complete to force a launch.
-
-### Ended worker turns and provider failures
-
-An executor event's `completion_seq` means a native turn ended, not that its
-assignment succeeded. Before acknowledging that revision, read the current
-native session, pinned assignment and reports. Do not reuse an earlier
-`working` observation. If the assignment is complete, adopt its report through
-`process-reports`. If the session is currently working, leave it alone.
-`state_change_seq` records state transitions, not a progress heartbeat: an
-unchanged value while working does not establish a stall. At a recovery
-deadline, inspect the active command and current owner artifacts before
-escalating. A reviewer may have saved rounds in `.ace-local/review/sessions/`,
-feedback dispositions, commits or a new PR HEAD while its assignment step is
-still unfinished; preserve those results and continue that step. Count progress
-only when artifacts are new or changed since the recovery baseline recorded
-in the existing coordination leg (assignment revision, review round, commit or
-PR HEAD). Historical artifacts alone cannot cancel its deadline. Absence of a
-final assignment report does not mean absence of work.
-
-If the same interactive session ended with a provider error and its assignment
-is unfinished, inspect its last output and recorded progress. Record recovery
-in the existing coordination leg, then send a continuation to that same
-terminal naming the assignment and unfinished step. Preserve completed work,
-commits and PRs; do not resend the original commission or create another agent.
-This continuation is distinct from startup recovery above. Acknowledge the
-handled revision only after recording the outcome, then end the turn with eyes
-armed. A prompt receipt alone does not prove progress. After submission, arm
-one existing eyes deadline `provider-recovery-<assignment>` pinned to the
-assignment revision, with a 300000-millisecond window. Cancel it only on
-verified assignment or work-product progress. Do not rearm it merely because
-another timeout or completion event arrived. On expiry, inspect the current
-owners; if there has been no progress, stop automatic retries and escalate the
-concrete provider failure through HITL. Preserve the deadline while handling
-repeated failures so a stalled continuation cannot silently wait forever.
-An unknown outcome or ambiguous session also requires reconciliation/escalation,
-not a speculative continuation.
-
-## 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. Use the configured client as described below.
-  If that client reports missing access, record its exact error and end the turn.
-  Never ask a human to paste a token.
-- 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. For Forgejo, use the installed `fj`
-client with the configured host/repository (consult its help for command syntax).
-It reads its prepared login from the session's XDG_DATA_HOME; no interactive login
-or auth lease request is needed for a static role credential. An anonymous curl
-403 is not evidence that the configured client lacks access. Do not probe host
-lease inventory or search credential stores before trying the configured client.
-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/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

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require "json"
 
 module Ace
   module Overseer
@@ -10,6 +11,8 @@ module Ace
           desc "Hand the task worktree to the next role in the sequence"
 
           option :task, aliases: ["-t"], desc: "Task reference whose worktree receives the next role"
+          option :json, type: :boolean, default: false, desc: "Machine result; progress on stderr"
+          option :manager, desc: "Private managing task reference"
           option :runtime, desc: "Terminal backend (auto, tmux, herdr)"
           option :dry_run, type: :boolean, default: false, desc: "Check handoff readiness without effects"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
@@ -21,7 +24,7 @@ module Ace
             @config = config
           end
 
-          def call(task: nil, runtime: nil, dry_run: false, **options)
+          def call(task: nil, runtime: nil, dry_run: false, manager: nil, json: false, **options)
             selected_runtime = runtime || (@config || Ace::Overseer.config)["runtime"] || "auto"
             unless %w[auto tmux herdr].include?(selected_runtime)
               raise Ace::Support::Cli::Error, "unsupported runtime: #{selected_runtime}"
@@ -34,14 +37,23 @@ module Ace
               raise Ace::Support::Cli::Error.new("--task is required. Usage: ace-overseer handoff --task <ref>")
             end
 
-            progress = options[:quiet] ? nil : ->(msg) { puts msg }
+            progress = options[:quiet] ? nil : ->(msg) { json ? $stderr.puts(msg) : puts(msg) }
             result = @orchestrator.call(
               task_ref: task_ref,
               dry_run: dry_run,
               on_progress: progress,
-              runtime: selected_runtime
+              runtime: selected_runtime, **(manager ? {manager_ref: manager} : {})
             )
 
+            execution = result[:execution]
+            result[:operation] = {
+              completed: ["delegation prepared"], running: execution ? [execution["agent"]] : [],
+              waiting: execution ? ["executor report"] : [], blocked: [],
+              evidence: result.slice(:manager_ref, :task_ref, :worktree_path, :assignment_id, :next)}
+            if json
+              puts JSON.generate(result)
+              return
+            end
             return if options[:quiet]
 
             if result[:status] == "sequence_complete"

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require "json"
 
 module Ace
   module Overseer
@@ -9,8 +10,9 @@ module Ace
 
           desc "Process incoming ace-hitl reports and continue the overseer queue"
 
+          option :json, type: :boolean, default: false, desc: "Machine result on stdout; progress on stderr"
           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 :owner, type: :string, 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"
@@ -20,15 +22,19 @@ module Ace
             @processor = processor
           end
 
-          def call(dry_run: false, owner: "overseer", scope: nil, **options)
+          def call(dry_run: false, owner: nil, scope: nil, json: false, **options)
             Atoms::RepoGuard.ensure_repo!
 
-            processor = @processor || Organisms::ReportProcessor.new(owner: owner, scope: scope)
+            processor = @processor || Organisms::ReportProcessor.new(owner: resolve_owner(owner), scope: scope)
             result = processor.call(
               dry_run: dry_run,
-              on_progress: options[:quiet] ? nil : ->(msg) { puts msg }
+              on_progress: options[:quiet] ? nil : ->(msg) { json ? $stderr.puts(msg) : puts(msg) }
             )
 
+            if json
+              puts JSON.generate(result)
+              return
+            end
             return if options[:quiet]
 
             puts
@@ -45,6 +51,29 @@ module Ace
           rescue => e
             raise Ace::Support::Cli::Error.new(e.message)
           end
+
+          private
+
+          def resolve_owner(owner)
+            return owner unless owner.to_s.strip.empty?
+
+            config = Ace::Overseer.config
+            configured = config["owner"].to_s.strip
+            return configured unless configured.empty?
+
+            scope = config.dig("start", "scope").to_s.strip
+            return "lab-overseer" if scope == "lab"
+            return "overseer" if scope == "project"
+
+            if File.file?(".ace-local/overseer/eyes.json")
+              data = JSON.parse(File.read(".ace-local/overseer/eyes.json"))
+              recipient = data.is_a?(Hash) ? data["recipient"].to_s.strip : ""
+              return recipient unless recipient.empty?
+            end
+            "overseer"
+          rescue JSON::ParserError, SystemCallError
+            "overseer"
+          end
         end
       end
     end

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

@@ -87,9 +87,14 @@ module Ace
 
             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|
+            Molecules::SessionEnvironment.new.with_environment(root: report.fetch("root"), role: role, eyes_config: report["eyes_config"]) do |path, credentials, _args|
               directory = credentials
               environment = JSON.parse(File.read(path))
+              # Foreground Pi occupies this terminal; delegated launches receive
+              # their destination context from native Herdr instead.
+              environment.merge!(ENV.to_h.slice("HERDR_ENV", "HERDR_PANE_ID", "HERDR_TAB_ID", "HERDR_WORKSPACE_ID"))
+              environment["HERDR_PANE"] = environment["HERDR_PANE_ID"] if environment["HERDR_PANE_ID"]
+              environment["HERDR_SESSION"] = environment["HERDR_WORKSPACE_ID"] if environment["HERDR_WORKSPACE_ID"]
               system(environment, *report.fetch("command"), unsetenv_others: true)
               status = $?
               unless status&.success?

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

@@ -25,7 +25,7 @@ module Ace
 
           def call(format:, runtime: nil, **options)
             selected_runtime = runtime || (@config || Ace::Overseer.config)["runtime"] || "auto"
-            unless %w[auto tmux].include?(selected_runtime)
+            unless %w[auto tmux herdr].include?(selected_runtime)
               raise Ace::Support::Cli::Error, "unsupported local runtime: #{selected_runtime}"
             end
 

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require "json"
 
 module Ace
   module Overseer
@@ -12,6 +13,8 @@ module Ace
           option :task, aliases: ["-t"], type: :array,
             desc: "Task reference(s), repeatable and comma-separated (e.g., 230 --task 231,232)"
           option :preset, aliases: ["-p"], desc: "Assignment preset name"
+          option :json, type: :boolean, default: false, desc: "Machine result; progress on stderr"
+          option :manager, desc: "Private managing task reference"
           option :runtime, desc: "Terminal backend (auto, tmux, herdr)"
           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"
@@ -22,7 +25,7 @@ module Ace
             @config = config
           end
 
-          def call(task: nil, preset: nil, runtime: nil, **options)
+          def call(task: nil, preset: nil, runtime: nil, manager: nil, json: false, **options)
             raise Ace::Support::Cli::Error, "--work is obsolete; select task or preset" if options.key?(:work)
             selected_runtime = runtime || (@config || Ace::Overseer.config)["runtime"] || "auto"
             unless %w[auto tmux herdr].include?(selected_runtime)
@@ -36,14 +39,23 @@ module Ace
               raise Ace::Support::Cli::Error.new("--task is required. Usage: ace-overseer work-on --task <ref>")
             end
 
-            progress = options[:quiet] ? nil : ->(msg) { puts msg }
+            progress = options[:quiet] ? nil : ->(msg) { json ? $stderr.puts(msg) : puts(msg) }
             result = @orchestrator.call(
               task_ref: task_refs.first,
               task_refs: task_refs,
               cli_preset: preset,
-              on_progress: progress, runtime: selected_runtime
+              on_progress: progress, runtime: selected_runtime, **(manager ? {manager_ref: manager} : {})
             )
 
+            execution = result[:execution]
+            result[:operation] = {
+              completed: ["delegation prepared"], running: execution ? [execution["agent"]] : [],
+              waiting: execution ? ["executor report"] : [], blocked: [],
+              evidence: result.slice(:manager_ref, :task_ref, :worktree_path, :assignment_id, :next)}
+            if json
+              puts JSON.generate(result)
+              return
+            end
             return if options[:quiet]
 
             if result[:execution]

data/lib/ace/overseer/molecules/coworker_launcher.rb

@@ -147,7 +147,11 @@ module Ace::Overseer::Molecules
           raise Ace::Overseer::Error, "executor terminal changed before session publication"
         end
         identity = Ace::Herdr::Atoms::NativeAgentSession.normalize(pane["agent_session"], agent: "pi")
-        return identity if identity
+        if identity
+          raw = pane["agent_session"]
+          execution["session_path"] = raw["value"] if raw.is_a?(Hash) && raw["kind"] == "path"
+          return identity
+        end
         raise Ace::Overseer::Error, "native executor session identity is unavailable; retry the same handoff" if @clock.call >= deadline
         @sleeper.call(0.2)
       end
@@ -178,6 +182,8 @@ module Ace::Overseer::Molecules
       end
       execution.merge!("pane" => row["pane_id"], "terminal_id" => row["terminal_id"],
         "agent_session" => identity, "state" => "started")
+      raw = row["agent_session"]
+      execution["session_path"] = raw["value"] if raw.is_a?(Hash) && raw["kind"] == "path"
       save.call
     end
 
@@ -241,7 +247,7 @@ module Ace::Overseer::Molecules
         return resume_dead(execution, brief, worktree_path, pane, save)
       end
       unless agent.is_a?(Hash) && same_executor?(agent, execution) && agent["cwd"] == worktree_path &&
-          agent["name"] == execution["agent"] && agent["interactive_ready"] == true && agent["agent_status"] == "idle"
+          agent["name"] == execution["agent"] && agent["interactive_ready"] == true && %w[idle done].include?(agent["agent_status"])
         raise Ace::Overseer::Error, "resumed executor is not the expected idle session; inspect before retrying"
       end
       execution["state"] = "resume_prompting"
@@ -276,7 +282,7 @@ module Ace::Overseer::Molecules
       rows = replacement_matches(execution)
       row = rows.one? && rows.first
       unless row && row["name"] == execution["agent"] && row["cwd"] == worktree_path && row["terminal_id"] &&
-          row["interactive_ready"] == true && row["agent_status"] == "idle" && session_identity(row) == execution["agent_session"]
+          row["interactive_ready"] == true && %w[idle done].include?(row["agent_status"]) && session_identity(row) == execution["agent_session"]
         raise Ace::Overseer::Error, "replacement resume is unconfirmed; inspect before retrying"
       end
       execution.merge!("pane" => row["pane_id"], "terminal_id" => row["terminal_id"])