ace-overseer 0.27.0 → 0.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5204d8b317b630a73e16ddc196fc90c3d6efa1e0f39a62406e1b6f7bd6de4c2e
-  data.tar.gz: 5293bfde27b37ca690442f2ffcc60446913ec54052b2426b47d82c55d48c1614
+  metadata.gz: 4d96c79ae10f470e6358022f081234f5080eba56cd58353471a33aa6f187e0c5
+  data.tar.gz: 5e4eadc41222d3448b57f938ad5c2716b1941ddfe7b800479d69a6a3f72f3cb9
 SHA512:
-  metadata.gz: 96747e1a1d70f884fb302110f0f12197b81a4b6a7701ce0ef0aeb000581daaae7bc6ccb7660f15fdf1ef067e6c879c0e3c86e774881b99ffdd351ec82204a740
-  data.tar.gz: 61e8da9b71790c8f7f5252e61652d4d7af4dd881d4bb8e716504c84ee60cfc1af3e784f0c5d8172d096e471d353d010e674984a9cee99d1a0b63e1e40d0c9eac
+  metadata.gz: f9fdda6024283fd16b8be35da318b7e4eb6a85574ef623cc1395c4c7af0d77fc1971a541bb2a28abe3a6ce7a6d52f1c04df442c69eaff53e09f7d3974b6b89e3
+  data.tar.gz: 4fe70abfe425a0c399763c790125f391bbca8099f5a96e4a24677047148fc4b7e1c578ae976853195a28f1e5306500e259de498a491601e241e1c82e1b514c91

data/CHANGELOG.md

@@ -5,6 +5,53 @@ 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.1] - 2026-10-31
+
+### Fixed
+
+- Transfer terminal runtime setup through a private script and require its
+  acknowledgement before launch, preventing canonical-input PATH truncation.
+
+- Bind unassigned readiness only to explicit planner allocations; reject missing
+  report identities and conflicting task/role references. Persist bootstrap
+  assignment and receipt identities in task metadata, using resolved task paths.
+  Check real completed assignment and role ownership before accepting success;
+  leave confirm-start continuation to the coordinator without worker dispatch.
+
+- Preserve concrete child startup failures reported before project scope is
+  established, while continuing to reject unscoped or wrong-scope success.
+
+- Delegate bootstrap diagnosis and reproduction to workers as well as repair;
+  a known symptom is enough to commission work. Reconcile project startup only
+  after accepted worker completion and independent verification.
+
+## [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

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

@@ -0,0 +1,119 @@
+---
+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
+
+The overseer reads owner state and public CLI contracts to establish scope,
+existing execution and the observed symptom. Technical diagnosis, source-code
+investigation, troubleshooting and reproduction commands belong to the worker.
+Record the known failure and desired outcome in the commission; discovering
+the root cause is part of the assigned work, never a prerequisite for dispatch.
+Use existing readiness state, or a startup dry run only when that state is
+otherwise unknown. Do not turn that check into a technical investigation.
+Once the symptom is known, proceed to task creation/reconciliation, observation
+and worker dispatch, then end the turn.
+
+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, observed failure, desired outcome, allowed changes, runtime
+mode, acceptance checks and report recipient. Assign diagnosis and reproduction
+as well as preparation to the worker. This is lab infrastructure work, not a project product task.
+Workers must not edit the private coordination tree. Resolve each task folder
+from `ace-task show <ref>` before writing commission, dispatch or receipt notes;
+never construct a folder from a guessed or expanded title slug.
+
+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 through the task API, not only in prose:
+
+```bash
+ace-task update <prepare-step> --set assignment=<worker-assignment> --set role=bootstrap-worker --set worktree=<returned-worktree>
+ace-task update <verify-step> --set assignment=<verifier-assignment> --set role=bootstrap-verifier --set worktree=<returned-worktree>
+ace-task update <confirm-step> --set role=confirm-start
+```
+
+Read back the steps with `ace-task show` and verify exact returned identities.
+A preparation readiness report is not worker completion. It does not complete
+any of these three steps; never label bootstrap execution as `role=planner`.
+Only a separate, explicitly commissioned planner preparation allocation may
+accept an unassigned readiness report.
+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 the actual accepted HITL event ID and result in step metadata through
+`ace-task update <step> --set processed_report=<event-id> --set report_result=<result>`
+(or let `process-reports` perform that same write after its dry run is checked).
+Mark done only after acceptance; errors keep the step open. Receipt notes in
+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.
+
+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.
+
+Only after accepted worker completion and independent verification does the
+overseer perform this commission's project-start 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

