ace-overseer 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 105fc700308987490a9f933ca8ce93eb6ce73a1322bd1892df9d7c7aaf94dd9f
-  data.tar.gz: 14574baa5c684cc096927171dbdae1fc2a3070939ad3160c1ace410c2304eae6
+  metadata.gz: 5204d8b317b630a73e16ddc196fc90c3d6efa1e0f39a62406e1b6f7bd6de4c2e
+  data.tar.gz: 5293bfde27b37ca690442f2ffcc60446913ec54052b2426b47d82c55d48c1614
 SHA512:
-  metadata.gz: 66ee73e26f7a17d4d090d86e12b24e93292cefbddd44d11eb445297a2dab4e9f37a691b2aabc74e528d6715737046be4fd7296aa5a21cceaff97d8922807adbd
-  data.tar.gz: 88e2d7c66ec0d186a872c1deca9a47a2e0d0da984f122465029f627b46642def5a45363cf436b3f50111e85cf4ac53fb41d8174ef47cfcf8443e8dee1c15edfc
+  metadata.gz: 96747e1a1d70f884fb302110f0f12197b81a4b6a7701ce0ef0aeb000581daaae7bc6ccb7660f15fdf1ef067e6c879c0e3c86e774881b99ffdd351ec82204a740
+  data.tar.gz: 61e8da9b71790c8f7f5252e61652d4d7af4dd881d4bb8e716504c84ee60cfc1af3e784f0c5d8172d096e471d353d010e674984a9cee99d1a0b63e1e40d0c9eac

data/CHANGELOG.md

