ace-overseer 0.30.1 → 0.30.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c02cb4e6cc0d37cd3db64cfb66c25acfdf35d9d52dbbf9d50fda87d21ffa6359
-  data.tar.gz: 339ddccc9081d5905d8a00178c8144925504a53f48e8baf29f135d6a7543b85a
+  metadata.gz: d988bf0e0a1bbd916a1612f1e8172f59bc9eedfb2c93660e52c59e5bc03562ff
+  data.tar.gz: a16e7ec132f9dc325ed860f944c578bdf7ece8b2ef44bd44c2de3ba188387df4
 SHA512:
-  metadata.gz: 993aa5aa36125ca59af277d7e4b1c22ad4aec9cd23e048ecc75a2d8684e51b0a6aa8d429c2ad8cf02aae9e8bd3e849e71ea1c95c9d4bde747fb0b604419a055a
-  data.tar.gz: c9236b380d6db7507402ffe6ae049248c191707fc9857c66b02d1672c598045831b1bf971d64fc69e6b05da29219ef64788a04b3f031f574c97fd8c33abf2e5e
+  metadata.gz: 0b5415e44739dc7f32e903c9d70860bf351419a7ef3532d90c53c54e9c3756d86bb675a4d836722fbab638ab5be12211d9d74788c1c33885083670b2f66b087c
+  data.tar.gz: e95bb169b326d8b27c5c764c6960e58ddd402247b8d270347099490f6a0a398d599b097a92bcee55a5fac85868b241f58e4056b00b667067f0d64028396e7ff0

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.2] - 2026-11-12
+
+### Fixed
+
+- Resume a failed executor in a fresh pane after native terminal identity replacement, preserving assignment/session and reconciling uncertain dispatch without duplicates.
+- Retry failed session resumption only after native proof that the original terminal contains only its shell.
+- Retrying work-on resumes a positively dead executor's existing Pi transcript and running assignment in its original terminal with fresh role credentials; uncertain start or prompt outcomes cannot duplicate execution.
+- Project-session observation recognizes one live replacement when a dead predecessor panel remains after restart, matching managed start ownership checks.
+- Judge recovery progress from changed owner artifacts against the recorded baseline, rather than an unchanged native state-transition counter or missing final report.
+- Distinguish same-session continuation after provider failure from duplicate startup dispatch; reconcile current owners before acknowledging completion and bound recovery with the existing eyes deadline.
+- Observe native worker turn completions even when provider failures leave a live panel without an assignment report; unchanged completion sequences remain silent.
+- Preserve native worker launch receipts while Pi publishes its session identity; resume the same verified idle executor without duplicating a process or an uncertain prompt.
+- Direct Forgejo sessions to their configured client before treating anonymous API refusal as missing access or requesting temporary credentials.
+- Namespace native overseer agent names by canonical root so lab and project sessions coexist on one Herdr server.
+- Consume configured project reports from the lab, bind all outcomes to their project, and resolve completion and continuation in the project checkout while retaining the lab task owner.
+- Specify the supported bootstrap workflow command and refuse substituting checkout instructions in installed mode.
+
 ## [0.30.1] - 2026-11-11
 
 ### Fixed

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

@@ -249,7 +249,7 @@ the path returned by `ace-task show` supplement these fields, never replace them
 Read back the recorded identity before acknowledging the eyes revision.
 Never put a preparation readiness ID on a worker, verifier or confirm-start step.
 
-After accepting the worker's report, use `ace-overseer process-reports` to
+After accepting the worker's report, use `ace-overseer process-reports --owner <configured-lab-recipient>` to
 retire its recorded executor and continue the prepared sequence. Preserve
 the exact report and assignment identity before starting the verifier.
 Do not launch a second executor while a predecessor is active or unknown.

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

@@ -61,9 +61,12 @@ Captain order.
 1. Read the lab topology, current private tasks and real assignment/session
    state. Resume this commissioned bootstrap before unrelated backlog. Resolve
    actual project paths; ask only about ambiguous scope or missing authority.
-2. Read `wfi://overseer/bootstrap-delegation` through `ace-bundle` to understand
+2. Run exactly `ace-bundle wfi://overseer/bootstrap-delegation` (there is no
+   `read` subcommand). Read the output file that command returns to understand
    the task → worker → observation → verification → start procedure. Do not
