RubyGems - ace-overseer - Versions diffs - 0.27.0 → 0.28.0 - Mend

ace-overseer 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +27 -0
data/docs/usage.md +53 -13
data/handbook/workflow-instructions/overseer/bootstrap-delegation.wf.md +88 -0
data/handbook/workflow-instructions/overseer/lab-start.wf.md +41 -9
data/lib/ace/overseer/atoms/start_contract.rb +25 -12
data/lib/ace/overseer/cli/commands/start.rb +33 -16
data/lib/ace/overseer/molecules/event_observation.rb +21 -2
data/lib/ace/overseer/molecules/project_bundle.rb +119 -0
data/lib/ace/overseer/organisms/start_orchestrator.rb +163 -86
data/lib/ace/overseer/version.rb +1 -1
metadata +8 -12

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5204d8b317b630a73e16ddc196fc90c3d6efa1e0f39a62406e1b6f7bd6de4c2e
-  data.tar.gz: 5293bfde27b37ca690442f2ffcc60446913ec54052b2426b47d82c55d48c1614
+  metadata.gz: c0228801ebed27e7b1fca7fe8f580dc4fdc2a5a5be9e8d76d3c6cf59b1f8cf48
+  data.tar.gz: 2fae06ba1fc9174fc41f53f3ddcbcc1ee8dddd0152faaaa7e894a862d6f0e8c5
 SHA512:
-  metadata.gz: 96747e1a1d70f884fb302110f0f12197b81a4b6a7701ce0ef0aeb000581daaae7bc6ccb7660f15fdf1ef067e6c879c0e3c86e774881b99ffdd351ec82204a740
-  data.tar.gz: 61e8da9b71790c8f7f5252e61652d4d7af4dd881d4bb8e716504c84ee60cfc1af3e784f0c5d8172d096e471d353d010e674984a9cee99d1a0b63e1e40d0c9eac
+  metadata.gz: 2ede68b20a4104eeb494014ca34a05627e8367aa5d1b6cf71cbd5f8fcfa0e4168e2029c3ca78be121e353e3e24a25bc0dd0c5ae153850b9797a7bff5bf504e6c
+  data.tar.gz: 611af27c6c2b7febc096cefeaff5545d8f3ce7fd1dd9e377932371359c850ec0e1f757476d9ffba937135f3ea021bd87f4c268007ab81b0e571c1723b48c4d88

data/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+## [0.28.0] - 2026-10-31
+### Fixed
+- Delegate lab bootstrap to workers and independent verification; distinguish
+  preparation/printed briefs from running agents and confirmed first turns.
+- Preserve installed operational runtime across project starts.
+- Normalize local observation identities for the eyes wire contract.
+## [0.28.0.pre.3] - 2026-10-31
+### Fixed
+- Child project bundles no longer inherit a forced Lab `ACE_TOOLCHAIN` mode;
+  project-selected path/source dependencies and explicit child policies remain
+  authoritative. The Lab role may perform routine project startup setup without
+  taking over project deliverables.
+- `ace-overseer start` bootstraps missing start settings and becomes the Lab
+  coordinator in the current terminal without Herdr preflight. Explicit
+  `start --reconcile` manages project children after agent initialization. The coordinator can configure itself using the packaged guide.
+- Lab and project workspaces use `overseer` and topology ids such as `ace`,
+  independently of session ownership labels. Project startup executes each
+  project's own Gemfile/lock and binstub in a separate process; project panes
+  use their own bundle instead of inheriting the Lab's gem runtime.
 ## [0.27.0] - 2026-10-30
 ### Fixed (review rounds 3/3b)

data/docs/usage.md CHANGED Viewed

@@ -32,14 +32,21 @@ authority execution model. tmux and Herdr are transports, never state owners.
 ## `ace-overseer start`
-Start or reuse the PROJECT overseer session from the directory's own
-configuration (task 8xs.t.pu0.1). The start contract is explicit — nothing is
-guessed and no interim default model applies:
+Run `ace-overseer start` at a shell in the Lab's existing Herdr `overseer`
+space. The command becomes the Lab's Pi agent directly in that same terminal
+and cwd, without any Herdr environment, agent, owner or layout preflight. The agent receives the packaged Lab guide
+and a first-turn prompt to delegate configuration of commissioned projects
+using installed CLI, skills and normal configuration editing.
+No local start YAML is required for first run. The packaged bootstrap profile
+is `pi`, `zai/glm-5.3-flash`, thinking `high`, in Lab scope. An explicit start
+section overrides bootstrap and is validated without fallback. For an
+explicit project start use:
 ```yaml
 # .ace/overseer/config.yml (project tier of the cascade)
 start:
-  scope: project            # project | lab (lab: not implemented yet)
+  scope: project            # project | lab
   profile: overseer-default # reference into the profiles map below
   instructions: wfi://overseer/start  # handbook source (or absolute file path)
 profiles:
@@ -53,6 +60,8 @@ profiles:
 |--------|---------|
 | `--dry-run` | Show the start plan; no session, no sync, no model call |
 | `--format` | `table` (default) or `json` |
+| `--reconcile` | Explicitly reconcile project children after the agent configures the Lab; never restart the coordinator |
+| `--scope` | Explicit `lab` or `project` role; an unconfigured bare start bootstraps the Lab |
 Behavior:
@@ -86,15 +95,37 @@ Behavior:
 - The report carries `status` (`started|reused|blocked|dry_run`), `scope`,
   `root`, `label`, `workspace`, `pane`, `agent`, `profile`, `instructions`
   (`source` + resolved `path`) and a `message`. Exit 0 only for a ready
-  start/reuse (dry-run included); a blocked start is a CLI error naming the
-  missing configuration.
+  start/reuse (dry-run included); a blocked start is a CLI error naming the concrete invalid configuration
+  or unavailable capability.
 - The started overseer coordinates and delegates (guide:
   `wfi://overseer/start`); it never substitutes for a missing coworker.
+### Project-local bundles
+In auto mode each project owns its Gemfile/lock and binstubs. Child starts
+clear parent Bundler/Ruby injection and select the project's bundle.
+Explicit `ACE_TOOLCHAIN=installed` is preserved instead: the installed
+Toolchain launcher and gem closure start the child without reading its
+Gemfile or executing its binstub. Missing installed dependencies fail visibly;
+there is no fallback to checkout code. Terminal backend selection does not
+change toolchain mode.
+The lab overseer delegates bundle/configuration preparation to a lab worker;
+it never edits the project's binstub or installs gems itself. Follow
+`wfi://overseer/bootstrap-delegation` for the task, worker, independent
+verification and observed completion cycle. `ace-coworker start` prints a
+brief; a separate Herdr agent launch and first prompt are required.
 ### Lab scope (8xs.t.pu0.a)
 `scope: lab` in the LAB coordination directory's own `.ace/overseer/config.yml`