@@ -5,7 +5,124 @@ 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.27.0] - 2026-10-30
+
+### Fixed (review rounds 3/3b)
+
+- Start hardening: herdr failures surface as blocked reports on project and
+  lab paths; the first prompt is a separate step (a prompt failure never
+  strands a started agent); installed toolchain resolution never falls back
+  to the checkout; the lab space is `lab-overseer` (no basename collision);
+  nested lab scopes are refused; malformed observe.remote entries degrade
+  to per-source health markers.
+
+### Added
+
+- Remote PR observation (task 8xs.t.pu0.4): `observe.remote.pull_requests`
+  configuration projects configured PRs through the existing forge provider
+  adapters — lifecycle rows (new HEAD, merge/close/reopen) and activity rows
+  (review/approval/comment identity sets) with semantic revisions, wake
+  payloads (forge, number/title, event kind, author, link), and per-source
+  degradation on API failures with one wake per failure class.
+
+- `ace-overseer observe` projects the six local source classes (task
+  8xs.t.pu0.3): project and `_overseer` tasks, worktrees, coworker
+  availability and assignment progress alongside HITL events — every row
+  read from its state owner with stable key/revision semantics, per-source
+  health (`ok`/`degraded`), and degraded-source markers that wake once per
+  failure class while healthy sources keep projecting.
+
+- `ace-overseer start [--dry-run] [--format table|json]` (task 8xs.t.pu0.1):
+  starts or reuses the project overseer session from an explicit `start`
+  section (scope/profile/instructions) in the `.ace/overseer/config.yml`
+  cascade. Canonical project-root resolution (subdirectory, symlink, and
+  worktree share one owner), Herdr-backed session identity
+  (`overseer-<project>` label) with reuse/conflict/dead-replacement
+  semantics, guide resolution through the handbook chain, and the packaged
+  project-overseer start guide (`wfi://overseer/start`).
+
+### Fixed
+
+- Lab scope starts the lab's OWN overseer session (review 8xte508e): `lab_start`
+  previously created the `overseer-lab` space and only started project sessions,
+  so the lab-start guide reached no agent (`pane` stayed nil). The lab session
+  now boots or is reused in the lab space with the same identity rules as a
+  project session (label from the lab root, cwd at the lab root, live owner
+  reused, foreign owner refused, empty configured list still runs the lab
+  overseer).
+- The lab starts each project in its OWN herdr space (review 8xte508b /
+  readiness F2): the lab space hosts only the lab overseer session; each
+  configured project gets a space titled by its session label
+  (`overseer-<project>`), created/reused by title and passed into the nested
+  start through an explicit workspace factory seam. Project sessions are
+  isolated from each other and from the lab overseer, never re-resolve the
+  caller's ambient workspace (a plain terminal without a herdr pane works),
+  and a live session found in another workspace is reused and reports that
+  workspace without leaving an empty space behind.
+- Installed toolchain isolation for start instructions (readiness F4): the
+  `wfi://` guide resolution now selects the `ace-nav` executable through
+  `Ace::Support::Cli::Toolchain` — under `ACE_TOOLCHAIN=installed` the
+  installed gem launcher is always used, never the checkout's `bin/`
+  binstubs even when the project contains an executable ACE checkout; auto
+  mode is unchanged. An unavailable installed executable is a blocked
+  start, never a fallback to source.
+- Lab-level failures keep their lab context (review 8xte508k): a raise
+  during lab start (e.g. herdr unavailable while resolving the lab space)
+  previously collapsed into the generic project-style blocked report with
+  `scope: nil`; `lab_start` now maps it to `status: blocked` with the lab
+  `scope`/`root`/`label` intact and a "lab start failed: …" message. A
+  herdr workspace entry that carries the title but no id is treated as the
+  space itself (reused by title) instead of falling through to
+  `workspace_create`, which would duplicate the `overseer-lab` space.
+- `start` sends the first prompt after `herdr agent start` (review F3):
+  `agent start` success only means the interactive agent is ready for input, so
+  a session booted without a prompt sat idle (no state read, no `/eyes`
+  arming). `boot_session` now submits a first-turn prompt (the standing
+  instructions' "First turn after start" contract) right after the agent
+  starts; a reused session is never prompted again. The prompt is a separate
+  step from the boot (review 8xtiatf0): a delivery failure after a started
+  agent stays `started` with `prompt_failed: true` and a repairable warning —
+  a live idle agent is never reported as a failed start.
+- herdr failures surface as blocked starts, never raw exceptions (reviews
+  8xth38bw/8xtiatez): the project path's rescue now covers every
+  `Ace::Herdr::ExecutorError` (pane list, agent probe, session boot) with a
+  "herdr failed while preparing the overseer session: …" message, and the
+  lab-level rescue covers `CommandError` from workspace/pane calls with the
+  lab context intact ("lab start failed: …"). Dry-run probes no herdr state.
+- Readiness requires a CONFIRMED first turn, and a failed delivery is
+  repaired on restart (re-review R7): the first-turn prompt is submitted
+  through herdr's activity gate (`agent prompt --wait` — new `wait:`/
+  `timeout_ms:` options on `HerdrExecutor#agent_prompt`), so success proves
+  observed working activity rather than a mere submission. A lab is `ready`
+  only when every session (lab overseer included) has its first turn
+  confirmed; an unconfirmed delivery keeps `prompt_failed: true` with a
+  visible reason instead of a ready declaration. On a repeated start, a live
+  reused agent is distinguished from a completed start through the existing
+  herdr session state: working/blocked = mid-conversation (never
+  interrupted); idle/done = the first-turn prompt is re-delivered through
+  the existing session, repairing missing initialization without restarting
+  anything; an unclassifiable state stays visibly unconfirmed.
+- The lab space title is namespaced to `lab-overseer` (review 8xtiatf4): a
+  project rooted at a directory literally named `lab` owns the session/space
+  title `overseer-lab`; the old lab space title collided with it. Session
+  labels (`overseer-<root>`) are unchanged.
+- Workspace ids dig with exactly ace-herdr's canonical keys
+  (`workspace_id`/`workspaceId`, review 8xtiatf2) — no broader key guessing.
+- Auto-mode binstub use is again root-guarded (review 8xtiatf3): `start`
+  passes `prefer_project: !Process.uid.zero?` to the toolchain executable
+  resolver, so root never executes a project-owned `bin/` binstub (installed
+  mode ignores the flag).
+- A project cascade declaring `scope: lab` is refused per-project (review
+  8xthrjsm) — a nested lab start never recurses. The topology read rescue is
+  narrowed to `Ace::Lab::InvalidConfigurationError` (review 8xthrjsn) so
+  programming errors surface instead of becoming "topology could not be
+  read" blocks.
+
+## [0.26.1] - 2026-10-25
+
+### Changed
+
+- Add the semantic wake contract for pending delivery answers to the overseer workflow (PR74): scoped watch, end-of-turn wait, wake reconciliation.
 
 ## [0.26.0] - 2026-10-23
 