-   dispatch during this initialization turn.
+   dispatch during this initialization turn. In installed mode use the packaged
+   workflow, never a similarly named file in the project checkout. If resolution
+   fails, record that error and end the turn; do not substitute checkout instructions.
 3. Arm observation with the `ace_eyes` tool, action `start`, using the lab's
    eyes configuration path `<lab>/.ace-local/overseer/eyes.json`. Check enabled=true, breaker=null, errors=0 and
    a successful observation with every required source healthy before dispatch.

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

@@ -160,7 +160,7 @@ 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.
+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.
@@ -171,6 +171,60 @@ 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:
@@ -224,10 +278,9 @@ settlement alone is not proof of handling.
   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.
+  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
@@ -239,7 +292,12 @@ settlement alone is not proof of handling.
 ## 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.
+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.

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

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

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "shellwords"
 require "ace/coworker/molecules/execution_binding"
 require "ace/herdr"
 require "ace/herdr/atoms/native_agent_session"
@@ -12,7 +13,9 @@ module Ace::Overseer::Molecules
   class CoworkerLauncher
     def initialize(executor: Ace::Herdr::Molecules::HerdrExecutor.new, env: ENV,
       environment: nil, bindings: Ace::Coworker::Molecules::ExecutionBinding.new,
-      brief_factory: nil, readiness: nil, eyes: nil, root_resolver: nil)
+      brief_factory: nil, readiness: nil, eyes: nil, root_resolver: nil,
+      identity_timeout: 10, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, sleeper: ->(seconds) { sleep(seconds) })
+      @identity_timeout, @clock, @sleeper = identity_timeout, clock, sleeper
       @executor, @env, @bindings = executor, env, bindings
       @environment = environment || SessionEnvironment.new(env: env)
       @brief_factory = brief_factory || ->(root, path) { Ace::Coworker::Organisms::StartOrchestrator.new(project_root: root).call(config_path: path) }
@@ -48,7 +51,18 @@ module Ace::Overseer::Molecules
           raise Ace::Overseer::Error, "executor commission changed during validation"
         end
         if document["execution"]
-          next reuse(document.fetch("execution"))
+          execution = document.fetch("execution")
+          if %w[resuming resumed].include?(execution["state"])
+            next finish_resume(execution, brief, worktree_path, save)
+          end
+          if %w[launching started].include?(execution["state"])
+            unless %w[paused empty].include?(brief.assignment_snapshot&.state.to_s)
+              raise Ace::Overseer::Error, "unconfirmed executor already has assignment activity"
+            end
+            recover_unprompted(execution, worktree_path, save)
+            next submit_prompt(execution, brief, save)
+          end
+          next reuse(execution, brief, worktree_path, save)
         end
         unless %w[paused empty].include?(brief.assignment_snapshot&.state.to_s)
           raise Ace::Overseer::Error, "unbound assignment is not ready for a new executor"
@@ -72,20 +86,14 @@ module Ace::Overseer::Molecules
           result = dispatcher.dispatch(label: name, prompt: "", kind: "pi", cwd: worktree_path,
             env_file: file, args: Array(profile_args) + ["--append-system-prompt", brief.instructions_source])
           execution.merge!(result.to_h).merge!("state" => "started")
+          save.call # Preserve the native receipt before asynchronous session publication.
           pane = pane_identity(execution.fetch("pane"))
           execution["terminal_id"] = pane.fetch("terminal_id")
-          execution["agent_session"] = session_identity(pane)
+          save.call
+          execution["agent_session"] = await_session(execution)
           save.call
         end
-        # Record uncertainty BEFORE submission. A crash after input reaches Pi
-        # cannot cause the same task to be submitted again automatically.
-        execution["state"] = "prompting"
-        save.call
-        prompt = "#{brief.config.start_prompt}\n\n#{Ace::Coworker::Atoms::BriefFormatter.format_table(brief)}"
-        @executor.agent_prompt(pane: execution.fetch("pane"), text: prompt)
-        execution["state"] = "running"
-        save.call
-        execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => false)
+        submit_prompt(execution, brief, save)
       end
     rescue Ace::Coworker::Error, Ace::Herdr::ExecutorError => e
       raise Ace::Overseer::Error, "executor launch blocked: #{e.message}"
@@ -120,7 +128,60 @@ module Ace::Overseer::Molecules
 
     private
 