-starts the whole lab from one external entry point:
+selects the Lab role. Bare `start` launches the foreground harness;
+`start --reconcile` is the explicit tool the agent uses after configuring its
+projects. Reconciliation manages project children without restarting or probing
+the Lab coordinator. The older full orchestration operation remains available
+explicitly through `start --scope lab`:
 - The project list and CANONICAL locations come from the existing ace-lab
   topology (`topology.projects` id/path, read internally — the public
@@ -105,17 +136,14 @@ starts the whole lab from one external entry point:
   per-project (a nested lab start never recurses). An unreadable topology
   (missing or unparseable `.ace/lab/config.yml`) is a blocked start with
   the concrete cause.
-- The lab creates/reuses its own herdr space (`lab-overseer` — namespaced
-  so it can never collide with a session/space title derived from a project
-  directory name, e.g. a project rooted at a directory named `lab` owns
-  `overseer-lab`) and boots or
+- The lab creates/reuses its own herdr space (`overseer`, reserved for the Lab) and boots or
   reuses the lab's OWN overseer session there (label `overseer-<lab-root>`,
   cwd at the lab root, the lab guide as standing instructions, first-turn
   prompt included) — the lab-start instructions always reach a real agent,
   and an empty configured project list still runs the lab overseer (idle).
-- EACH project then starts or is found through the SAME operation as a
+- EACH project then starts or is found through its own bundle and the SAME operation as a
   standalone start (its own cascade, root, and session identity) in its OWN
-  herdr space, titled by its session label (`overseer-<project>`) and
+  herdr space, titled by its topology id (for example `ace`) and
   created/reused by title by the lab flow — project sessions are isolated
   from each other and from the lab overseer, never share one space, and
   never re-resolve the caller's ambient workspace (a plain terminal without