data/docs/usage.md

@@ -16,8 +16,9 @@ ace-docs:
 
 ## Command Surface
 
-Local work uses five primary commands (`projects` lists configured lab projects):
+Local work uses six primary commands (`projects` lists configured lab projects):
 
+- `ace-overseer start` - start or reuse the project overseer session from configuration.
 - `ace-overseer work-on` - prepare a worktree, assignment, and terminal.
 - `ace-overseer handoff` - hand the task worktree to the next role in the prepared sequence.
 - `ace-overseer process-reports` - interpret ace-hitl reports and continue the queue.
@@ -29,6 +30,189 @@ launcher are removed in L1 and are not normal paths. Status and prune read
 local assignment/task/worktree/Git state only; there is no journal, attempt or
 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:
+
+```yaml
+# .ace/overseer/config.yml (project tier of the cascade)
+start:
+  scope: project            # project | lab (lab: not implemented yet)
+  profile: overseer-default # reference into the profiles map below
+  instructions: wfi://overseer/start  # handbook source (or absolute file path)
+profiles:
+  overseer-default:
+    harness: pi
+    model: zai/glm-5.3-flash
+    thinking: high
+```
+
+| Option | Purpose |
+|--------|---------|
+| `--dry-run` | Show the start plan; no session, no sync, no model call |
+| `--format` | `table` (default) or `json` |
+
+Behavior:
+
+- The project root is canonical: a subdirectory, a symlinked checkout, and a
+  linked worktree of one repository resolve to the SAME owner, so one project
+  never runs two whole-project overseers.
+- Session identity is Herdr's: the tab/pane label `overseer-<project>` on the
+  caller's herdr workspace. A live owner pane is REUSED (`status: reused`); a
+  live pane whose cwd resolves elsewhere is a conflict (`status: blocked`,
+  never taken over); a dead owner pane is replaced and the new identity is
+  reported (`replaced_pane`).
+- The guide resolves through the normal handbook chain (`wfi://` sources via
+  the project's `ace-nav`; absolute paths verbatim) and boots the harness
+  agent as standing instructions with the configured profile. The `ace-nav`
+  binary follows the repo toolchain policy: auto mode prefers the project's
+  `bin/` binstub for a NON-ROOT caller and falls back to PATH, while
+  `ACE_TOOLCHAIN=installed`
+  always uses the installed gem launcher — a checkout inside the project is
+  data, never the runtime source. Because
+  `herdr agent start` success only means the interactive agent is ready for
+  input, the start submits a first-turn prompt right after the agent starts —
+  the session actually begins its first turn (state read, `/eyes` arming).
+  Delivery is confirmed through herdr's activity gate (`agent prompt
+  --wait`): success means observed working activity, so the turn began. A
+  delivery failure after a started agent never reports the start as failed:
+  the report stays `started` with `prompt_failed: true` and a repairable
+  warning. On a later start, a live reused agent ready for input gets the
+  first-turn prompt re-delivered through the same gate (repairing a missing
+  initialization without restarting anything); a working/blocked agent is
+  never interrupted, and an unclassifiable state stays visibly unconfirmed.
+- 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.
+- The started overseer coordinates and delegates (guide:
+  `wfi://overseer/start`); it never substitutes for a missing coworker.
+
+### 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:
+
+- The project list and CANONICAL locations come from the existing ace-lab
+  topology (`topology.projects` id/path, read internally — the public
+  projection keeps its no-paths allowlist; locations are never derived from
+  an id/label/repo name). The lab root is a coordination directory with its
+  own `_overseer`; a directory declaring itself as both lab and project is
+  refused, and a project whose own cascade declares `scope: lab` is refused
+  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
+  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
+  standalone start (its own cascade, root, and session identity) in its OWN
+  herdr space, titled by its session label (`overseer-<project>`) 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
+  a herdr pane works). The per-project report carries its space id; a live
+  session found in another workspace is reused and reports that workspace
+  without creating an empty space. herdr spaces are flat (no parent/child
+  nesting): the lab context owns the per-project spaces by creating and
+  reusing them from this one start flow.
+- Statuses: `ready` (all projects started/reused AND every first turn
+  confirmed delivered — the lab overseer's included; an empty configured
+  list is a valid idle lab once its own session is initialized), `partial`
+  (an unhealthy project — or a session whose first turn failed or stays
+  unconfirmed — is reported with its concrete reason while healthy projects
+  run — never false success), `blocked` (unreadable topology / conflicting
+  roles). A repeated start repairs only what is missing: healthy sessions
+  are reused, manual panes are never closed, nothing healthy is restarted,
+  and a reused session that is ready for input gets its first-turn prompt
+  re-delivered through herdr's activity gate (`agent prompt --wait`) to
+  confirm or repair initialization; a working/blocked agent is never
+  interrupted, and an unclassifiable one stays visibly unconfirmed.
+- `--dry-run` lists the plan (space + per-project would_start) and creates
+  nothing. The report carries per-project results (`projects`), the count,
+  and the lab-level readiness; exit 0 for ready, non-zero for partial and
+  blocked. The lab guide (`wfi://overseer/lab-start`) binds the lab
+  overseer to cross-project coordination, delegation to project overseers,
+  and per-project escalation.
+
+## `ace-overseer observe`
+
+Read-only standing observation the started overseer's eyes poll (task
+8xs.t.pu0.3). The projection merges the six local source classes, each read
+from its state owner — never a second task/assignment state:
+
+- HITL events (semantic revisions; reports/questions toward this owner),
+- project tasks and private `_overseer` tasks (`ace-task`),
+- worktrees (`ace-git-worktree`),
+- coworker availability and assignment progress (`ace-coworker` probe over the
+  `ace-assign` inventory; live/stale judged by existing run identifiers —
+  commissioned assignment ids — never pane names).
+
+Every row carries a stable `key` and a `revision` that changes only when the
+owner's data changes: identical state projects identical revisions (healthy
+silence consumes zero model turns), and a real change wakes the observer once.
+A failing source degrades ONLY itself — it contributes a `source-health` row
+whose revision is keyed by the failure class (an identical repeated failure
+never re-wakes; a new failure mode wakes once) while the healthy sources keep
+projecting. `sources` maps each source to `ok`/`degraded`. After a restart,
+pending revisions reconcile before new work is chosen, so a report that
+arrived during the overseer's absence is recognized exactly once.
+
+### Remote PR observation
+
+Configure the observed pull requests in the same cascade (task 8xs.t.pu0.4)
+— the project's own declarations, never a scan of every accessible account:
+
+```yaml
+# .ace/overseer/config.yml
+observe:
+  remote:
+    pull_requests:
+      - server: github-cs3b   # configured git server (ace-git ServerRegistry)
+        number: 398
+```
+
+Rows project through the EXISTING forge provider adapters (Forgejo and
+GitHub — `Ace::Git::Providers.for`; no separate HTTP client, no webhook
+service). Each configured PR contributes two rows: its lifecycle (`pr:` —
+new HEAD via `head_sha`, merge, close, reopen, title/draft) and its activity
+(`pr-activity:` — the sorted identity set of reviews and comments, so a new
+review, formal approval or comment revises once while re-ordered payloads and
+volatile counters never do). Row payloads carry the wake facts: forge, PR
+number/title, event kind, author and link. Technical polling of identical
+state projects identical revisions — zero model turns.
+
+A failing forge (401/403, rate limit, timeout, malformed payload) degrades
+only its source (`source-health` marker keyed by failure class: one wake per
+failure mode, never an empty healthy list); retry/backoff stays inside the
+provider adapters. After access returns, the changed state is recognized
+through its normal revision. Remote data stays data: re-read the current
+state and evidence before any merge decision. CI check changes are
+information, never a merge gate.
+
+### Cold-cycle acceptance (8xs.t.pu0.e)
+
+`wfi://overseer/cold-cycle-acceptance` binds the end-to-end acceptance of
+the whole family: explicit preconditions (a fresh runtime from the
+PUBLISHED set — a missing dependency is a readiness failure, never a
+binstub fallback), the run's non-interference contract (the operator only
+answers decisions/OTP), the ONE identity axis every acceptance record
+captures (task → assignments/roles + auth leases → HITL case/suggestion/
+decision/lesson → PR+HEAD → head-bound review/tests → publish versions+
+digests → installed runtime paths + target-account result → record PR), the
+mandatory negative flow (refuse one install step after publish: no done, no
+record, correct escalation; resume the same cycle without re-publishing),
+and re-run idempotence (a start after closure re-publishes, re-delegates
+and re-applies nothing).
+
 ## `ace-overseer work-on`
 
 Create or reuse local worktrees and prepare one assignment.