-    def reuse(execution)
+    def submit_prompt(execution, brief, save)
+      # A crash after input reaches Pi must never repeat the commission.
+      execution["state"] = "prompting"
+      save.call
+      prompt = "#{brief.config.start_prompt}\n\n#{Ace::Coworker::Atoms::BriefFormatter.format_table(brief)}"
+      @executor.agent_prompt(pane: execution.fetch("pane"), text: prompt)
+      execution["state"] = "running"
+      save.call
+      execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => false)
+    end
+
+    def await_session(execution)
+      deadline = @clock.call + @identity_timeout
+      loop do
+        pane = pane_identity(execution.fetch("pane"))
+        unless pane["terminal_id"] == execution.fetch("terminal_id")
+          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
+        raise Ace::Overseer::Error, "native executor session identity is unavailable; retry the same handoff" if @clock.call >= deadline
+        @sleeper.call(0.2)
+      end
+    end
+
+    def recover_unprompted(execution, worktree_path, save)
+      row = @executor.agent_get(execution["pane"] || execution.fetch("agent")).parsed_json&.dig("result", "agent")
+      unless row.is_a?(Hash) && row["name"] == execution["agent"] &&
+          row["cwd"] == worktree_path && row["agent_status"] == "idle" &&
+          row["interactive_ready"] == true && row["pane_id"] && row["terminal_id"]
+        raise Ace::Overseer::Error, "unconfirmed launch is not the expected idle executor"
+      end
+      if execution["terminal_id"] && execution["terminal_id"] != row["terminal_id"]
+        raise Ace::Overseer::Error, "executor terminal changed before recovery"
+      end
+      identity = session_identity(row)
+      if execution["agent_session"] && execution["agent_session"] != identity
+        raise Ace::Overseer::Error, "executor session changed before recovery"
+      end
+      # Without a saved Pi identity, bind only the unique private session
+      # directory allocated for this dispatch, never an arbitrary same-name pane.
+      unless execution["agent_session"]
+        directory = execution["credentials_directory"]
+        native_session = row.fetch("agent_session")
+        unless directory && native_session["kind"] == "path" && native_session["value"].start_with?("#{directory}/sessions/")
+          raise Ace::Overseer::Error, "unconfirmed launch has no matching session provenance"
+        end
+      end
+      execution.merge!("pane" => row["pane_id"], "terminal_id" => row["terminal_id"],
+        "agent_session" => identity, "state" => "started")
+      save.call
+    end
+
+    def reuse(execution, brief, worktree_path, save)
       if execution["state"] == "retired"
         raise Ace::Overseer::Error, "recorded executor is retired; reconcile the assignment before starting another"
       end
@@ -128,16 +189,170 @@ module Ace::Overseer::Molecules
         raise Ace::Overseer::Error, "executor start is unconfirmed; inspect the recorded assignment before retrying"
       end
       pane = pane_identity(execution.fetch("pane"))
-      unless same_executor?(pane, execution)
+      unless pane["terminal_id"] == execution["terminal_id"]
         raise Ace::Overseer::Error, "recorded executor terminal no longer matches"
       end
-      agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
+      begin
+        agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
+      rescue Ace::Herdr::AgentNotFoundError
+        return resume_dead(execution, brief, worktree_path, pane, save)
+      end
       unless agent.is_a?(Hash) && agent["interactive_ready"] == true && same_executor?(agent, execution)
         raise Ace::Overseer::Error, "recorded executor is not a live interactive agent"
       end
       execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => true)
     end
 