@@ -532,3 +560,15 @@ ace-overseer prune --dry-run
 ace-overseer prune --yes
 ace-overseer prune --dry-run
 ```
+### Workspace names and foreground instructions
+Topology IDs reserve workspace titles for the commissioned lab projects.
+Reconciliation may reuse an existing workspace with that title, but never
+replaces its manual panes; project ownership is the stable overseer tab label
+plus canonical cwd, not the mutable terminal title. Ambiguous ownership blocks.
+Foreground bootstrap pins the two built-in start guides to their packaged
+files. An explicit custom instruction source remains configurable; missing
+files block before launching Pi. Project development dependencies do not select
+the operational runtime when installed mode is chosen.

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

@@ -0,0 +1,88 @@
+---
+name: overseer-bootstrap-delegation
+description: Delegate project startup to lab workers and accept their observed results
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Delegated Project Bootstrap
+purpose: Complete one lab-owned startup commission without the overseer doing the repair.
+---
+# Delegated project bootstrap
+## Commission and ownership
+Read existing tasks and assignments first. Reuse the open commission for the
+same project and goal; unknown execution state never means free capacity.
+Create one lab coordination task in `_overseer`, with three direct children:
+prepare, independently verify, confirm start. The latter two depend on their
+predecessor. Only the lab overseer updates this private tree.
+Create a separate executable lab task through `ace-task` for the bootstrap
+work, linking it as the manager's `project_task`. Keep its specification in
+its task folder. Include the canonical target repository path, required
+configuration, allowed changes, runtime mode, acceptance checks and report
+recipient. This is lab infrastructure work, not a project product task.
+Workers must not edit the private coordination tree.
+Explicit `ACE_TOOLCHAIN=installed` remains installed in every subprocess,
+worker and resumed session. The project checkout is domain data. Never modify
+tracked binstubs to bypass this selection. In auto mode retain the project's
+own dependency model. If package code is defective, commission its repair;
+do not patch installed gems. Preserve unrelated changes.
+## Arm eyes before dispatch
+Use the lab's existing eyes JSON configuration. The `ace_eyes` tool accepts
+`{"action":"start","configPath":"<absolute eyes JSON path>"}`.
+Inspect the returned state: enabled=true, breaker=null, errors=0 and at least
+one observation. Read pending revisions from their original owners, reconcile
+existing commissions, and ack each exact key/revision only after acceptance.
+A missing extension, invalid configuration or degraded source blocks dispatch;
+report that capability gap. Do not claim that mentioning `/eyes` armed it.
+## Prepare and actually launch a worker
+Use `ace-coworker prepare --task <executable-task> --roles bootstrap-worker,bootstrap-verifier
+--to <configured-overseer-address> --format json`. Read its returned worktree,
+assignment IDs and start-config paths; record these on the matching private
+steps before launch. A preparation readiness report is not worker completion.
+The task must be present in the execution worktree before any agent starts.
+`ace-coworker start --config <returned-path>` validates and prints a brief;
+it does NOT launch an agent. Use the configured Herdr provider/profile to
+start a separate worker agent in the returned worktree, load the returned
+role instructions, and send its first prompt. The prompt commissions only
+that task and pinned assignment, requires the worker to read its start brief,
+drive that assignment, and finish with `ace-coworker report`. These operational roles explicitly allow the commissioned canonical target
+outside the lab task worktree; ordinary product worker/reviewer roles do not.
+Use CLI help for
+Herdr's current arguments. Record the returned pane/agent identity and verify
+first-turn delivery. Never replace a missing executor with your own work.
+End the overseer's turn immediately after dispatch. The eyes timer observes
+assignment and HITL revisions without invoking the model on unchanged state.
+## Receive, verify, start
+On wake, read the original report and current assignment. Require matching
+report ID, task, assignment and role; a preparation report, process exit or
+unmatched message is not success. Use `ace-overseer process-reports --dry-run`
+to inspect the matching and continuation before applying it. Only accept
+worker success with a completed non-empty assignment and the promised evidence.
+Record receipt through task APIs before acknowledging the eyes revision.
+Use the existing role handoff gate to prepare the independent reviewer after
+worker completion. As with the worker, a printed start command is not a live
+agent: launch the reviewer separately with its own returned role/config and
+confirm first-turn delivery. Do not launch a second executor while an earlier
+one is active or its state is unknown. On repeated delivery, reconcile existing
+assignments and agents instead of dispatching again.
+After accepted independent verification, the overseer performs its coordination
+operation `ace-overseer start --reconcile`. Confirm the target's session, first
+turn and active eyes from actual session evidence. A ready process alone is
+not initialized observation. Close the confirmation step and managing task
+only with these proofs; the worker report alone cannot close the family.
+On error, keep the step open and route repair to the worker. Missing authority
+or an actual Captain decision becomes a precise HITL question; end the turn
+armed for its answer. Never self-repair or use sleep-poll while waiting.

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

@@ -1,7 +1,7 @@
 ---
 name: overseer-lab-start
 description: Standing instructions for a started LAB overseer session (aggregate project readiness, escalate across projects, delegate to project overseers)
-allowed-tools: Bash, Read
+allowed-tools: Bash, Read, Write, Edit
 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.
@@ -20,21 +20,53 @@ aggregating their status and escalations, and routing the Captain's goals to
 the right project. You never take over a project's tasks, worktrees, or
 private `_overseer` state — those belong to each project's overseer.
+You own the OUTCOME of routine startup, never its execution. Configuration,
+Bundler installation, dependency repairs and binstub generation are WORKER
+work. Create a commission and dispatch a separate lab worker even when the
+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.
 ## First turn after start
-1. Read your own coordination tasks: `ace-task --in _overseer list`.
-2. Read per-project readiness from the start report and the state owners
-   (`ace-overseer status`); a project reported `blocked` is an escalation
-   with its concrete reason, never something to work around by starting a
-   duplicate session or doing the project's work yourself.
-3. Re-run `ace-overseer start` to repair missing pieces only — it reuses
-   healthy sessions and never restarts them or closes manual panes.
+`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.
+The Captain's latest instruction outranks this guide and stored tasks or plans.
+On this first turn, establish your own configuration and the commissioned
+project overseers before resuming unrelated stored backlog. Read old
+`_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
+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.
+3. Arm observation with the `ace_eyes` tool, action `start`, using the lab's
+   eyes configuration path. Check enabled=true, breaker=null, errors=0 and
+   a successful observation before dispatch. A missing tool/configuration is
+   a readiness gap. Writing `/eyes` in prose does not arm observation.
+4. Use `ace-overseer start --reconcile` to inspect/start commissioned project
+   sessions. Bare `ace-overseer start` launches a foreground harness; never
+   call it recursively from your own session. Delegate preparation or repair
+   of blocked projects to a lab worker through the bootstrap procedure.
+5. After dispatch, record the real assignment and agent identity and END YOUR
+   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
-  coworkers directly.
+  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.

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

@@ -3,14 +3,9 @@
 module Ace
   module Overseer
     module Atoms
-      # Pure validation and normalization of the `start` contract
-      # (task 8xs.t.pu0.1): the `.ace/overseer/config.yml` cascade must
-      # carry an EXPLICIT start section — `scope: project|lab`, a
-      # `profile` reference into the same document's `profiles` map and
-      # an `instructions` source (wfi:// or an absolute file path).
-      # Nothing is guessed: a missing or ambiguous section is an error
-      # BEFORE any session is created, and no interim default model is
-      # applied anywhere. Pure — no IO, value-free messages.
+      # Validate explicit start configuration, or select the packaged
+      # first-run profile when no start section exists. A malformed explicit
+      # configuration never falls back to another model or harness.
       class StartContract
         SCOPES = %w[project lab].freeze
         SECTION_KEYS = %w[scope profile instructions].freeze
@@ -23,7 +18,25 @@ module Ace
         #   thinking:}, instructions:}
         # @raise [Ace::Overseer::Error] missing/ambiguous/invalid start
         #   configuration
+        BOOTSTRAP_PROFILE = {"harness" => "pi", "model" => "zai/glm-5.3-flash",
+                             "thinking" => "high"}.freeze
+        # A missing start configuration is first-run setup, not a reason to
+        # prevent the coordinator that owns setup from starting. Explicit
+        # configurations are still validated without fallback.
+        def self.bootstrap(config, scope: "lab")
+          return config if config.key?("start")
+          profiles = config.fetch("profiles", {})
+          raise Ace::Overseer::Error, "profiles must be a mapping" unless profiles.is_a?(Hash)
+          config.merge("start" => {"scope" => scope, "profile" => "overseer-default",
+                                   "instructions" => "wfi://overseer/#{(scope == "lab") ? "lab-start" : "start"}"},
+            "profiles" => {"overseer-default" => BOOTSTRAP_PROFILE}.merge(profiles))
+        end
         def self.normalize(config)
+          config = bootstrap(config)
           start = config["start"]
           unless start.is_a?(Hash)
             raise Ace::Overseer::Error,
@@ -36,13 +49,13 @@ module Ace
           unless unknown.empty?
             raise Ace::Overseer::Error,
               "start section has unknown key '#{unknown.sort.first}' " \
-              "(allowed: #{SECTION_KEYS.join(', ')})"
+              "(allowed: #{SECTION_KEYS.join(", ")})"
           end
           scope = required(start, "scope")
           unless SCOPES.include?(scope)
             raise Ace::Overseer::Error,
-              "start scope must be one of: #{SCOPES.join(', ')} (got '#{scope}')"
+              "start scope must be one of: #{SCOPES.join(", ")} (got '#{scope}')"
           end
           profile_name = required(start, "profile")
@@ -50,7 +63,7 @@ module Ace
           instructions = required(start, "instructions")
           unless INSTRUCTION_PROTOCOLS.any? { |prefix| instructions.start_with?(prefix) } ||
-            instructions.start_with?("/")
+              instructions.start_with?("/")
             raise Ace::Overseer::Error,
               "start instructions must be a wfi:// (or prompt://, tmpl://) " \
                 "source or an absolute file path"
@@ -81,7 +94,7 @@ module Ace
           unless unknown.empty?
             raise Ace::Overseer::Error,
               "profile '#{profile_name}' has unknown key '#{unknown.sort.first}' " \
-                "(allowed: #{PROFILE_KEYS.join(', ')})"
+                "(allowed: #{PROFILE_KEYS.join(", ")})"
           end
           harness = required_value(raw, "harness", "profile '#{profile_name}'")

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

@@ -16,19 +16,36 @@ module Ace
           desc "Start or reuse the project overseer session from .ace/overseer/config.yml"
+          option :reconcile, type: :boolean, default: false, desc: "Explicitly reconcile configured project overseers without restarting the lab coordinator"
+          option :scope, type: :string, desc: "Coordinator role (lab or project); omitted means lab bootstrap"
           option :dry_run, type: :boolean, default: false, desc: "Show the start plan without creating a session"
           option :format, default: "table", desc: "Output format (table, json)"
           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"
-          def initialize(orchestrator: nil, config: nil)
+          def initialize(orchestrator: nil, config: nil, launcher: nil)
             super()
             @orchestrator = orchestrator
             @config = config
+            @launcher = launcher || ->(argv) { Kernel.exec(*argv) }
           end
-          def call(dry_run: false, format: "table", **options)
-            report = orchestrator.call(dry_run: dry_run)
+          def call(dry_run: false, format: "table", scope: nil, reconcile: false, **options)
+            unless scope.nil? || Atoms::StartContract::SCOPES.include?(scope)
+              raise Ace::Support::Cli::Error, "scope must be lab or project"
+            end
+            if reconcile && scope == "project"
+              raise Ace::Support::Cli::Error, "--reconcile requires lab scope"
+            end
+            operation = orchestrator(scope: scope)
+            report = if reconcile
+              operation.reconcile(dry_run: dry_run)
+            elsif scope
+              operation.call(dry_run: dry_run)
+            else
+              operation.bootstrap(dry_run: dry_run)
+            end
+            return @launcher.call(report.fetch("command")) if report["status"] == "foreground"
             if options[:quiet]
               # quiet still fails loudly on a blocked start
@@ -51,24 +68,24 @@ module Ace
           private
-          def orchestrator
-            @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config)
+          def orchestrator(scope: nil)
+            @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config, scope: scope)
           end
           def render_table(report)
-            puts "ace-overseer start: #{report['status']}"
-            puts "  scope:         #{report['scope'] || '-'}"
-            puts "  root:          #{report['root'] || '-'}"
-            puts "  label:         #{report['label'] || '-'}"
-            puts "  profile:       #{report['profile'] || '-'}"
+            puts "ace-overseer start: #{report["status"]}"
+            puts "  scope:         #{report["scope"] || "-"}"
+            puts "  root:          #{report["root"] || "-"}"
+            puts "  label:         #{report["label"] || "-"}"
+            puts "  profile:       #{report["profile"] || "-"}"
             if report["instructions"]
-              puts "  instructions:  #{report['instructions']['source']} -> #{report['instructions']['path']}"
+              puts "  instructions:  #{report["instructions"]["source"]} -> #{report["instructions"]["path"]}"
             end
-            puts "  workspace:     #{report['workspace'] || '-'}"
-            puts "  pane:          #{report['pane'] || '-'}"
-            puts "  agent:         #{report['agent']}"
-            puts "  replaced pane: #{report['replaced_pane'] || '-'}" if report["replaced_pane"]
-            puts "  #{report['message']}" if report["message"]
+            puts "  workspace:     #{report["workspace"] || "-"}"
+            puts "  pane:          #{report["pane"] || "-"}"
+            puts "  agent:         #{report["agent"]}"
+            puts "  replaced pane: #{report["replaced_pane"] || "-"}" if report["replaced_pane"]
+            puts "  #{report["message"]}" if report["message"]
           end
         end
       end

data/lib/ace/overseer/molecules/event_observation.rb CHANGED Viewed

@@ -44,8 +44,9 @@ module Ace
             sources = local.fetch("sources").merge(remote.fetch("sources")).merge(
               "hitl" => {"status" => "degraded", "error" => "#{hitl_error.class}: #{hitl_error.message}"}
             )
+            ensure_budget!(events.length, limit)
             return {"schema" => "ace.hitl.observation/v1",
-                    "events" => events.sort_by { |row| row["key"] },
+                    "events" => wire_events(events).sort_by { |row| row["key"] },
                     "settled" => [], "sources" => sources}
           end
@@ -60,7 +61,8 @@ module Ace
             manager && ([manager] + Array(manager.subtasks)).all? { |task| Ace::Task::Atoms::TaskValidationRules.terminal_status?(task.status.to_s) }
           end
-          projection.merge("events" => (pending + local.fetch("events") + remote.fetch("events"))
+          ensure_budget!(pending.length + settled.length + local.fetch("events").length + remote.fetch("events").length, limit)
+          projection.merge("events" => (pending + wire_events(local.fetch("events") + remote.fetch("events")))
               .sort_by { |row| row["key"] },
             "settled" => settled,
             "sources" => local.fetch("sources").merge(remote.fetch("sources"))
@@ -69,6 +71,23 @@ module Ace
         private
+        def ensure_budget!(count, limit)
+          return if count <= limit
+          raise ArgumentError, "observation has #{count} rows, exceeding limit #{limit}; increase maxEvents/--limit or archive accepted history before arming eyes"
+        end
+        # Local owners expose readable keys, whereas eyes consumes the HITL
+        # wire envelope (hashed key, revision and a safe id). Normalize only
+        # local/remote rows; canonical HITL identities remain untouched.
+        def wire_events(rows)
+          rows.map do |row|
+            key = Digest::SHA256.hexdigest("overseer:#{row.fetch('key')}")
+            row.merge("source_key" => row.fetch("key"), "source_id" => row["id"],
+              "key" => key, "id" => key)
+          end
+        end
         # Configured remote observation (8xs.t.pu0.4): the project's own
         # observe.remote.pull_requests list — never a scan of accessible
         # accounts. No configuration means no remote rows and no remote

data/lib/ace/overseer/molecules/project_bundle.rb ADDED Viewed

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+require "json"
+require "ace/herdr/molecules/bounded_process"
+require "shellwords"
+require "ace/support/cli/toolchain"
+module Ace
+  module Overseer
+    module Molecules
+      # A project's own Gemfile/lock and binstub select its ACE version.
+      # Never load child project gems into the lab coordinator's process.
+      class ProjectBundle
+        # A new Herdr shell inherits the server environment, which may differ
+        # from this CLI's environment. Clear known Bundler selectors even
+        # when the requesting process did not have them set.
+        BUNDLE_SELECTORS = %w[
+          BUNDLE_ALLOW_OFFLINE_INSTALL BUNDLE_APP_CONFIG BUNDLE_AUTO_INSTALL
+          BUNDLE_BIN BUNDLE_BIN_PATH BUNDLE_CACHE_ALL BUNDLE_CACHE_ALL_PLATFORMS
+          BUNDLE_CACHE_PATH BUNDLE_CLEAN BUNDLE_CONSOLE BUNDLE_DEPLOYMENT
+          BUNDLE_DISABLE_CHECKSUM_VALIDATION BUNDLE_DISABLE_EXEC_LOAD
+          BUNDLE_DISABLE_LOCAL_BRANCH_CHECK BUNDLE_DISABLE_LOCAL_REVISION_CHECK
+          BUNDLE_DISABLE_SHARED_GEMS BUNDLE_DISABLE_VERSION_CHECK
+          BUNDLE_FORCE_RUBY_PLATFORM BUNDLE_FORGET_CLI_OPTIONS BUNDLE_FROZEN
+          BUNDLE_GEMFILE BUNDLE_GEM__BUNDLE BUNDLE_GEM__CHANGELOG BUNDLE_GEM__CI
+          BUNDLE_GEM__COC BUNDLE_GEM__GITHUB_USERNAME BUNDLE_GEM__LINTER
+          BUNDLE_GEM__MIT BUNDLE_GEM__RUBOCOP BUNDLE_GEM__TEST
+          BUNDLE_GIT__ALLOW_INSECURE BUNDLE_GLOBAL_GEM_CACHE BUNDLE_IGNORE_CONFIG
+          BUNDLE_IGNORE_MESSAGES BUNDLE_INIT_GEMS_RB BUNDLE_INLINE BUNDLE_JOBS
+          BUNDLE_LOCKFILE_CHECKSUMS BUNDLE_NO_INSTALL BUNDLE_NO_PRUNE BUNDLE_ONLY
+          BUNDLE_PATH BUNDLE_PATH__SYSTEM BUNDLE_PLUGINS BUNDLE_PREFER_PATCH
+          BUNDLE_REDIRECT BUNDLE_RETRY BUNDLE_SHEBANG BUNDLE_SILENCE_DEPRECATIONS
+          BUNDLE_SILENCE_ROOT_WARNING BUNDLE_SIMULATE_VERSION BUNDLE_SSL_CA_CERT
+          BUNDLE_SSL_CLIENT_CERT BUNDLE_SSL_VERIFY_MODE BUNDLE_SYSTEM_BINDIR
+          BUNDLE_TIMEOUT BUNDLE_TRUST___POLICY BUNDLE_UPDATE_REQUIRES_ALL_FLAG
+          BUNDLE_USER_HOME BUNDLE_USER_CONFIG BUNDLE_USER_CACHE BUNDLE_USER_PLUGIN
+          BUNDLE_VERBOSE BUNDLE_VERSION BUNDLE_WITH BUNDLE_WITHOUT
+          BUNDLER_SETUP BUNDLER_VERSION
+        ].freeze
+        RUBY_SELECTORS = %w[RUBYOPT RUBYLIB GEM_HOME GEM_PATH ACE_TOOLCHAIN].freeze
+        def self.environment(root, env: ENV)
+          if Ace::Support::Cli::Toolchain.installed?
+            # Reuse the installed closure; the project checkout is domain data.
+            # Do not let a project binstub or Gemfile select source dependencies.
+            return Ace::Support::Cli::Toolchain.child_environment.merge(
+              "HERDR_PANE" => nil, "HERDR_TAB" => nil,
+              "HERDR_PANE_ID" => nil, "HERDR_TAB_ID" => nil
+            )
+          end
+          known = BUNDLE_SELECTORS + RUBY_SELECTORS
+          names = env.keys.grep(/\ABUNDLER?_/) + known +
+            (known + %w[PATH]).map { |key| "BUNDLER_ORIG_#{key}" } +
+            %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID]
+          names.to_h { |name| [name, nil] }.merge(
+            "BUNDLE_GEMFILE" => File.file?(File.join(root, "Gemfile")) ? File.join(root, "Gemfile") : nil,
+            "PATH" => [File.join(root, "bin"), env.fetch("PATH", "/usr/bin:/bin")].join(File::PATH_SEPARATOR)
+          )
+        end
+        def self.shell_setup(root, env: ENV)
+          if Ace::Support::Cli::Toolchain.installed?
+            # A server-created shell may contain selectors absent from this
+            # caller. Clear the same known selectors before applying the
+            # installed closure; never inherit server-side Bundler injection.
+            names = BUNDLE_SELECTORS + BUNDLE_SELECTORS.map { |key| "BUNDLER_ORIG_#{key}" }
+            return "unset #{names.map { |name| Shellwords.escape(name) }.join(' ')}; " +
+              Ace::Support::Cli::Toolchain.shell_setup
+          end
+          values = environment(root, env: env).reject { |name, _| %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID].include?(name) }
+          cleared, assigned = values.partition { |_, value| value.nil? }
+          "unset #{cleared.map { |name, _| Shellwords.escape(name) }.join(" ")}; export " +
+            assigned.map { |name, value| "#{name}=#{Shellwords.escape(value)}" }.join(" ")
+        end
+        def initialize(timeout_s: 240)
+          @timeout_s = timeout_s
+        end
+        def call(root:, workspace:, env: ENV)
+          installed = Ace::Support::Cli::Toolchain.installed?
+          unless installed
+            %w[Gemfile Gemfile.lock].each do |name|
+              unless File.file?(File.join(root, name))
+                raise Ace::Overseer::Error, "project bundle missing #{name}; prepare this project's own bundle first"
+              end
+            end
+          end
+          binary = installed ? Ace::Support::Cli::Toolchain.executable("ace-overseer") : File.join(root, "bin", "ace-overseer")
+          command = File.executable?(binary) ? [binary] : ["bundle", "exec", "ace-overseer"]
+          command += ["start", "--scope", "project", "--format", "json"]
+          child_env = self.class.environment(root, env: env).merge("HERDR_WORKSPACE_ID" => workspace)
+          result = Ace::Herdr::Molecules::BoundedProcess.call(command,
+            environment: ENV.to_h.merge(child_env).compact, chdir: root,
+            timeout_s: @timeout_s, output_limit: 1_048_576)
+          raise Ace::Overseer::Error, "project start output exceeded its limit" if result.oversized
+          out, err, status = result.stdout, result.stderr, result.status
+          report = JSON.parse(out)
+          unless report.is_a?(Hash) && report["scope"] == "project" && report["status"].is_a?(String)
+            raise Ace::Overseer::Error, "project start returned no project-scope report"
+          end
+          if !status.success? && %w[started reused ready].include?(report["status"])
+            raise Ace::Overseer::Error, "project start exited #{status.exitstatus} despite a ready report"
+          end
+          report
+        rescue Timeout::Error
+          raise Ace::Overseer::Error, "project start timed out after #{@timeout_s}s; inspect the existing session before retrying"
+        rescue Ace::Herdr::Molecules::BoundedProcess::PostLaunchError => e
+          raise Ace::Overseer::Error, "project start outcome is uncertain: #{e.message}"
+        rescue JSON::ParserError
+          raise Ace::Overseer::Error, "project bundle start returned invalid JSON#{": " + err.strip[0, 300] unless err.to_s.empty?}"
+        rescue SystemCallError => e
+          raise Ace::Overseer::Error, "project bundle could not start: #{e.message}"
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 require_relative "../atoms/start_contract"
 require_relative "../molecules/project_root_resolver"
+require_relative "../molecules/project_bundle"
 require "ace/herdr"
 require "ace/support/cli/toolchain"
 require "json"
@@ -9,13 +10,10 @@ require "json"
 module Ace
   module Overseer
     module Organisms
-      # `ace-overseer start` (task 8xs.t.pu0.1): boots or reuses the
-      # PROJECT overseer session from the directory's own configuration
-      # — an explicit `start` section (scope/profile/instructions) in
-      # the `.ace/overseer/config.yml` cascade, a profile from the same
-      # document's `profiles` map, and the guide resolved through the
-      # normal handbook override chain. No interim defaults: a missing
-      # or ambiguous configuration is a blocked start, never a guess.
+      # `ace-overseer start` boots the Lab in the calling Herdr terminal,
+      # or starts/reuses configured project sessions. Missing start config
+      # uses the packaged bootstrap profile so the coordinator can configure
+      # itself. Explicit malformed configuration remains a blocked start.
       #
       # Session identity is Herdr's: the tab/pane label
       # `overseer-<project>` derives from the canonical repository root
@@ -34,12 +32,9 @@ module Ace
         # turn must BEGIN within this window (herdr enforces its own
         # 5s activity observation inside the wait).
         FIRST_TURN_TIMEOUT_MS = 120_000
-        # The lab's own herdr space title. Namespaced ("lab-overseer",
-        # never "overseer-…") so it can never collide with a session or
-        # per-project space title derived from a directory name — e.g. a
-        # project rooted at a directory literally named "lab" owns the
-        # session/space title "overseer-lab".
-        LAB_SPACE_TITLE = "lab-overseer"
+        # Workspace display names are separate from session identities.
+        # `overseer` belongs to the Lab; project spaces use topology ids.
+        LAB_SPACE_TITLE = "overseer"
         # `herdr agent start` success only means the interactive agent is
         # READY for input — the session begins its first turn when this
         # prompt arrives, exactly as the standing instructions' "First
@@ -48,9 +43,10 @@ module Ace
           Begin your first turn now. Follow the "First turn after start"
           section of your standing instructions: read your private
           _overseer tasks and the project state from its owners, continue
-          existing commissioned work before choosing anything new, arm
-          /eyes for standing observation, and remain idle when there is
-          nothing to do.
+          existing commissioned work before choosing anything new. Arm
+          standing observation with the ace_eyes tool, action start and
+          configPath naming your eyes configuration; verify its returned
+          observation state. Remain idle when there is nothing to do.
         PROMPT
         attr_reader :cwd
@@ -69,14 +65,18 @@ module Ace
         #   lazily, only when a session actually boots.
         # @param cwd [String] invocation directory
         def initialize(config: nil, executor: nil, root_resolver: nil, nav_runner: nil,
-          workspace: nil, workspace_factory: nil, cwd: Dir.pwd)
+          workspace: nil, workspace_factory: nil, cwd: Dir.pwd, env: ENV, scope: nil, project_runner: nil)
           @config = config || Ace::Overseer.config
           @executor = executor || Ace::Herdr::Molecules::HerdrExecutor.new
+          @control_surface = Ace::Herdr::Organisms::ControlSurface.new(executor: @executor)
           @root_resolver = root_resolver || Molecules::ProjectRootResolver.new
           @nav_runner = nav_runner || method(:run_nav)
           @workspace = workspace
           @workspace_factory = workspace_factory
           @cwd = cwd
+          @env = env
+          @scope = scope
+          @project_runner = project_runner || Molecules::ProjectBundle.new
         end
         # @param dry_run [Boolean] report the plan without creating a
@@ -86,7 +86,10 @@ module Ace
         #   replaced_pane, message}; scope lab additionally carries
         #   {projects: [{id, path, status, ...}], project_count, ready}
         def call(dry_run: false)
-          plan = Atoms::StartContract.normalize(@config)
+          plan = Atoms::StartContract.normalize(Atoms::StartContract.bootstrap(@config, scope: @scope || "lab"))
+          if @scope && plan["scope"] != @scope
+            raise Ace::Overseer::Error, "configured start scope '#{plan["scope"]}' conflicts with requested '#{@scope}'; nested lab scopes are refused"
+          end
           return lab_start(plan, dry_run) if plan["scope"] == "lab"
           root = @root_resolver.resolve(cwd: @cwd)
@@ -94,8 +97,10 @@ module Ace
           instructions_path = resolve_instructions(plan["instructions"], root)
           report = base_report(plan, root, label, instructions_path)
-          return report.merge("status" => "dry_run",
-            "message" => "dry-run: session would start with this plan; nothing was created") if dry_run
+          if dry_run
+            return report.merge("status" => "dry_run",
+              "message" => "dry-run: session would start with this plan; nothing was created")
+          end
           owner = owner_pane(label)
           if owner
@@ -144,6 +149,41 @@ module Ace
           blocked("herdr failed while preparing the overseer session: #{e.message}")
         end
+        # Bare start is just the foreground harness entrypoint. It does
+        # not discover a terminal, inspect agents or analyze topology.
+        def bootstrap(dry_run: false)
+          plan = Atoms::StartContract.normalize(@config)
+          unless plan["profile"]["harness"] == "pi"
+            raise Ace::Overseer::Error, "foreground start requires the configured pi harness"
+          end
+          root = File.realpath(@cwd)
+          source = plan["instructions"]
+          guide = if %w[wfi://overseer/lab-start wfi://overseer/start].include?(source)
+            filename = source.end_with?("lab-start") ? "lab-start.wf.md" : "start.wf.md"
+            File.join(Ace::Overseer.gem_root, "handbook/workflow-instructions/overseer", filename)
+          else
+            resolve_instructions(source, root)
+          end
+          raise Ace::Overseer::Error, "standing instructions file is missing: #{guide}" unless File.file?(guide)
+          command = ["pi", "--model", plan["profile"]["model"]]
+          thinking = plan["profile"]["thinking"]
+          command += ["--thinking", thinking] if thinking
+          command += ["--append-system-prompt", guide, FIRST_TURN_PROMPT]
+          {"status" => dry_run ? "dry_run" : "foreground", "scope" => plan["scope"],
+            "root" => root, "profile" => plan["profile_name"],
+            "instructions" => {"source" => source, "path" => guide},
+            "command" => command, "message" => "launch the coordinator in the current terminal"}
+        end
+        # Explicit tool available to the running Lab agent. This operation
+        # manages configured project children, never the coordinator itself.
+        def reconcile(dry_run: false)
+          plan = Atoms::StartContract.normalize(@config)
+          raise Ace::Overseer::Error, "project reconciliation requires lab scope" unless plan["scope"] == "lab"
+          lab_start(plan, dry_run, reconcile: true)
+        end
         private
         # --- lab scope (task 8xs.t.pu0.a) -----------------------------------
@@ -161,16 +201,16 @@ module Ace
         # healthy projects continue; a repeated start repairs only what
         # is missing and never restarts healthy sessions or closes
         # manual panes.
-        def lab_start(plan, dry_run)
+        def lab_start(plan, dry_run, reconcile: false)
           lab_root = File.realpath(@cwd)
           base = {"status" => nil, "scope" => "lab", "root" => lab_root,
-            "label" => Atoms::StartContract.session_label(lab_root),
-            "workspace" => nil, "pane" => nil, "agent" => AGENT_NAME,
-            "profile" => plan["profile_name"],
-            "instructions" => {"source" => plan["instructions"], "path" => nil},
-            "replaced_pane" => nil, "projects" => [], "project_count" => 0,
-            "ready" => nil, "message" => nil}
-          base["instructions"]["path"] = resolve_instructions(plan["instructions"], lab_root)
+                  "label" => Atoms::StartContract.session_label(lab_root),
+                  "workspace" => nil, "pane" => nil, "agent" => AGENT_NAME,
+                  "profile" => plan["profile_name"],
+                  "instructions" => {"source" => plan["instructions"], "path" => nil},
+                  "replaced_pane" => nil, "projects" => [], "project_count" => 0,
+                  "ready" => nil, "message" => nil}
+          base["instructions"]["path"] = resolve_instructions(plan["instructions"], lab_root) unless reconcile
           projects = begin
             Ace::Lab::Molecules::ProjectLocations.read(lab_root)
@@ -179,42 +219,56 @@ module Ace
               "message" => "lab topology could not be read: #{e.message}")
           end
-          if projects.any? { |project| project["path"].to_s.empty? == false &&
-            File.directory?(project["path"]) && File.realpath(project["path"]) == lab_root }
+          if projects.any? { |project|
+            project["path"].to_s.empty? == false &&
+                File.directory?(project["path"]) && File.realpath(project["path"]) == lab_root
+          }
             return base.merge("status" => "blocked",
               "message" => "the lab root '#{lab_root}' is itself declared as a project; " \
                 "conflicting lab/project roles are refused")
           end
-          return base.merge("status" => "dry_run", "project_count" => projects.size,
-            "projects" => projects.map { |project| {"id" => project["id"], "path" => project["path"],
-              "status" => "would_start"}},
-            "message" => "dry-run: the lab space with the lab overseer session and " \
-              "#{projects.size} project space(s)/overseer(s) would start; nothing was created") if dry_run
-          workspace = lab_workspace
-          base["workspace"] = workspace
+          if dry_run
+            return base.merge("status" => "dry_run", "project_count" => projects.size,
+              "projects" => projects.map { |project|
+                {"id" => project["id"], "path" => project["path"],
+                 "status" => "would_start"}
+              },
+              "message" => "dry-run: the lab space with the lab overseer session and " \
+                "#{projects.size} project space(s)/overseer(s) would start; nothing was created")
+          end
-          # The lab's OWN overseer session (the wfi://overseer/lab-start
-          # guide assumes it): booted or reused in the lab space before
-          # any project, so the lab-start instructions reach an agent.
-          session = boot_lab_session(workspace, plan, base["instructions"]["path"], lab_root)
-          return base.merge("status" => "blocked", "pane" => session["pane"],
-            "message" => session["message"]) if session["status"] == "blocked"
+          if reconcile
+            base["coordinator_managed"] = false
+            session = {}
+            lab_ready = true
+          else
+            workspace = lab_workspace
+            base["workspace"] = workspace
+            # The lab's OWN overseer session (the wfi://overseer/lab-start
+            # guide assumes it): booted or reused in the lab space before
+            # any project, so the lab-start instructions reach an agent.
+            session = boot_lab_session(workspace, plan, base["instructions"]["path"], lab_root)
+            if session["status"] == "blocked"
+              return base.merge("status" => "blocked", "pane" => session["pane"],
+                "message" => session["message"])
+            end
-          base["pane"] = session["pane"]
-          base["replaced_pane"] = session["replaced_pane"]
-          base["prompt_failed"] = !session["prompt_failed"].nil? && session["prompt_failed"]
+            base["pane"] = session["pane"]
+            base["replaced_pane"] = session["replaced_pane"]
+            base["prompt_failed"] = !session["prompt_failed"].nil? && session["prompt_failed"]
-          # Readiness REQUIRES a confirmed first turn (review R7): a
-          # started/reused session whose first-turn delivery failed or
-          # stays unconfirmed is NOT ready, whatever its process state.
-          lab_ready = !session["prompt_failed"]
+            # Readiness REQUIRES a confirmed first turn (review R7): a
+            # started/reused session whose first-turn delivery failed or
+            # stays unconfirmed is NOT ready, whatever its process state.
+            lab_ready = !session["prompt_failed"]
+          end
           # An empty configured list is a valid idle lab: the lab
           # overseer itself still runs (and must be initialized).
           if projects.empty?
-            message = "no projects configured; the lab overseer is idle"
+            message = reconcile ? "no project children configured" : "no projects configured; the lab overseer is idle"
             message += "; #{session["message"]}" if session["message"]
             return base.merge("status" => lab_ready ? "ready" : "partial",
               "ready" => lab_ready, "project_count" => 0, "message" => message)
@@ -264,12 +318,10 @@ module Ace
         # workspace reference), never treated as absent: creating a
         # second space with the same title would duplicate the space.
         def find_workspace(title)
-          existing = @executor.workspace_list.parsed_json
-          list = existing.is_a?(Hash) ? Array(existing["result"] || existing["workspaces"]) : Array(existing)
-          found = list.find { |entry| entry["title"] == title || entry["label"] == title }
+          found = @control_surface.list_workspaces.find { |entry| entry[:title] == title }
           return nil unless found
-          found["id"] || found["workspace_id"] || found["title"] || found["label"]
+          found[:id] || found[:title]
         rescue Ace::Herdr::ExecutorUnavailableError => e
           raise Ace::Overseer::Error, "herdr is unavailable: #{e.message}"
         end
@@ -287,17 +339,21 @@ module Ace
           if owner
             owner_cwd = owner["cwd"].to_s
             matching = !owner_cwd.empty? &&
-              (File.realpath(owner_cwd) == lab_root rescue false)
+              begin
+                File.realpath(owner_cwd) == lab_root
+              rescue
+                false
+              end
             unless matching
               return {"status" => "blocked", "pane" => nil, "replaced_pane" => nil,
-                "message" => "owner pane '#{owner["id"]}' works in '#{owner_cwd}', which is " \
+                      "message" => "owner pane '#{owner["id"]}' works in '#{owner_cwd}', which is " \
                   "not the lab root '#{lab_root}'; refusing to take over a foreign session"}
             end
             state = agent_state(owner["id"])
             if state
               warning = repair_reused_initialization(owner["id"], state)
               return {"status" => "reused", "pane" => owner["id"], "replaced_pane" => nil,
-                "prompt_failed" => !warning.nil?, "message" => warning}
+                      "prompt_failed" => !warning.nil?, "message" => warning}
             end
             replaced = owner["id"]
@@ -306,7 +362,7 @@ module Ace
           pane = boot_session(workspace, label, lab_root, plan, instructions_path)
           prompt_warning = first_prompt(pane)
           {"status" => "started", "pane" => pane, "replaced_pane" => replaced,
-            "prompt_failed" => !prompt_warning.nil?, "message" => prompt_warning}
+           "prompt_failed" => !prompt_warning.nil?, "message" => prompt_warning}
         rescue Ace::Overseer::Error => e
           {"status" => "blocked", "pane" => nil, "replaced_pane" => nil, "message" => e.message}
         end
@@ -320,29 +376,33 @@ module Ace
           path = project["path"]
           if path.nil? || path.to_s.strip.empty?
             return {"id" => id, "path" => nil, "status" => "blocked",
-              "message" => "project '#{id}' declares no path in the lab topology"}
+                    "message" => "project '#{id}' declares no path in the lab topology"}
           end
           unless File.directory?(path)
             return {"id" => id, "path" => path, "status" => "blocked",
-              "message" => "project '#{id}' directory '#{path}' does not exist"}
+                    "message" => "project '#{id}' directory '#{path}' does not exist"}
           end
-          project_config = Ace::Overseer.config_at(path)
-          # a project cascade that itself declares scope lab would
-          # recurse (a nested lab start) — refused, never executed
-          if project_config.is_a?(Hash) && project_config.dig("start", "scope") == "lab"
+          if id == LAB_SPACE_TITLE
             return {"id" => id, "path" => path, "status" => "blocked",
-              "message" => "project '#{id}' declares scope lab in its own " \
-                ".ace/overseer/config.yml; nested lab scopes are refused"}
+                    "message" => "project id '#{id}' is reserved for the lab workspace"}
+          end
+          root = @root_resolver.resolve(cwd: path)
+          label = Atoms::StartContract.session_label(root)
+          owner = owner_pane(label)
+          workspace = if owner && agent_state(owner["id"])
+            reference = owner["workspace"] || owner["workspace_id"]
+            if reference.to_s.strip.empty?
+              raise Ace::Overseer::Error,
+                "live project owner '#{owner["id"]}' reports no workspace; " \
+                "refusing ambient fallback or a separate project workspace"
+            end
+            reference
+          else
+            find_or_create_workspace(id)
           end
+          report = @project_runner.call(root: root, workspace: workspace, env: @env)
-          orchestrator = self.class.new(config: project_config, executor: @executor,
-            root_resolver: @root_resolver, nav_runner: @nav_runner,
-            workspace_factory: ->(label) { find_or_create_workspace(label) }, cwd: path)
-          report = orchestrator.call
-          # a reused session keeps its reported space: the lab-managed
-          # space titled by the project's session label, when it exists
-          report["workspace"] ||= find_workspace(report["label"])
           report.merge("id" => id, "path" => path)
         rescue Ace::Overseer::Error, Ace::Herdr::ExecutorError => e
           {"id" => id, "path" => path, "status" => "blocked", "message" => e.message}
@@ -383,7 +443,7 @@ module Ace
               "cannot resolve the ace-nav executable for the start instructions: #{e.message}"
           end
           result = @nav_runner.call([binary, "resolve", source], root)
-          path = result["status"] == "ok" ? result["out"].to_s.lines.first.to_s.strip : nil
+          path = (result["status"] == "ok") ? result["out"].to_s.lines.first.to_s.strip : nil
           if path.nil? || path.empty?
             raise Ace::Overseer::Error,
               "start instructions '#{source}' do not resolve through ace-nav " \
@@ -426,8 +486,32 @@ module Ace
         # The live pane owning this project's overseer label.
         def owner_pane(label)
-          panes = extract_panes(@executor.pane_list.parsed_json)
-          panes.find { |pane| pane["title"] == label || pane["label"] == label }
+          # boot_session names the TAB, not the terminal title. Pi and shell
+          # applications may change terminal titles at any time.
+          tabs = @control_surface.list_tabs.select { |entry| entry[:title] == label }
+          return nil if tabs.empty?
+          panes = @control_surface.list_panes
+          owners = tabs.map do |tab|
+            matches = panes.select { |pane| pane[:tab] == tab[:id] }
+            if tab[:id].to_s.empty? || matches.length != 1 || matches.first[:id].to_s.empty?
+              raise Ace::Overseer::Error,
+                "overseer tab '#{label}' has no unique owner pane; refusing an ambiguous session"
+            end
+            matches.first
+          end
+          if owners.length > 1
+            # A replaced dead owner may retain its tab. Only a single live
+            # agent identifies an unambiguous current owner; never pick the
+            # first of multiple live or dead candidates.
+            live = owners.select { |pane| !agent_state(pane[:id]).nil? }
+            unless live.length == 1
+              raise Ace::Overseer::Error,
+                "multiple overseer tabs '#{label}' have no unique live owner; refusing an ambiguous session"
+            end
+            owners = live
+          end
+          owners.first.transform_keys(&:to_s)
         rescue Ace::Herdr::ExecutorUnavailableError => e
           raise Ace::Overseer::Error, "herdr is unavailable: #{e.message}"
         end
@@ -492,6 +576,7 @@ module Ace
               "herdr created tab '#{label}' but reported no root pane"
           end
+          @executor.pane_run(pane, Molecules::ProjectBundle.shell_setup(root, env: @env))
           args = ["--model", plan["profile"]["model"]]
           if plan["profile"]["thinking"]
             args += ["--thinking", plan["profile"]["thinking"]]
@@ -544,14 +629,6 @@ module Ace
           end
         end
-        def extract_panes(json)
-          case json
-          when Array then json
-          when Hash then Array(json["result"] || json["panes"] || [])
-          else []
-          end
-        end
         def dig_pane(json)
           return nil unless json.is_a?(Hash)

data/lib/ace/overseer/version.rb CHANGED Viewed

@@ -2,6 +2,6 @@
 module Ace
   module Overseer
-    VERSION = "0.27.0"
+    VERSION = "0.28.0"
   end
 end

metadata CHANGED Viewed

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-30 00:00:00.000000000 Z
+date: 2026-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -139,14 +139,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: ace-hitl
   requirement: !ruby/object:Gem::Requirement
@@ -195,20 +195,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.8.1
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.8.1
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: ace-lab
   requirement: !ruby/object:Gem::Requirement
@@ -319,6 +313,7 @@ files:
 - exe/ace-overseer
 - handbook/skills/as-overseer/SKILL.md
 - handbook/workflow-instructions/overseer.wf.md
+- handbook/workflow-instructions/overseer/bootstrap-delegation.wf.md
 - handbook/workflow-instructions/overseer/cold-cycle-acceptance.wf.md
 - handbook/workflow-instructions/overseer/lab-start.wf.md
 - handbook/workflow-instructions/overseer/queue.wf.md
@@ -354,6 +349,7 @@ files:
 - lib/ace/overseer/molecules/hitl_inbox.rb
 - lib/ace/overseer/molecules/local_sources.rb
 - lib/ace/overseer/molecules/preservation_manifest.rb
+- lib/ace/overseer/molecules/project_bundle.rb
 - lib/ace/overseer/molecules/project_root_resolver.rb
 - lib/ace/overseer/molecules/prune_safety_checker.rb
 - lib/ace/overseer/molecules/remote_sources.rb