data/handbook/workflow-instructions/overseer/cold-cycle-acceptance.wf.md

@@ -0,0 +1,95 @@
+---
+name: overseer-cold-cycle-acceptance
+description: The repeatable cold-start full-cycle acceptance scenario — two projects, one delegated task, HITL with a Second Captain suggestion, independent review, merge, publish, install, record; negative install refusal and idempotent re-run
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Cold-Cycle Acceptance Scenario
+purpose: Bind the end-to-end acceptance of the autonomous lab family (8xs.t.pu0): explicit preconditions, one identity axis for every handoff, the operator's non-interference contract, a negative install flow, and re-run idempotence — executed on the installed, published set only.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Cold-Cycle Acceptance Scenario (8xs.t.pu0.e)
+
+## Goal
+
+Prove that every handoff composes into ONE autonomous cycle on the
+INSTALLED lab: a cold start with at least two configured projects, a task
+carried by real delegation through spec/planning, worker execution, an HITL
+question carrying a Second Captain suggestion, independent review, merge,
+publication, installation, runtime acceptance under the target account, and
+the integrated record. The operator presses START and answers ONLY the
+decisions/OTP the Captain must give — no further prompts, no pasted
+answers, no manual deploy.
+
+## Preconditions (explicit, NOT hidden autonomy)
+
+- A fresh runtime from the PUBLISHED set: every component (core, wake
+  extension projection, all three auth plugins) comes from installed gems —
+  a missing dependency/runner/projection is a readiness FAILURE, never
+  permission to fall back to the checkout's binstubs (`ACE_TOOLCHAIN=installed`).
+- `ace-lab install` converged the manifest (gem closure, exact versions,
+  extension projections); `ace-lab verify` passes under the target accounts.
+- At least two configured projects (one carries the task; the other proves
+  isolation); accounts, keys and auth profiles prepared by install.
+
+## Run
+
+1. `ace-overseer start` in the lab directory (scope lab). Expect: lab space,
+   both project overseers started/reused, per-project statuses.
+2. State the goal with acceptance criteria to the lab overseer (one explicit
+   message). From here the operator only answers HITL.
+3. The overseer accepts the goal, delegates spec/planning through the
+   EXISTING roles, records the task, and drives dependencies to acceptance —
+   delegation is proved by role/assignment evidence, not by the overseer
+   doing the work.
+4. Worker executes with a developer lease (`ace-lab auth request → use →
+   revoke`); reviewer with a reviewer lease (identity DISTINCT from the
+   author); integrator with an integrator lease and the formal approver
+   account from the configured lane.
+5. The required HITL decision carries a marked Second Captain suggestion in
+   the SAME case BEFORE the Captain answers; only the human answer releases
+   the gated step (the suggestion never does). An OTP ask is `--secret`: the
+   value never appears in any wake, log, or argv.
+6. Merge only through the gate: HEAD-bound tests, HEAD-bound independent
+   review verdict, HEAD-bound formal approval by a different account; the
+   adapter's expected-head condition refuses drift.
+7. Publisher releases from the published queue (resume by version+digest);
+   install converges the runtime; runtime acceptance runs UNDER THE TARGET
+   ACCOUNT with the actually installed paths/versions.
+8. The record (`wfi://release/cycle-record`) integrates through a reviewed
+   record-only PR; the task closes only after acceptance AND record.
+
+## The one identity axis (the acceptance record)
+
+Every handoff names the SAME verifiable chain — capture the real values, no
+fabricated suffixes: task id → assignments/roles (worker/reviewer/integrator
++ auth lease ids per role with principal/scope/use_until/expiry_mode) →
+HITL case id (suggestion id, decision revision, lesson) → PR + merged HEAD →
+review/tests evidence (heads, commands, results) → publish versions +
+digests → installed runtime paths/versions + target-account result → record
+PR. Producer → consumer at every step; command success alone proves
+nothing.
+
+## Negative flow (mandatory)
+
+After a successful publish, REFUSE one required install step (e.g. remove
+one manifest dependency or the extension projection). Expect: no done, no
+ready, no record; the blocked state names the concrete missing dependency
+and the correct escalation addressee; healthy parts keep reporting. After
+restoring the cause, resume THE SAME cycle without re-publishing (matching
+version+digest = already published).
+
+## Re-run idempotence
+
+After the cycle closes, run `ace-overseer start` again: no re-delegation, no
+re-publication, no re-application of a closed decision; previously
+started/reused sessions stay; the answer-only replay of an applied decision
+is refused by the lifecycle.
+
+## Boundaries
+
+- Tests and scenarios live with their existing owners (ace-lab,
+  ace-overseer); no separate test service.
+- The scenario is repeatable: a second cold run produces the same evidence
+  shape with fresh identifiers.

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