@@ -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,61 @@ 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, binstub generation and technical
+diagnosis are WORKER work. Read owner state and public CLI contracts to route
+the commission; source-code investigation, troubleshooting and reproduction
+commands belong to the worker. Capture the observed symptom and desired
+outcome. An unknown root cause is not a reason to postpone task creation and
+dispatch. Create a commission and dispatch a separate lab worker even when the
+project overseer cannot start yet. Do not edit project configuration, install
+packages or run repair commands yourself. Missing workers are a concrete
+capability gap, not a reason to become the worker.
+
 ## 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, commission any missing configuration and project
+preparation through workers 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. For a preparation commission, read existing readiness/session state; use
+   a startup dry run only if needed to establish an otherwise unknown status.
+   Do not investigate its implementation or reproduce the failure yourself.
+   Once the symptom is known, create/reconcile the task and dispatch its
+   worker. Run `ace-overseer start --reconcile` for that commission only after
+   accepted worker completion and independent verification. Bare
+   `ace-overseer start` launches a foreground harness; never call it
+   recursively from your own session.
+5. After dispatch, record the real assignment and agent identity and END YOUR
+   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/handbook/workflow-instructions/overseer/queue.wf.md

@@ -80,6 +80,7 @@ task:
 ```bash
 ace-task create "Manage: <scope>" --in _overseer --tags queue
 ace-task create "Prepare <scope>" --child-of <manager-ref>
+ace-task update <prep-ref> --set role=planner
 ace-task create "Implement <scope>" --child-of <manager-ref>
 ace-task create "Review <scope>" --child-of <manager-ref>
 ace-task create "Integrate <scope>" --child-of <manager-ref>
@@ -94,7 +95,11 @@ Rules:
 - Add worktree/assignment references only after they really exist (the
   planner prepares them); never fabricate references ahead of preparation.
   Record them on the step that owns them, e.g.
-  `ace-task update <step-ref> --set worktree=.ace-wt/<task>/`.
+  `ace-task update <step-ref> --set assignment=<actual-id> --set role=<allocated-role> --set worktree=<actual-path>`.
+  Read back the fields; notes alone do not bind reports. `role=planner` denotes
+  only the allocation that prepares assignments, never bootstrap-worker or
+  confirmation of a running project. Resolve note folders from `ace-task show`;
+  never guess their title-derived paths.
 
 - Cross-task ordering goes through the integration step: a step of task B
   that requires A's merge depends on A's *integrate* subtask, not on A's
@@ -162,8 +167,9 @@ When a report arrives (ace-hitl event or message):
 1. Match its message ID plus task/assignment/step references to the current
    order. A report that fits no open allocation is kept for clarification,
    not counted as success.
-2. Record the outcome and the processed report ID in the managing task /
-   step (task-folder notes), then update statuses:
+2. Persist the exact accepted event ID and result on the owning step:
+   `ace-task update <step-ref> --set processed_report=<event-id> --set report_result=<result>`.
+   Add evidence notes in the folder returned by `ace-task show`, then update statuses:
    `ace-task update <step-ref> --set status=done` (or keep open / escalate).
 3. For success: end the current allocation, then continue with the next
    unblocked step per rule 3. For a repeated report: check the recorded
@@ -174,14 +180,23 @@ When a report arrives (ace-hitl event or message):
 
 `ace-overseer process-reports` executes rules 1-3 mechanically: it matches
 each incoming event (assignment recorded on a step, or the managing task's
-project_task with exactly one non-terminal step), records the outcome and
+project_task with exactly one explicitly allocated `role=planner` non-terminal
+step having no assignment). Task and any supplied role must agree; an event
+without an ID is refused. Unassigned readiness never closes worker, verifier,
+integration or confirm-start allocations. Before recording assigned success, the processor reads the actual coworker role
+allocation and ace-assign state: exact task/assignment/role, a completed nonempty
+plan, and every step done are required in dry-run and apply. Unavailable owner
+state refuses acceptance. It records the outcome and
 the processed report ID on the step through the ordinary ace-task update
 surface, and continues with the next unblocked step through the existing
 gates — `ace-overseer handoff` for the next role when the family records a
 worktree, otherwise the `work-on` dependency gate. A repeated delivery is
 answered from the recorded `processed_report` and re-runs nothing; an error
 report or question never advances a step; a report matching no open
-allocation stays for clarification. `--dry-run` interprets without effects.
+allocation stays for clarification. A `role=confirm-start` continuation remains
+a coordinator operation; no generic worker is dispatched and no managing task
+closes until first-turn and observation evidence is accepted. `--dry-run`
+interprets without effects.
 
 ### 6) Close
 

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

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

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

@@ -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}'")