+    def resume_dead(execution, brief, worktree_path, pane, save)
+      unless brief.assignment_snapshot&.state.to_s == "running" && pane["cwd"] == worktree_path
+        raise Ace::Overseer::Error, "dead executor recovery requires its running assignment and original directory"
+      end
+      transcript = resume_transcript(execution, worktree_path)
+      SessionEnvironment.cleanup(execution["credentials_directory"])
+      @environment.with_environment(root: worktree_path, role: brief.config.role) do |file, directory, args|
+        execution.merge!("state" => "resuming", "resume_transcript" => transcript,
+          "credentials_directory" => directory)
+        save.call # An uncertain native start must be inspected, never repeated.
+        @executor.agent_start(name: execution.fetch("agent"), kind: "pi", pane: execution.fetch("pane"),
+          timeout_ms: 60_000, env_file: file,
+          args: Array(args) + ["--session", transcript, "--append-system-prompt", brief.instructions_source])
+        identity = await_session(execution)
+        raise Ace::Overseer::Error, "resumed executor session changed" unless identity == execution["agent_session"]
+        execution["state"] = "resumed"
+        save.call
+      end
+      finish_resume(execution, brief, worktree_path, save)
+    end
+
+    def finish_resume(execution, brief, worktree_path, save)
+      raise Ace::Overseer::Error, "resumed assignment is no longer running" unless brief.assignment_snapshot&.state.to_s == "running"
+      if execution["replacement_pending"]
+        recover_replacement(execution, worktree_path, save)
+      end
+      begin
+        agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
+      rescue Ace::Herdr::AgentNotFoundError
+        raise unless execution["state"] == "resuming"
+        pane = pane_identity(execution.fetch("pane"))
+        if pane["terminal_id"] != execution["terminal_id"]
+          return replace_resume_terminal(execution, brief, worktree_path, pane, save)
+        end
+        pane = confirmed_resume_shell(execution, worktree_path)
+        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"
+        raise Ace::Overseer::Error, "resumed executor is not the expected idle session; inspect before retrying"
+      end
+      execution["state"] = "resume_prompting"
+      save.call
+      @executor.agent_prompt(pane: execution.fetch("pane"), text:
+        "Continue the existing assignment #{brief.config.assignment} after process interruption. " \
+        "Read its current owner state and preserved reports; resume unfinished work only. " \
+        "Do not repeat completed effects or create a replacement assignment. " \
+        "Use ace-coworker resume --config #{Shellwords.escape(brief.config.source_path)} to assess continuation.")
+      execution["state"] = "running"
+      save.call
+      execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => true, "resumed" => true)
+    end
+
+    def resume_inventory
+      rows = @executor.agent_list.parsed_json&.dig("result", "agents")
+      unless rows.is_a?(Array) && rows.all? { |row| row.is_a?(Hash) && row["name"].is_a?(String) && row["pane_id"].is_a?(String) &&
+          Ace::Herdr::Atoms::NativeAgentSession.normalize(row["agent_session"], agent: row["agent"]) }
+        raise Ace::Overseer::Error, "native executor inventory is incomplete"
+      end
+      rows
+    end
+
+    def replacement_matches(execution)
+      resume_inventory.select do |row|
+        row["name"] == execution["agent"] ||
+          Ace::Herdr::Atoms::NativeAgentSession.normalize(row["agent_session"], agent: "pi") == execution["agent_session"]
+      end
+    end
+
+    def recover_replacement(execution, worktree_path, save)
+      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"]
+        raise Ace::Overseer::Error, "replacement resume is unconfirmed; inspect before retrying"
+      end
+      execution.merge!("pane" => row["pane_id"], "terminal_id" => row["terminal_id"])
+      execution.delete("replacement_pending")
+      save.call
+    end
+
+    def replace_resume_terminal(execution, brief, worktree_path, pane, save)
+      transcript = resume_transcript(execution, worktree_path)
+      info = @executor.pane_process_info(execution.fetch("pane")).parsed_json&.dig("result", "process_info")
+      unless pane["cwd"] == worktree_path && shell_only?(info, execution["pane"]) && replacement_matches(execution).empty?
+        raise Ace::Overseer::Error, "old executor absence is unconfirmed; replacement refused"
+      end
+      # A native live handoff may replace terminal identity. Never send input
+      # to or close that old pane; resume the same Pi transcript in a new pane.
+      SessionEnvironment.cleanup(execution["credentials_directory"])
+      @environment.with_environment(root: worktree_path, role: brief.config.role) do |file, directory, args|
+        execution["previous_terminal"] = execution.slice("pane", "terminal_id")
+        execution.merge!("replacement_pending" => true, "credentials_directory" => directory, "resume_transcript" => transcript)
+        save.call
+        dispatcher = Ace::Herdr::Organisms::Dispatcher.from_config(executor: @executor)
+        result = dispatcher.dispatch(label: execution.fetch("agent"), prompt: "", kind: "pi", cwd: worktree_path,
+          workspace_id: execution["workspace"], env_file: file,
+          args: Array(args) + ["--session", transcript, "--append-system-prompt", brief.instructions_source])
+        execution.merge!(result.to_h)
+        execution["terminal_id"] = pane_identity(execution.fetch("pane")).fetch("terminal_id")
+        save.call
+        identity = await_session(execution)
+        raise Ace::Overseer::Error, "replacement executor session changed" unless identity == execution["agent_session"]
+        execution.delete("replacement_pending")
+        save.call
+      end
+      finish_resume(execution, brief, worktree_path, save)
+    end
+
+    def shell_only?(info, pane)
+      info.is_a?(Hash) && info["pane_id"] == pane && info["shell_pid"].is_a?(Integer) && info["shell_pid"].positive? &&
+        info["foreground_process_group_id"] == info["shell_pid"] && info["foreground_processes"].is_a?(Array) &&
+        info["foreground_processes"].length == 1 && info["foreground_processes"].first.is_a?(Hash) &&
+        info["foreground_processes"].first["pid"] == info["shell_pid"]
+    end
+
+    def confirmed_resume_shell(execution, worktree_path)
+      pane = pane_identity(execution.fetch("pane"))
+      info = @executor.pane_process_info(execution.fetch("pane")).parsed_json&.dig("result", "process_info")
+      unless info.is_a?(Hash) && pane["terminal_id"] == execution["terminal_id"] && pane["cwd"] == worktree_path &&
+          info["pane_id"] == execution["pane"] && info.dig("guarded_prompt_origin", "terminal_id") == execution["terminal_id"] &&
+          info["guarded_prompt"] == true && info["guarded_input_drain"] == true &&
+          shell_only?(info, execution["pane"])
+        raise Ace::Overseer::Error, "failed resume has no confirmed original shell; inspect before retrying"
+      end
+      pane
+    end
+
+    def resume_transcript(execution, worktree_path)
+      candidates = if execution["resume_transcript"]
+        [execution.fetch("resume_transcript")]
+      else
+        directory = execution["credentials_directory"]
+        raise Ace::Overseer::Error, "executor has no private session directory" unless directory
+        Dir.glob(File.join(directory, "sessions", "**", "*.jsonl")).select do |path|
+          Ace::Herdr::Atoms::NativeAgentSession.normalize({"agent" => "pi", "kind" => "path", "value" => path}, agent: "pi") == execution["agent_session"]
+        end
+      end
+      raise Ace::Overseer::Error, "executor transcript is missing or ambiguous" unless candidates.length == 1
+      path = candidates.first
+      raise Ace::Overseer::Error, "executor transcript is not a regular file" unless File.file?(path) && !File.symlink?(path)
+      header = File.open(path) { |file| JSON.parse(file.readline) }
+      unless header["type"] == "session" && header["id"] == execution.dig("agent_session", "value") && header["cwd"] == worktree_path
+        raise Ace::Overseer::Error, "executor transcript identity does not match"
+      end
+      path
+    rescue JSON::ParserError, EOFError, SystemCallError
+      raise Ace::Overseer::Error, "executor transcript is unavailable or invalid"
+    end
+
     def pane_identity(pane)
       reply = @executor.pane_get(pane).parsed_json
       row = reply&.dig("result", "pane")

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ace/hitl/molecules/event_observation"
+require_relative "project_observations"
 
 module Ace
   module Overseer