@@ -0,0 +1,50 @@
+---
+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
+doc-type: workflow
+title: Lab Overseer Start Guide
+purpose: Define the lab overseer's coordination role across projects — readiness aggregation, cross-project escalation, delegation to project overseers — without taking over any project's tasks or private state.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Lab Overseer Start Guide
+
+## Goal
+
+You are the LAB overseer started by `ace-overseer start` with `scope: lab`
+in the lab coordination directory. Your role is coordination ACROSS
+projects: ensuring each configured project has a healthy overseer session,
+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.
+
+## 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.
+
+## 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.
+- Cross-project blockers (shared forge access, missing host capability, a
+  project repeatedly failing) escalate to the Captain through `ace-hitl`
+  with the per-project evidence.
+- One project's failure never blocks the healthy ones: keep their work
+  flowing and report the failure separately.
+
+## Boundaries
+
+- The lab root is a coordination directory with its own `_overseer`; project
+  locations come from the lab topology (`ace-lab`), never from names.
+- Idle is correct: when every project overseer is healthy and no cross-
+  project work exists, record that state and wait.
+- Capabilities not yet delivered are reported as gaps, not simulated.

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

@@ -0,0 +1,79 @@
+---
+name: overseer-start
+description: Standing instructions for a started project overseer session (coordination, delegation, escalation, idle) loaded by ace-overseer start
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Project Overseer Start Guide
+purpose: Define the started project overseer's role boundaries, observation and delegation loop, HITL escalation, and completion semantics; the overseer coordinates and never substitutes for a missing coworker.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Project Overseer Start Guide
+
+## Goal
+
+You are the project overseer started by `ace-overseer start` with this guide as
+your standing instructions. Your role is COORDINATION: reading real state,
+choosing the next action, delegating execution to coworkers, and escalating to
+the Captain through HITL. You do not implement, review, or publish in place of
+a missing coworker — you report the gap and escalate.
+
+## First turn after start
+
+1. Read your private task list: `ace-task --in _overseer list` (your
+   coordination tasks live there; you own them).
+2. Read project truth from the state owners — never a second cache:
+   `ace-task list`, `ace-overseer status`, `ace-git-worktree list`,
+   `git status --short`, and pending escalations with `ace-hitl list`.
+3. Continue EXISTING commissioned work before choosing anything new.
+4. When the lists are empty and no report awaits processing: record that state
+   and remain idle. Silence is a correct state; do not invent work.
+
+## Delegation
+
+- Prepare work through the owners: task (`ace-task`), worktree
+  (`ace-git-worktree`), assignment (`ace-assign`), and the coworker roles
+  (`ace-coworker prepare`). Never hand-edit another owner's files.
+- Delegate to the coworker roles with scope, context, completion criteria, and
+  the access the task grants. A missing coworker or missing permission is
+  REPORTED (and escalated when blocking) — never filled by doing the work
+  yourself.
+- Merge gate: executed tests plus an independent reviewer verdict. CI is
+  advisory.
+
+## Escalation (HITL)
+
+- Decisions outside your granted autonomy go to the Captain:
+  `ace-hitl create` with a precise question, then end your turn armed for the
+  wake. Blocking wait is an emergency path only.
+- Answers return through the same case; apply them once and close the case.
+
+## Standing observation
+
+After start, arm `/eyes` with the project's eyes configuration (interval 15s is
+the default reconcile cadence). `ace-overseer observe` — what eyes polls —
+projects the six local source classes from their owners: project tasks,
+private `_overseer` tasks, worktrees, coworker availability (existing run
+identifiers, never pane names), assignment progress and HITL events. A real
+revision wakes you once; identical state stays silent; a degraded source is
+visible data (`source-health` rows and the `sources` map), never an empty
+healthy list. After a restart, reconcile pending revisions first — a report
+that arrived in your absence surfaces as an unacknowledged revision — then
+choose work by the existing plan/dependency order (`ace-overseer
+process-reports`, `ace-overseer work-on`). Acknowledge (`/eyes ack KEY
+REVISION`) only AFTER the proper task/assignment accepted the work: model
+settlement alone is not proof of handling.
+
+## Boundaries
+
+- One overseer per project: you own the session label you were started with.
+  Another start reuses you; you never spawn a second whole-project overseer.
+- Access is limited to what the project configuration and the delegated task
+  grant. Credentials and OTP values never enter prompts, reports, or files.
+- Remote PR observation (observe.remote.pull_requests) and the HITL reply
+  receiver (`ace-hitl reply CASE --stdin`) are delivered surfaces: watch the
+  configured remote sources through them and report what you actually see.
+  Capabilities genuinely not yet delivered (e.g. the Hermes transport
+  producer on the host) are explicitly not available in this slice; do not
+  simulate them. Missing capability is a reported gap, not a workaround.

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