@@ -12,13 +13,13 @@ module Ace
       # until answered — both are the overseer's inbox.
       class HitlInbox
         # @param manager [Ace::Hitl::Organisms::HitlManager, nil]
-        def initialize(manager: nil, owner: "overseer", scope: nil)
+        def initialize(manager: nil, owner: "overseer", scope: nil, projects: ProjectObservations.new)
           @manager = manager || Ace::Hitl::Organisms::HitlManager.new
           raise ArgumentError, "configured HITL owner is required" if owner.to_s.strip.empty?
           unless scope.nil? || %w[current all].include?(scope)
             raise ArgumentError, "HITL scope must be current or all"
           end
-          @owner, @scope = owner, scope
+          @owner, @scope, @projects = owner, scope, projects
           @observation = Ace::Hitl::Molecules::EventObservation.new(manager: @manager)
         end
 
@@ -30,7 +31,19 @@ module Ace
           events = @observation.incoming_events(owner: @owner, scope: @scope).select do |event|
             event.type == "report" || (event.type == "question" && event.status == "pending")
           end
-          events.sort_by { |event| event.created_at || Time.now }.map { |event| normalize(event) }
+          local = events.sort_by { |event| event.created_at || Time.now }.map { |event| normalize(event) }
+          projects = @projects.call(owner: @owner, scope: @scope || "all", limit: 500)
+          unless projects.fetch("sources").values.all? { |source| source["status"] == "ok" }
+            raise Ace::Overseer::Error, "project report sources are degraded; preserve pending reports"
+          end
+          remote = projects.fetch("events").select do |event|
+            event["type"] == "report" || (event["type"] == "question" && event["status"] == "pending")
+          end
+          combined = local + remote
+          if combined.group_by { |event| event.fetch("id") }.any? { |_, rows| rows.size > 1 }
+            raise Ace::Overseer::Error, "ambiguous report IDs across configured projects"
+          end
+          combined
         end
 
         private

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

@@ -195,7 +195,13 @@ module Ace
                 cwd.is_a?(String) && cwd.start_with?("/")
               raise Error, "executor session identity is invalid"
             end
-            sessions[cwd] << {"terminal" => terminal, "agent" => agent["name"]}
+            # A provider failure can end a turn while its panel stays alive and
+            # no report is written. Herdr exposes completion_seq when done and
+            # omits it while working: completion/resumption each revise once,
+            # while repeated observations of either state remain silent.
+            # This is a signal to inspect the assignment, never success proof.
+            sessions[cwd] << {"terminal" => terminal, "agent" => agent["name"],
+              "completion_seq" => agent["completion_seq"]}
           end
           sessions.transform_values { |rows| rows.sort_by { |row| row.fetch("terminal") } }
         end

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

@@ -74,6 +74,18 @@ module Ace
         end
 
 
+        def live_agent?(pane)
+          json = @executor.agent_get(pane).parsed_json
+          raise Error, "herdr returned malformed agent state" unless json.is_a?(Hash)
+          agent = json["agent"]
+          agent ||= json.dig("result", "agent") if json["result"].is_a?(Hash)
+          agent ||= json["result"] if json["result"].is_a?(Hash)
+          raise Error, "herdr returned no agent identity" unless agent.is_a?(Hash)
+          true
+        rescue Ace::Herdr::AgentNotFoundError
+          false
+        end
+
         def project_row(id, root, tabs, panes)
           label = Atoms::StartContract.session_label(root)
           owners = tabs.select { |tab| tab[:title] == label }.flat_map do |tab|
@@ -81,7 +93,12 @@ module Ace
             raise Error, "project overseer tab has no unique pane: #{label}" unless matches.length == 1
             matches
           end
-          raise Error, "project overseer has ambiguous sessions: #{label}" if owners.length > 1
+          if owners.length > 1
+            # Reconciliation preserves dead panels for diagnostics. Native
+            # agent presence, not the retained tab, identifies the live owner.
+            owners = owners.select { |owner| live_agent?(owner.fetch(:id)) }
+            raise Error, "project overseer has ambiguous sessions: #{label}" unless owners.length == 1
+          end
           pane = owners.first
           raise Error, "project overseer session did not report a working directory: #{label}" if pane && pane[:cwd].to_s.empty?
           if pane && @root_resolver.resolve(cwd: pane[:cwd]) != root

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

@@ -7,7 +7,7 @@ module Ace
       # the queue accepts success. This check owns no persisted state.
       class ReportCompletionCheck
         def initialize(handoff_probe: nil, assignment_probe_factory: nil, worktree_finder: nil)