@@ -6,8 +6,8 @@ doc-type: workflow
 title: Overseer Workflow
 purpose: Binding process contract for the overseer lifecycle (work-on, status, prune) with executed-check contracts for prune safety and status truth.
 ace-docs:
-  last-updated: '2026-09-29'
-  last-checked: '2026-09-29'
+  last-updated: '2026-10-23'
+  last-checked: '2026-10-23'
 ---
 # Overseer Workflow
 
@@ -145,6 +145,20 @@ candidate:
    operator; never silently drop it and never bypass a failed proof with
    `--force`. Preserve on ambiguity.
 
+### 4) Wait: pending answers use the semantic wake, never polling
+
+While an answer is pending (for example a RubyGems OTP window of ~30-45 s
+during publication), the supervising session registers exactly ONE
+in-process `/watch` scoped to the project ace-hitl transport folder (the
+folder holding that case's reply/request files, e.g. `.ace-local/hitl`),
+then ends its turn. On wake: run the project `ace-hitl-hermes sync` ONCE,
+reconcile the exact case state (`ace-hitl show <id>`: answered, not merely
+replies>0), and act within the answer window or report the precise blocker.
+Never block a model turn with sleep/poll loops, and never introduce
+cron/systemd/external heartbeats - none exists and none may be added.
+Observed defect (eyes-20261023 OTP wait): the supervising session blocked
+its turn with a 36x sleep-8 poll loop.
+
 ## Non-Negotiable Contracts Summary
 
 | Contract     | Claim | Executed proof |