-          @worktree_finder = worktree_finder || Ace::Git::Worktree::Organisms::WorktreeManager.new
+          @worktree_finder = worktree_finder
           @handoff_probe = handoff_probe || HandoffProbe.new
           @assignment_probe_factory = assignment_probe_factory || ->(root) {
             Ace::Coworker::Molecules::AssignmentProbe.new(project_root: root)
@@ -30,7 +30,13 @@ module Ace
           return "confirm-start requires coordinator session evidence" if role == "confirm-start"
           return "report assignment disagrees with the allocation" unless step.metadata["assignment"].to_s == assignment
 
-          found = @worktree_finder.switch(task)
+          project_root = manager.metadata["project_root"].to_s
+          if event["project_root"] && event["project_root"] != project_root
+            return "report project disagrees with the allocation"
+          end
+          finder = @worktree_finder || Ace::Git::Worktree::Organisms::WorktreeManager.new(
+            project_root: project_root.empty? ? Dir.pwd : project_root)
+          found = Dir.chdir(project_root.empty? ? Dir.pwd : project_root) { finder.switch(task) }
           return "task has no usable worktree: #{found[:error] || found[:message]}" unless found[:success]
           root = found.fetch(:worktree_path)
           legs = @handoff_probe.probe(root, task_id: task).fetch(:legs)

data/lib/ace/overseer/organisms/report_processor.rb

@@ -20,7 +20,7 @@ module Ace
           @completion_check = completion_check || Molecules::ReportCompletionCheck.new
           @inbox = inbox || Molecules::HitlInbox.new(owner: owner, scope: scope)
           @task_manager = task_manager || Ace::Task::Organisms::TaskManager.new
-          @handoff = handoff || Organisms::HandoffOrchestrator.new(task_loader: @task_manager)
+          @handoff = handoff
           @work_on = work_on || Organisms::WorkOnOrchestrator.new(task_loader: @task_manager)
           @retire = retire || Molecules::CoworkerLauncher.new.method(:retire)
         end
@@ -157,7 +157,15 @@ module Ace
 
           begin
             if family_worktree(manager)
-              result = @handoff.call(task_ref: manager.metadata["project_task"].to_s)
+              project_root = manager.metadata["project_root"].to_s
+              result = if @handoff
+                @handoff.call(task_ref: manager.metadata["project_task"].to_s)
+              else
+                Dir.chdir(project_root.empty? ? Dir.pwd : project_root) do
+                  Organisms::HandoffOrchestrator.new.call(task_ref: manager.metadata["project_task"].to_s,
+                    runtime: Ace::Support::Cli::Toolchain.installed? ? "herdr" : nil)
+                end
+              end
               record_allocation(next_step, result) if result[:execution]
               {action: "handoff", step_ref: next_step.id.to_s,
                next: result[:next], status: result[:status], worktree_path: result[:worktree_path],

data/lib/ace/overseer/organisms/start_orchestrator.rb

@@ -11,6 +11,7 @@ require "ace/herdr/molecules/installed_pi_extensions"
 require "ace/lab"
 require "ace/support/cli/toolchain"
 require "json"
+require "digest"
 require "open3"
 
 module Ace
@@ -594,7 +595,7 @@ module Ace
               @executor.pane_run(pane, command)
               @executor.pane_wait_output(pane, pattern: marker, timeout_ms: START_TIMEOUT_MS)
             end
-            @executor.agent_start(name: AGENT_NAME, kind: plan["profile"]["harness"],
+            @executor.agent_start(name: "#{AGENT_NAME}-#{Digest::SHA256.hexdigest(root)[0, 12]}", kind: plan["profile"]["harness"],
               pane: pane, timeout_ms: START_TIMEOUT_MS, args: args)
           end
           pane
@@ -611,7 +612,7 @@ module Ace
           credentials = nil
           Molecules::SessionEnvironment.new(env: @env).with_environment(root: root, role: role) do |file, directory, _profile|
             credentials = directory
-            @executor.agent_start(name: AGENT_NAME, kind: plan["profile"]["harness"],
+            @executor.agent_start(name: "#{AGENT_NAME}-#{Digest::SHA256.hexdigest(root)[0, 12]}", kind: plan["profile"]["harness"],
               pane: pane, timeout_ms: START_TIMEOUT_MS, args: args, env_file: file)
           end
         rescue StandardError, Interrupt

data/lib/ace/overseer/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Overseer
-    VERSION = "0.30.1"
+    VERSION = "0.30.2"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.30.1
+  version: 0.30.2
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-11-11 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -80,7 +80,7 @@ dependencies:
         version: '0.70'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.73.1
+        version: 0.73.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -90,7 +90,7 @@ dependencies:
         version: '0.70'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.73.1
+        version: 0.73.3
 - !ruby/object:Gem::Dependency
   name: ace-git
   requirement: !ruby/object:Gem::Requirement
@@ -160,7 +160,7 @@ dependencies:
         version: '0.8'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.9.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -170,7 +170,7 @@ dependencies:
         version: '0.8'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.9.1
 - !ruby/object:Gem::Dependency
   name: ace-hitl
   requirement: !ruby/object:Gem::Requirement
@@ -180,7 +180,7 @@ dependencies:
         version: '0.24'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.25.1
+        version: 0.26.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -190,7 +190,7 @@ dependencies:
         version: '0.24'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.25.1
+        version: 0.26.0
 - !ruby/object:Gem::Dependency
   name: ace-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -234,7 +234,7 @@ dependencies:
         version: '0.9'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.11.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -244,7 +244,7 @@ dependencies:
         version: '0.9'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.11.1
 - !ruby/object:Gem::Dependency
   name: ace-lab
   requirement: !ruby/object:Gem::Requirement