ace-handbook-integration-pi 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c5ab037a9338b9466fc32aaed92e0418c5ef05e436ca790a6ef6c6706b88ffb
-  data.tar.gz: 1181cb6b7863f29e907af9e3cd9a008b10265225dd00537d55aa6127cfe80a05
+  metadata.gz: 4e1e1f851408ab94551b1f23f43b258fdd064b8df2790f0bb2a80ab05363983a
+  data.tar.gz: 7fa298d85b1ce4844320dc980d323b28079c2a05a37dd26ea3dc46d159a41f47
 SHA512:
-  metadata.gz: 85683a4338df4a155fbc01bee9d8324b5be22cc9a5a0eaad3501d2359a5497d38545b7f45eae03b3eaf180095236bbaed7c8b5081130ed7300a89e72522e1c77
-  data.tar.gz: da305a0888d369118bc6c6c1e2ac965bc0468f807138a4f3a0a60e1c95f146f841fd083c125137d7a55718d1a3c91993ee2ca0c4751a05b2af9ae5531cb98fc7
+  metadata.gz: 75c4ed2da5fce4f238a8e8d7b401ee4ac524548f15fb3e5f574a9bd5f526f7b73eecbefc80241e814e6ac71d055253e619dffb2c87443b8c949f94b34ce304d1
+  data.tar.gz: 53bff4c326bad616aff1ddfcf417d16496cd3177f38c6cb35c95d40b2bd5fdcbe6b923883e55241af306c5f03671b96d1538dd2c244417af5928b96fd769560c

data/CHANGELOG.md

@@ -4,100 +4,28 @@ All notable changes to ace-handbook-integration-pi will be documented in this fi
 
 ## [Unreleased]
 
-## [0.5.0] - 2026-09-28
 
-### Added
-- Shipped the **ace-wake** Pi extension (`handbook/extensions/ace-wake/index.js`, projected to `.pi/extensions/`): session-scoped `/loop` timers and `/watch` file subscriptions that wake the live agent through queued `sendUserMessage` messages only. Wakes are bounded, source-prefixed, coalesce per source while one is queued, and reach busy agents as queued follow-ups that never interrupt an in-flight tool operation. Concurrent sources deliver into an active run immediately (serialization guards only the idle-to-running transition). Delivery ambiguities from Pi's void `sendUserMessage` resolve toward redelivery over loss: unconfirmed attempts re-fire on a bounded recovery window, and watch changes refused while no model is selected retry on that window without needing another filesystem event. Definitions persist as session entries and reconcile exactly once per session start, reload, or branch switch with no missed-tick replay. No cron, systemd, or external heartbeat dependency.
-- Provider manifest now declares `extensions_dir: .pi/extensions`; `ace-handbook sync` projects extension assets and prunes stale projected files via a projection receipt without touching user-authored extensions.
-- Command flags accept quoted values both after the flag (`--message "check the build"`) and inline (`--message="check the build"`); an unterminated quote fails the command instead of storing a truncated value, while prose apostrophes mid-token stay literal.
-
-### Changed
-- Renamed the backlog-running prompt from `/loop` to `/work-backlog` (template `handbook/prompts/work-backlog.md`) so the timer command owns the `/loop` name. Behavior unchanged; no alias is provided.
-- Package verification now includes the JavaScript wake suite (run on the installed Node runtime) and an installed-extension acceptance scenario inside the real Pi SDK runtime (`test/feat/`).
-
-## [0.4.0] - 2026-09-27
-
-### Added
-- Provider manifest now declares `prompts_dir: .pi/prompts`; canonical pi prompt templates from `handbook/prompts/` project there via `ace-handbook sync`.
-- Shipped the canonical `loop` prompt template: the ACE overseer loop running in-process inside a pi session (`/loop`), cycling the task backlog through the `as-task-work` discipline with executed-evidence stop conditions. Projected to `.pi/prompts/loop.md`.
-
-
-## [0.3.11] - 2026-09-02
-
-### Technical
-- Included in the coordinated all-package patch release preparation for ACE monorepo review.
-## [0.3.10] - 2026-08-12
-
-### Technical
-- Raised the `ace-handbook` dependency floor to `~> 0.31` after the generic release workflow baselines release.
-
-## [0.3.9] - 2026-08-12
-
-### Technical
-- Aligned gemspec dependency floors with current ACE package minor release lines and safe external minor dependency bumps (no major version jumps).
-
-## [0.3.8] - 2026-04-22
-
-### Technical
-- **ace-handbook-integration-pi v0.3.8**: Bumped patch release to keep dependency constraints aligned with `ace-handbook v0.28.0`.
-
-## [0.3.7] - 2026-04-13
-
-### Changed
-- **ace-handbook-integration-pi v0.3.7**: Published handbook and HITL migration release changes for PI handbook integration.
-
-
-## [0.3.6] - 2026-04-11
-
-### Technical
-- Migrated deterministic coverage to `test/fast/` and documented `ace-handbook-integration-pi` as a fast-only package (no `test/feat/` or `test/e2e/` layer).
-
-## [0.3.5] - 2026-03-29
-
-### Technical
-- Updated the `ace-handbook` runtime dependency range from `~> 0.21` to `~> 0.22` to follow the new handbook minor release.
-
-## [0.3.4] - 2026-03-29
-
-### Technical
-- Normalized published gem metadata so RubyGems and Ruby Toolbox use current release information instead of the 1980 fallback date.
-
-
-## [0.3.3] - 2026-03-29
+## [0.6.0] - 2026-10-20
 
 ### Fixed
-- **ace-handbook-integration-pi v0.3.3**: Bumped dependency constraints to currently available `~>` ranges on RubyGems and updated release metadata after dependency synchronization.
-
-## [0.3.2] - 2026-03-22
-
-### Technical
-- Standardized PI provider casing in README terminology (`PI-specific`, `PI-native`) to match package naming and changelog language.
-
-## [0.3.1] - 2026-03-22
-
-### Technical
-- Refreshed the package README with standardized handbook integration sections, PI-specific provider wording, and ACE/`ace-handbook` linkage.
-
-## [0.3.0] - 2026-03-12
-
-### Changed
-- Replaced the legacy `ace-handbook-integration-agent` dependency with a direct `ace-handbook` runtime dependency.
-- Updated the package entrypoint and docs to treat PI integration as a thin provider plugin on top of `ace-handbook`.
-
-## [0.2.0] - 2026-03-10
+- `ace-wake` target drop could silently lose a deferred report wake: when a discovered extra target's watcher errored (e.g. `ace-overseer prune`), `dropTarget` in `wake/watch-subscription.js` recomputed the aggregate baseline from CURRENT stats for every remaining path — absorbing an undelivered change (a deferred wake left the fingerprint at its pre-report state, `dirty=true`) into the baseline, so the next settlement boundary saw `next === fingerprint`, cleared dirty, and never woke. The baseline is now adjusted by removing ONLY the dropped target's segment from the recorded fingerprint strings (both `fingerprint` and `previousFingerprint`), keeping every remaining target at its recorded state so the pending change still delivers. Because this shape never touches the filesystem, it also removes the unguarded primary stat that previously ran inside the native `onError` callback: a primary deleted moments before the extra target's error could throw uncaught into the extension host (the primary's own watcher error still deactivates through the documented path). Covered by two new fake-layer scenarios in `test/js/watch-subscription.test.mjs`: a pending undelivered primary wake survives an extra target dropped at settlement, and `dropTarget` no longer throws when the primary was just deleted.
+- `ace-wake` runtime discovery refresh (`wake/watch-subscription.js`): worktree discovery re-ran only inside `handleChange` — the one-shot ~500 ms post-registration reconcile plus events on already-watched paths. A worktree linked long after start whose FIRST report landed in its own (then-unwatched) inbox triggered no refresh pass at all, so the wake was missed until another watched path changed or a re-registration. Settlement boundaries now refresh discovery for EVERY active subscription: `flushDirty()` runs the full refresh pass (target discovery + ancestor→direct re-attachment) for all entries, not only dirty ones, and delivers any fingerprint change as a wake. Covered by a fake-layer scenario (late-linked worktree, report in its own inbox, no watched-path event, wake at the settlement boundary); the real-git late-worktree scenario in `test/js/report-wake-worktree.test.mjs` now expresses production ordering — it waits out the one-shot reconcile before linking the worktree and proves the settlement boundary is the channel that wakes.
+- `ace-wake` discovery micro-race: a report created between the discovery stat proving a target absent and the baseline fingerprint recomputation was absorbed into the baseline (the `absent` state was never recorded), so the first report into that inbox never woke. The baseline now records the PROVEN "absent" state (derived from the ancestor climb, never a re-stat) at registration and at every discovery refresh, and attaching a newly discovered target schedules a follow-up reconcile pass mirroring `start()` — a race-window report stays a pending change and is delivered by that pass. A fake-layer test injects the report exactly inside the stat-throw/recompute window and asserts the wake.
+- `ace-wake` watcher runtime errors on a discovered extra target no longer kill the whole subscription: with runtime discovery, `ace-overseer prune` removing a watched worktree used to deactivate the watch for ALL worktrees (never retried). A runtime error on the primary target keeps the documented deactivate posture; an error on a discovered extra target drops only that target's watcher (the disappearance is absorbed into the baseline — a pruned worktree is not a report) while the subscription stays active, and discovery re-attaches the target if it reappears. A fake-layer test asserts watcher teardown without deactivation and that the primary keeps waking.
+- `ace-wake` report watches now discover worktrees linked AFTER the watch started: inbox expansion (`expandInboxWatchTargets` over `git worktree list`) re-runs on every change/reconcile refresh pass instead of only at registration, so a report filed in a task worktree created while the overseer session is already watching still wakes it — no re-registration, reload, or new queue/cache. A newly discovered target that is still absent joins the baseline fingerprint as its stable "absent" state, so only the first report into it wakes.
 
 ### Added
-- Added a shipped PI provider manifest and packaging support so `ace-handbook sync` can project canonical skills into `.pi/skills`.
+- L7.3 commissioned-work continuation (task 8xg.t.sbz.6.2): new `/continue-work` resume prompt (`handbook/prompts/continue-work.md`) for a pi overseer session. After a report wake or session restart it reads `_overseer` tasks, `ace-assign` assignments, and current project truth, then continues the SAME commissioned process through the existing `ace-overseer` gates (`process-reports`, `work-on`, `handoff`) with single-execution, delivery-repetition-≠-work-repetition, and no-self-seeking rules. Report wake wiring is documented: a `/watch` on `.ace-local/hitl` wakes a waiting session, active turns receive queued follow-ups, and restarts re-register the watch exactly once.
+- JavaScript acceptance suite for the report wake path (`test/js/report-wake.test.mjs`): wake-on-report for an idle session, queued follow-up (never a second execution) during an active turn with coalesced repeats, exactly-once re-registration after restart without replay, and idempotence of an identical repeated notification. Shared session harness extracted to `test/js/session-harness.mjs`; a real-filesystem test proves a file created inside a watched directory (the `.ace-local/hitl` inbox wiring) wakes exactly once.
 
 ### Changed
-- Simplified the PI integration entrypoint to a thin provider package that relies on `ace-handbook` for sync and status execution.
-
-## [0.1.1] - 2026-03-10
+- `ace-wake` `/watch` now handles directory targets explicitly: the directory itself is watched and any child event is accepted (the mtime/size fingerprint filters noise), so a report file created in `.ace-local/hitl` wakes the session on every platform — Linux inotify delivers child-create events only to a watch on the directory itself, which the previous parent-watch design could never observe. File targets keep the parent-watch + basename-filter behavior that survives atomic replacement.
+- Removed the superseded `/work-backlog` prompt template: its self-seeking backlog cycling (pick any pending project task) contradicts the approved file-based lab contract; `/continue-work` replaces it with no alias.
 
-### Added
-- Added the PI-specific handbook integration package scaffold on top of the shared agent integration base.
-
-## [0.1.0] - 2026-03-10
+### Fixed
+- `ace-wake` watcher re-attachment (`refreshAttachments` in `wake/watch-subscription.js`) could crash the extension host: `watchFactory` may throw synchronously (EMFILE, EPERM, stat race) and re-attachment is reached from native watcher callbacks and the reconcile timer with no guard. The replacement watcher is now attached BEFORE the old ancestor watcher is closed — on an empty result the old watch survives — and a synchronous throw is caught and deactivates the definition (`re-attachment failed: …`, all watchers closed) per the documented runtime-error posture (visible error via `onDeactivate`, never retried) instead of escaping into the host. Covered by a new fake scenario in `test/js/report-wake.test.mjs` (synchronous `watchFactory` throw during re-attachment deactivates the watch, delivers no wake, and leaves no watchers).
+- Cross-worktree report wake (PR393 P2): `ace-hitl create` writes a coworker's report inside THAT coworker's worktree (its own `.ace-local/hitl`), so the documented watch on the main checkout's inbox never fired — reproduced with a real linked worktree, a real `ace-hitl create` and the real watcher (zero wakes). A `/watch` on `.ace-local/hitl` now expands to the inbox of every linked worktree using the same `git worktree list --porcelain` discovery the HITL list uses (new `wake/inbox-discovery.js`, the default `resolveTargets` port of `createWatchPort`, overridable for tests); no second inbox, queue, or cache. The watch fingerprint aggregates all targets — a worktree inbox that does not exist yet is a stable "absent" state watched through its nearest existing ancestor, so the first report into a freshly created inbox still wakes; expansion re-runs at every re-registration (session start/reload/branch switch). `test/js/report-wake.test.mjs` gains cross-worktree scenarios (including a not-yet-existing inbox and exactly-once re-registration across targets) and a new real-git + real-`bin/ace-hitl` scenario in `test/js/report-wake-worktree.test.mjs` fails with the old single-target watch.
+- `ace-wake` watcher re-attachment for formerly-absent inbox targets: when a worktree's `.ace-local/hitl` did not exist at registration, the watcher attached to the nearest existing ancestor — but Linux inotify is non-recursive, so a SECOND report created inside the now-existing inbox fired no event until the next re-registration. Every change/reconcile pass now re-checks targets watched through an ancestor and, once the target exists, closes the ancestor watch and watches the real target directly (`refreshAttachments` in `wake/watch-subscription.js`). Proven by a new fake scenario in `test/js/report-wake.test.mjs` (second report wakes; the ancestor watch is closed and the inbox watched directly) and a second real-`ace-hitl create` step in `test/js/report-wake-worktree.test.mjs`.
+- `expandInboxWatchTargets` now realpath-normalizes its results (worktree roots before joining the inbox suffix, since the inbox itself may not exist yet): symlinked roots (`/tmp` → `/private/tmp`) previously survived as distinct strings, defeating the target dedup in `createWatchPort`'s `resolveTargetsFor` and double-watching one physical inbox.
+- `test/js/report-wake-worktree.test.mjs` no longer sleeps fixed 700/900 ms gaps: an awaited-event helper (`waitFor`, 25 ms poll with a 5 s deadline) awaits each expected wake directly, removing slow-machine flake and shortening the fast path.
 
-### Added
-- Initial package scaffold for PI handbook integration support.

data/README.md

@@ -21,9 +21,9 @@
 
 **Consume canonical skills from PI tooling** - keep provider-specific behavior while preserving shared semantics, so agents running under pi-agent get the same skill intent as any other provider.
 
-**Run the in-process overseer loop with `/work-backlog`** - the canonical `handbook/prompts/work-backlog.md` template projects to `.pi/prompts/work-backlog.md` (`ace-handbook sync --provider pi`), giving pi a slash command that cycles the task backlog (select → execute via `as-task-work` → verify → report) inside the pi session itself - no tmux windows or external orchestrator.
+**Resume commissioned work with `/continue-work`** - the canonical `handbook/prompts/continue-work.md` template projects to `.pi/prompts/continue-work.md` (`ace-handbook sync --provider pi`). It is the L7.3 resume prompt for a pi overseer session: after a report wake or a session restart it reads `_overseer` tasks, `ace-assign` assignments, and current project truth, then continues the SAME commissioned process through the existing `ace-overseer` gates (`process-reports`, `work-on`, `handoff`) - one execution, no self-seeking of new work.
 
-**Wake idle agents with `/loop` timers and `/watch` file subscriptions** - the bundled ace-wake extension (projected to `.pi/extensions/ace-wake/index.js`) queues bounded wake messages to the live agent through `sendUserMessage` only. Wakes coalesce per source, busy agents receive queued follow-ups instead of interruptions, definitions survive reload/restart with exactly-once re-registration, and there is no cron, systemd, or external heartbeat dependency. See [docs/usage.md](docs/usage.md).
+**Wake idle agents with `/loop` timers and `/watch` file subscriptions** - the bundled ace-wake extension (projected to `.pi/extensions/ace-wake/index.js`) queues bounded wake messages to the live agent through `sendUserMessage` only. Wakes coalesce per source, busy agents receive queued follow-ups instead of interruptions, definitions survive reload/restart with exactly-once re-registration, and there is no cron, daemon, heartbeat, or delivery-queue engine. See [docs/usage.md](docs/usage.md).
 
 **Keep provider updates constrained** - update projection assets inside this package instead of canonical definitions, keeping changes isolated from [ace-handbook](../ace-handbook).
 

data/handbook/extensions/ace-wake/index.js

@@ -169,6 +169,10 @@ function createRegistry(pi, ctx, ports) {
       watchFactory: ports.watchFactory ?? nodeWatchFactory,
       statFn: ports.statFn ?? nodeStatFn,
       baseDir: ctx.cwd,
+      // The report-inbox watch covers every linked worktree's
+      // .ace-local/hitl by default (the same git worktree discovery
+      // ace-hitl's list uses); injectable for deterministic tests.
+      resolveTargets: ports.resolveTargets,
       scheduleReconcile: ports.scheduleReconcile,
       onDeactivate: () => registry?.refreshStatus(),
     }),

data/handbook/extensions/ace-wake/wake/inbox-discovery.js

@@ -0,0 +1,111 @@
+import { execFileSync } from "node:child_process";
+import * as nodeFs from "node:fs";
+import * as nodePath from "node:path";
+
+/**
+ * Cross-worktree discovery for the ace-hitl report inbox.
+ *
+ * `ace-hitl create` writes a coworker's report inside THAT coworker's
+ * worktree (its own `.ace-local/hitl`), while the overseer session usually
+ * waits in the main checkout — a watch on the main checkout's inbox alone
+ * never fires. The HITL list already solves this with multi-worktree
+ * discovery over `git worktree list --porcelain`; this module reuses the
+ * SAME discovery (no second inbox, queue, or cache) to expand a configured
+ * `.ace-local/hitl` watch to every linked worktree's inbox directory.
+ *
+ * Expansion happens at watch registration, at every re-registration
+ * (session start/reload/branch switch), and on every watch refresh pass,
+ * so worktrees linked while the session is already watching are picked
+ * up without waiting for a re-registration.
+ */
+
+/** The inbox path suffix that marks a watch as the ace-hitl report inbox. */
+export const HITL_INBOX_SEGMENTS = [".ace-local", "hitl"];
+
+/**
+ * List the roots of every linked worktree (including the main checkout)
+ * using the same porcelain output ace-hitl's WorktreeScopeResolver reads.
+ *
+ * @param {string} baseDir session working directory (git runs there)
+ * @param {(args: string[], options: object) => string} [execGit] injectable
+ *   git runner for tests; defaults to execFileSync with output decoding
+ * @returns {string[]} unique worktree roots, main first; [] when git fails
+ */
+export function discoverWorktreeRoots(baseDir, execGit = defaultExecGit) {
+  let output;
+  try {
+    output = execGit(["worktree", "list", "--porcelain"], { cwd: baseDir });
+  } catch {
+    // Not a repository (or git missing): the caller keeps whatever targets
+    // it can resolve on its own.
+    return [];
+  }
+  return output
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("worktree "))
+    .map((line) => line.slice("worktree ".length).trim())
+    .filter((path) => path.length > 0);
+}
+
+/**
+ * Resolve the watch targets for a configured path. A path that names an
+ * ace-hitl inbox (any `.ace-local/hitl` directory) expands to that same
+ * inbox in EVERY discovered worktree, so a report written inside a
+ * coworker's worktree wakes the waiting session. Any other path stays a
+ * single target — the watch never invents unrelated directories.
+ *
+ * @param {string} baseDir session working directory
+ * @param {string} configuredPath the path the user configured
+ * @param {(args: string[], options: object) => string} [execGit]
+ * @returns {string[]} canonical target directories, sorted and unique
+ */
+export function expandInboxWatchTargets(baseDir, configuredPath, execGit = defaultExecGit) {
+  const primary = realpathOrSelf(nodePath.resolve(baseDir, configuredPath));
+  if (!namesInbox(primary)) {
+    return [primary];
+  }
+  const roots = discoverWorktreeRoots(baseDir, execGit);
+  if (roots.length === 0) {
+    return [primary];
+  }
+  // Realpath the (existing) worktree ROOT, not the not-yet-existing inbox:
+  // /tmp → /private/tmp style symlinked roots would otherwise survive as
+  // separate strings and defeat dedup against the canonicalized primary.
+  const targets = new Set(roots.map((root) => nodePath.join(realpathOrSelf(root), ...HITL_INBOX_SEGMENTS)));
+  targets.add(primary);
+  return [...targets].sort();
+}
+
+/**
+ * @param {string} path
+ * @returns {string} The realpath when the path exists, the path itself otherwise.
+ */
+function realpathOrSelf(path) {
+  try {
+    return nodeFs.realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/** @param {string} path @returns {boolean} */
+function namesInbox(path) {
+  const segments = nodePath.normalize(path).split(nodePath.sep);
+  const last = HITL_INBOX_SEGMENTS.length;
+  for (let index = segments.length - last; index >= 0; index -= 1) {
+    const window = segments.slice(index, index + last);
+    if (window.join(nodePath.sep) === HITL_INBOX_SEGMENTS.join(nodePath.sep)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{cwd: string}} options
+ * @returns {string}
+ */
+function defaultExecGit(args, options) {
+  return execFileSync("git", args, { ...options, encoding: "utf8" });
+}

data/handbook/extensions/ace-wake/wake/watch-subscription.js

@@ -1,6 +1,7 @@
 import * as nodeFs from "node:fs";
 import * as nodePath from "node:path";
 import { WakeError } from "./types.js";
+import { expandInboxWatchTargets } from "./inbox-discovery.js";
 
 /**
  * Resolve a configured watch path to the filesystem target: relative paths
@@ -27,18 +28,30 @@ export function canonicalizeWatchPath(baseDir, path) {
  *
  * start() resolves the configured path to a canonical absolute target (relative
  * paths resolve against `baseDir`; symlinks resolve to their target), validates
- * readable metadata, and records a baseline fingerprint. Only later fingerprint
+ * readable metadata, and records a baseline fingerprint. An injected
+ * `resolveTargets` port may expand the configured path to several targets —
+ * the ace-hitl inbox watch expands `.ace-local/hitl` to every linked
+ * worktree's inbox, because `ace-hitl create` writes reports inside the
+ * coworker's worktree, not the main checkout. Discovery re-runs on every
+ * change/reconcile pass, so worktrees linked AFTER registration are
+ * picked up without a re-registration or session reload. The fingerprint
+ * aggregates all
+ * targets; a target that does not exist yet is a stable "absent" state, so
+ * the first report into a freshly created inbox still wakes. Only later fingerprint
  * changes wake the agent, so registering a watch never produces an initial
  * wake. When a wake coalesces into one already queued, the fingerprint stays
  * at the previously delivered state: the queued wake covers the change, and a
  * further change queues a fresh follow-up after settlement.
  *
- * A watcher runtime error (path deleted, permission lost) closes the handle,
- * marks the subscription inactive with a visible error via the injected
- * `onDeactivate` hook, and never retries: the user removes and re-adds the
- * watch explicitly. `fail()` records the same inactive-error state without a
- * native handle, which reconciliation uses for subscriptions that could not
- * be restarted.
+ * A watcher runtime error on the configured (primary) path closes the
+ * handle, marks the subscription inactive with a visible error via the
+ * injected `onDeactivate` hook, and never retries: the user removes and
+ * re-adds the watch explicitly. A runtime error on a DISCOVERED extra
+ * target (e.g. `ace-overseer prune` removed a watched worktree) drops only
+ * that target's watcher and keeps the subscription alive for every other
+ * worktree; discovery re-attaches the target if it reappears. `fail()`
+ * records the same inactive-error state without a native handle, which
+ * reconciliation uses for subscriptions that could not be restarted.
  *
  * @param {object} ports
  * @param {(path: string, handlers: {onChange: () => void, onError: (error: Error) => void}) => {close: () => void}} ports.watchFactory
@@ -62,9 +75,12 @@ export function canonicalizeWatchPath(baseDir, path) {
  * }}
  */
 const RECONCILE_DELAY_MS = 500;
+// How far above a not-yet-existing target an ancestor watch may climb
+// (enough for <worktree>/.ace-local/hitl inside any sane worktree layout).
+const MAX_ANCESTOR_CLIMB = 6;
 
-export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(), canonicalizeFn = canonicalizeWatchPath, scheduleReconcile = defaultScheduleReconcile, onDeactivate }) {
-  /** @type {Map<string, {watcher: {close: () => void}, canonicalPath: string, definition: import("./types.js").WatchDefinition, fingerprint: string, previousFingerprint: string, dirty: boolean}>} */
+export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(), canonicalizeFn = canonicalizeWatchPath, resolveTargets = expandInboxWatchTargets, scheduleReconcile = defaultScheduleReconcile, onDeactivate }) {
+  /** @type {Map<string, {watchers: Array<{path: string, watchPath: string, watcher: {close: () => void}}>, paths: string[], definition: import("./types.js").WatchDefinition, fingerprint: string, previousFingerprint: string, dirty: boolean}>} */
   const active = new Map();
   /** @type {Map<string, string>} */
   const errors = new Map();
@@ -78,21 +94,21 @@ export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(),
       errors.delete(definition.name);
 
       const canonicalPath = canonicalizeFn(baseDir, definition.path);
-      const baseline = readBaseline(canonicalPath);
-      const fingerprint = fingerprintOf(baseline);
-      const watcher = watchFactory(canonicalPath, {
-        onChange: () => handleChange(definition, onWake),
-        onError: (error) => {
-          // A callback from a removed registration must never touch its
-          // replacement.
-          if (active.get(definition.name)?.definition !== definition) {
-            return;
-          }
-          deactivate(definition.name, describeError(error));
-        },
-      });
+      // The configured path itself must be readable; expansion targets may
+      // legitimately not exist yet (an inbox in a worktree that never
+      // received a report), so only the primary is validated strictly.
+      readBaseline(canonicalPath);
+      const targetPaths = resolveTargetsFor(resolveTargets, baseDir, definition.path, canonicalPath);
+      const watchers = targetPaths.flatMap((target) => attachWatcher(target, definition, onWake));
+      const paths = watchers.map((entry) => entry.path);
+      // A target watched through an ancestor was PROVEN absent just now;
+      // its baseline records that fact rather than a re-stat, so a report
+      // created between the proof and this recomputation stays a change
+      // (the scheduled reconcile below delivers it).
+      const provenAbsent = new Set(watchers.filter((each) => each.watchPath !== each.path).map((each) => each.path));
+      const fingerprint = aggregateFingerprint(paths, canonicalPath, provenAbsent);
 
-      active.set(definition.name, { watcher, canonicalPath, definition, fingerprint, previousFingerprint: fingerprint, dirty: false });
+      active.set(definition.name, { watchers, paths, primaryPath: canonicalPath, definition, fingerprint, previousFingerprint: fingerprint, dirty: false });
       // Close the registration gap: a change between baseline capture and
       // watcher effectiveness produces no callback, so re-stat once.
       scheduleReconcile(() => handleChange(definition, onWake));
@@ -112,23 +128,32 @@ export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(),
     },
 
     /**
-     * Re-check subscriptions whose change was absorbed by a pending wake.
-     * Called after the agent settles (pending markers cleared): a subscription
-     * whose current state still differs from its last delivered fingerprint
-     * fires a fresh wake — no new filesystem event required.
+     * Re-check subscriptions after the agent settles (pending markers
+     * cleared). Target discovery refreshes for EVERY active subscription:
+     * a worktree linked while the session was watching whose first report
+     * landed in its own (then-unwatched) inbox produced no watched-path
+     * event, so this settlement boundary is the channel that notices it.
+     * A subscription whose current state still differs from its last
+     * delivered fingerprint fires a fresh wake — no new filesystem event
+     * required.
      *
      * @param {(definition: import("./types.js").WatchDefinition) => {delivered: boolean, reason?: string} | undefined} onWake
      */
     flushDirty(onWake) {
       for (const entry of active.values()) {
-        if (!entry.dirty) {
+        // Settlement boundaries refresh target discovery for EVERY active
+        // subscription, not only dirty ones: a worktree linked long after
+        // start whose first report lands in its own (not yet watched)
+        // inbox produces no watched-path event, so this pass is the only
+        // channel that can notice the new target and wake.
+        refreshAttachments(entry, entry.definition, onWake);
+        if (active.get(entry.definition.name)?.definition !== entry.definition) {
           continue;
         }
-        const current = readBaselineOrError(entry.canonicalPath, entry.definition.name);
-        if (current === undefined) {
+        const next = currentFingerprint(entry, entry.definition.name);
+        if (next === undefined) {
           continue;
         }
-        const next = fingerprintOf(current);
         if (next === entry.fingerprint) {
           entry.dirty = false;
           continue;
@@ -202,10 +227,12 @@ export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(),
   function stopExisting(name) {
     const entry = active.get(name);
     if (entry !== undefined) {
-      try {
-        entry.watcher.close();
-      } catch {
-        // Closing an already-broken watcher must not mask the original error.
+      for (const { watcher } of entry.watchers) {
+        try {
+          watcher.close();
+        } catch {
+          // Closing an already-broken watcher must not mask the original error.
+        }
       }
       active.delete(name);
     }
@@ -219,11 +246,16 @@ export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(),
     if (entry === undefined || entry.definition !== definition) {
       return;
     }
-    const current = readBaselineOrError(entry.canonicalPath, definition.name);
-    if (current === undefined) {
+    refreshAttachments(entry, definition, onWake);
+    // Re-attachment failure deactivates the subscription; a deactivated
+    // definition must not deliver a wake from the same pass.
+    if (active.get(definition.name)?.definition !== definition) {
+      return;
+    }
+    const next = currentFingerprint(entry, definition.name);
+    if (next === undefined) {
       return;
     }
-    const next = fingerprintOf(current);
     if (next === entry.fingerprint) {
       return;
     }
@@ -269,6 +301,304 @@ export function createWatchPort({ watchFactory, statFn, baseDir = process.cwd(),
       return undefined;
     }
   }
+
+  /**
+   * Resolve the watch targets for one configured path. An injected
+   * `resolveTargets` port (the ace-hitl inbox expansion) may return several
+   * directories; the validated primary canonical path is always watched,
+   * whatever the port returns.
+   *
+   * @param {((baseDir: string, path: string) => string[]) | undefined} resolveTargets
+   * @param {string} baseDir
+   * @param {string} configuredPath
+   * @param {string} canonicalPath
+   * @returns {string[]}
+   */
+  function resolveTargetsFor(resolveTargets, baseDir, configuredPath, canonicalPath) {
+    if (!resolveTargets) {
+      return [canonicalPath];
+    }
+    const expanded = resolveTargets(baseDir, configuredPath)
+      .filter((path) => typeof path === "string" && path.length > 0)
+      .map((path) => nodePath.resolve(path));
+    return [...new Set([canonicalPath, ...expanded])];
+  }
+
+  /**
+   * Attach one native watcher for a target. A target that does not exist
+   * yet (a worktree inbox with no report so far) is watched through its
+   * nearest EXISTING ancestor directory: the ancestor's events re-stat the
+   * target, so the first report — which creates the inbox — still wakes.
+   * When no ancestor is readable the target is skipped until the next
+   * re-registration.
+   *
+   * @param {string} target
+   * @param {import("./types.js").WatchDefinition} definition
+   * @param {(definition: import("./types.js").WatchDefinition) => unknown} onWake
+   * @returns {Array<{path: string, watchPath: string, watcher: {close: () => void}}>}
+   */
+  function attachWatcher(target, definition, onWake) {
+    const handlers = {
+      onChange: () => handleChange(definition, onWake),
+      onError: (error) => {
+        // A callback from a removed registration must never touch its
+        // replacement.
+        const entry = active.get(definition.name);
+        if (entry === undefined || entry.definition !== definition) {
+          return;
+        }
+        if (target !== entry.primaryPath) {
+          // A discovered extra target died (the worktree was pruned):
+          // drop only this target's watcher, keep the subscription.
+          dropTarget(entry, target);
+          return;
+        }
+        deactivate(definition.name, describeError(error));
+      },
+    };
+    let watchPath = target;
+    let attempts = 0;
+    for (;;) {
+      try {
+        statFn(watchPath);
+        break;
+      } catch {
+        if (attempts >= MAX_ANCESTOR_CLIMB || watchPath === nodePath.dirname(watchPath)) {
+          return [];
+        }
+        attempts += 1;
+        watchPath = nodePath.dirname(watchPath);
+      }
+    }
+    return [{ path: target, watchPath, watcher: watchFactory(watchPath, handlers) }];
+  }
+
+  /**
+   * Re-run target discovery and re-attach targets that were watched
+   * through an ancestor because they did not exist yet. Runs on every
+   * change/reconcile pass — exactly when a formerly-absent target may
+   * have appeared, and when a worktree linked AFTER registration may have
+   * become discoverable: discovery (the ace-hitl inbox expansion over
+   * `git worktree list`) no longer runs only at registration, so a task
+   * worktree created while the session is already watching gets its
+   * inbox watched without any re-registration or reload.
+   *
+   * Linux inotify is non-recursive, so an ancestor's watch never sees a
+   * SECOND report created inside the now-existing target; once the target
+   * exists, close the ancestor watch and watch the real target directly.
+   *
+   * A newly discovered target that does not exist yet joins the baseline
+   * fingerprint as its PROVEN "absent" state (never a re-stat, so a report
+   * created between the discovery stat and the baseline recomputation stays
+   * a pending change) and a follow-up reconcile pass — mirroring start() —
+   * delivers any change that landed in the attach gap; its later appearance
+   * (the first report) is the change that wakes, not its discovery.
+   *
+   * @param {{watchers: Array<{path: string, watchPath: string, watcher: {close: () => void}}>, paths: string[], primaryPath: string, fingerprint: string, previousFingerprint: string}} entry
+   * @param {import("./types.js").WatchDefinition} definition
+   * @param {(definition: import("./types.js").WatchDefinition) => unknown} onWake
+   */
+  function refreshAttachments(entry, definition, onWake) {
+    refreshDiscoveredTargets(entry, definition, onWake);
+    if (active.get(definition.name)?.definition !== definition) {
+      return;
+    }
+    for (let index = 0; index < entry.watchers.length; index += 1) {
+      const attached = entry.watchers[index];
+      if (attached.watchPath === attached.path) {
+        continue;
+      }
+      try {
+        statFn(attached.path);
+      } catch {
+        // Still absent: the ancestor watch remains the only channel.
+        continue;
+      }
+      try {
+        // Attach the replacement BEFORE closing the old watcher:
+        // watchFactory can throw synchronously (EMFILE, EPERM, stat race),
+        // and handleChange runs inside native watcher callbacks — an
+        // uncaught throw here would crash the extension host. On failure
+        // the documented runtime-error posture applies: deactivate and
+        // never retry.
+        const replacement = attachWatcher(attached.path, definition, onWake);
+        if (replacement.length > 0) {
+          try {
+            attached.watcher.close();
+          } catch {
+            // Closing an already-broken watcher must not block re-attachment.
+          }
+          entry.watchers[index] = replacement[0];
+        }
+      } catch (error) {
+        deactivate(definition.name, `re-attachment failed: ${describeError(error)}`);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Re-run target discovery for one subscription and attach watchers for
+   * targets that appeared since the last pass (a worktree linked after
+   * registration, whose inbox the registration-time expansion could not
+   * have seen). A new target that already exists keeps the OLD baseline
+   * fingerprint, so the pass's fingerprint comparison delivers the wake
+   * the missed event never could; a new target that is still absent joins
+   * the baseline as its stable "absent" state, so only its later
+   * appearance (the first report) wakes.
+   *
+   * @param {{watchers: Array<{path: string, watchPath: string, watcher: {close: () => void}}>, paths: string[], primaryPath: string, fingerprint: string, previousFingerprint: string}} entry
+   * @param {import("./types.js").WatchDefinition} definition
+   * @param {(definition: import("./types.js").WatchDefinition) => unknown} onWake
+   */
+  function refreshDiscoveredTargets(entry, definition, onWake) {
+    if (!resolveTargets) {
+      return;
+    }
+    const targetPaths = resolveTargetsFor(resolveTargets, baseDir, definition.path, entry.primaryPath);
+    let attachedAny = false;
+    for (const target of targetPaths) {
+      if (entry.watchers.some((attached) => attached.path === target)) {
+        continue;
+      }
+      let attachedWatcher;
+      try {
+        attachedWatcher = attachWatcher(target, definition, onWake);
+      } catch (error) {
+        deactivate(definition.name, `re-attachment failed: ${describeError(error)}`);
+        return;
+      }
+      if (attachedWatcher.length === 0) {
+        // No readable ancestor yet: retried on the next pass.
+        continue;
+      }
+      entry.watchers.push(attachedWatcher[0]);
+      entry.paths = entry.watchers.map((each) => each.path);
+      attachedAny = true;
+      if (attachedWatcher[0].watchPath !== target) {
+        // The baseline records the "absent" state PROVEN by the ancestor
+        // climb, never a re-stat: a report created between the two must
+        // remain a pending change. The follow-up reconcile scheduled
+        // below delivers it without waiting for another event.
+        const baseline = aggregateFingerprint(entry.paths, entry.primaryPath, new Set([target]));
+        entry.previousFingerprint = baseline;
+        entry.fingerprint = baseline;
+      }
+    }
+    if (attachedAny) {
+      // Mirror start(): a change landing in the attach gap (the race
+      // above, or watcher initialization latency on the new target)
+      // produces no callback, so re-stat once.
+      scheduleReconcile(() => handleChange(definition, onWake));
+    }
+  }
+
+  /**
+   * Drop the watcher of one discovered extra target after a runtime error
+   * (typically `ace-overseer prune` removing the worktree): only that
+   * target's handle closes; the subscription stays active for the primary
+   * and every other worktree. The target's disappearance is absorbed into
+   * the baseline — a pruned worktree is not a report and must not wake.
+   *
+   * The baselines are adjusted by removing ONLY the dropped target's
+   * segment from the recorded fingerprint strings. Re-statting every
+   * remaining target would fold an undelivered change (a deferred wake
+   * left the fingerprint at its pre-change state) into the baseline,
+   * silently losing the pending report; the segment removal keeps every
+   * remaining target at its recorded state, so the settlement boundary
+   * still delivers it. It also never touches the filesystem at all, so a
+   * primary deleted moments earlier cannot throw from inside the native
+   * onError callback (the primary's own watcher error deactivates the
+   * subscription through the documented path).
+   *
+   * @param {{watchers: Array<{path: string, watchPath: string, watcher: {close: () => void}}>, paths: string[], primaryPath: string, fingerprint: string, previousFingerprint: string}} entry
+   * @param {string} target
+   */
+  function dropTarget(entry, target) {
+    const remaining = [];
+    for (const attached of entry.watchers) {
+      if (attached.path === target) {
+        try {
+          attached.watcher.close();
+        } catch {
+          // Closing an already-broken watcher must not mask the original error.
+        }
+      } else {
+        remaining.push(attached);
+      }
+    }
+    if (remaining.length === entry.watchers.length) {
+      return;
+    }
+    entry.watchers = remaining;
+    entry.paths = remaining.map((each) => each.path);
+    // The `=` terminator makes the prefix match the segment of exactly this
+    // target, never a target whose path merely extends it.
+    const droppedPrefix = `${target}=`;
+    entry.fingerprint = withoutSegment(entry.fingerprint, droppedPrefix);
+    entry.previousFingerprint = withoutSegment(entry.previousFingerprint, droppedPrefix);
+  }
+
+  /**
+   * Remove one target's `path=fingerprint` segment from an aggregate
+   * fingerprint string, keeping every other segment verbatim.
+   *
+   * @param {string} fingerprint
+   * @param {string} segmentPrefix The exact `path=` prefix of the removed target.
+   * @returns {string}
+   */
+  function withoutSegment(fingerprint, segmentPrefix) {
+    return fingerprint
+      .split("|")
+      .filter((segment) => !segment.startsWith(segmentPrefix))
+      .join("|");
+  }
+
+  /**
+   * Current aggregate fingerprint of a subscription. An unreadable
+   * PRIMARY deactivates the subscription (the configured path itself is
+   * the contract); an unreadable extra target is a stable "absent" state
+   * that changes to a real fingerprint once the target appears.
+   *
+   * @param {{paths: string[], primaryPath: string}} entry
+   * @param {string} name
+   * @returns {string | undefined}
+   */
+  function currentFingerprint(entry, name) {
+    try {
+      return aggregateFingerprint(entry.paths, entry.primaryPath);
+    } catch (error) {
+      deactivate(name, describeError(error));
+      return undefined;
+    }
+  }
+
+  /**
+   * @param {string[]} paths sorted target paths
+   * @param {string} primaryPath
+   * @param {Set<string>} [forcedAbsent] Targets recorded as "absent" without
+   *   re-statting — the proven-at-discovery baseline of a newly attached
+   *   target, so a report created in the stat/recompute gap stays a change.
+   * @returns {string}
+   */
+  function aggregateFingerprint(paths, primaryPath, forcedAbsent) {
+    return [...paths]
+      .sort()
+      .map((path) => {
+        if (forcedAbsent?.has(path)) {
+          return `${path}=absent`;
+        }
+        if (path === primaryPath) {
+          return `${path}=${fingerprintOf(statFn(path))}`;
+        }
+        try {
+          return `${path}=${fingerprintOf(statFn(path))}`;
+        } catch {
+          return `${path}=absent`;
+        }
+      })
+      .join("|");
+  }
 }
 
 /**
@@ -302,16 +632,31 @@ function describeError(error) {
 /**
  * Default watchFactory over node:fs.watch.
  *
- * Watches the target's parent directory and filters events to the target's
- * basename: watching the file itself keeps following the original inode, so
- * atomic replacement (write-to-temporary + rename) would silently detach the
- * subscription after one change.
+ * Directory targets are watched directly and accept any child event: on
+ * Linux (inotify) a child file's creation is delivered only to a watch on
+ * the directory itself, never to a watch on its parent. The mtime/size
+ * fingerprint comparison filters noise, so accepting every event is safe.
+ *
+ * File targets keep watching the parent directory and filter events to the
+ * target's basename: watching the file itself keeps following the original
+ * inode, so atomic replacement (write-to-temporary + rename) would silently
+ * detach the subscription after one change.
  *
- * @param {string} path Canonical path of the watched file.
+ * @param {string} path Canonical path of the watched file or directory.
  * @param {{onChange: () => void, onError: (error: Error) => void}} handlers
  * @returns {{close: () => void}}
  */
 export function nodeWatchFactory(path, handlers) {
+  if (nodeFs.statSync(path).isDirectory()) {
+    const watcher = nodeFs.watch(path, { persistent: false }, () => {
+      // Any child event is checked: the fingerprint comparison filters
+      // non-changes, including nested relative paths some platforms report.
+      handlers.onChange();
+    });
+    watcher.on("error", (error) => handlers.onError(error));
+    watcher.unref?.();
+    return watcher;
+  }
   const directory = nodePath.dirname(path);
   const target = nodePath.basename(path);
   const watcher = nodeFs.watch(

data/handbook/prompts/continue-work.md

@@ -0,0 +1,38 @@
+---
+description: Resume the commissioned overseer process after a report wake or session restart — same process, same assignments, no self-seeking
+argument-hint: "[report-ref]"
+source: ace-handbook-integration-pi
+last_modified: 2026-10-19
+---
+
+Resume the **already commissioned** overseer process in this pi session. This prompt runs on two triggers only: a report/notification message woke the session, or the session restarted. Either way the job is the same — continue the existing commissioned process and its assignments. This session is the one overseer execution: a message arriving while you are already working is a follow-up for THIS run, processed in this turn. Never start a second overseer, window, loop, or agent for the same commission.
+
+## Arguments
+
+`${1:-}` is an optional report/event reference from the waking message. When omitted, discover new reports in step 2.
+
+## Resume cycle
+
+1. **Read truth, not memory.** Reconstruct the current state from the files that own it — never from what the previous turn believed:
+   - Private overseer tasks: `ace-task --in _overseer list`, then `ace-task --in _overseer show <ref>` for every `in-progress` task. These define the commissioned process.
+   - Assignments: the `ace-assign` plans under `.ace-local/assign/` for those tasks. Steps are read from the assignment; they are not copied anywhere else.
+   - Project truth: `ace-task list`, `ace-overseer status`, `ace-git-worktree list`, and `git status --short` in each involved worktree.
+2. **Process reports.** Run `ace-overseer process-reports` so incoming ace-hitl reports are interpreted against the managing task and the queue continues. Delivery repetition is not work repetition: an already-processed report (same event id) must not trigger the work again — `process-reports` dedups by event state; trust its output, not the count of wake messages.
+3. **Continue the commissioned work.** Run `ace-overseer work-on` to execute the next unblocked step(s) of the commissioned process, and `ace-overseer handoff` when a role finishes and the worktree passes to the next one. Record durable progress in the task folder with `ace-task update` (never edit frontmatter directly).
+
+## Stop conditions
+
+Stop this cycle and give a summary when one of these holds:
+
+- **Commission terminal.** The managing `_overseer` task is `done` — close out with a final report via `ace-hitl`.
+- **Blocked on a decision or an owner.** A blocker cannot be verified or cleared without a human or another owner. Record it with `ace-task update`, send the question via `ace-hitl`, and wait. Do not fill the wait with other work.
+- **Interrupted.** The user interjects. Yield immediately and summarize the state.
+
+## Non-negotiable rules
+
+- **No self-seeking.** Continue only the commissioned process, its assignments, and unblocked subtasks. When there is no new commissioned work, record that state and wait — do not pick project tasks, backlog items, or "useful" work on your own initiative.
+- **Single execution.** Repeated notifications (timer re-fire, redelivered report, duplicate wake) are transport noise for the same commission: verify against report/task state, then continue once. They never justify a second execution.
+- **One active worker per worktree.** Before handing off or starting a step, confirm with `ace-git-worktree list` / `ace-overseer status` that the previous role finished; sequential roles share one worktree.
+- An unreadable source (missing `_overseer` folder, unreadable assignment, dead runtime) is an error to report, not an empty-and-ready state, and never a reason to start replacement work on the same worktree.
+- Never reset or discard unrelated changes; commit path-scoped with `ace-git-commit <paths>`.
+- Temp files go to `/tmp/` or `.ace-local/<subfolder>/`, never the project root.

data/lib/ace/handbook/integration/pi/version.rb

@@ -4,7 +4,7 @@ module Ace
   module Handbook
     module Integration
       module Pi
-        VERSION = "0.5.0"
+        VERSION = "0.6.0"
       end
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-handbook-integration-pi
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-handbook
@@ -36,13 +36,14 @@ files:
 - README.md
 - handbook/extensions/ace-wake/index.js
 - handbook/extensions/ace-wake/package.json
+- handbook/extensions/ace-wake/wake/inbox-discovery.js
 - handbook/extensions/ace-wake/wake/loop-subscription.js
 - handbook/extensions/ace-wake/wake/types.js
 - handbook/extensions/ace-wake/wake/wake-command-parser.js
 - handbook/extensions/ace-wake/wake/wake-dispatcher.js
 - handbook/extensions/ace-wake/wake/wake-registry.js
 - handbook/extensions/ace-wake/wake/watch-subscription.js
-- handbook/prompts/work-backlog.md
+- handbook/prompts/continue-work.md
 - lib/ace/handbook/integration/pi.rb
 - lib/ace/handbook/integration/pi/version.rb
 homepage: https://github.com/cs3b/ace

data/handbook/prompts/work-backlog.md

@@ -1,38 +0,0 @@
----
-description: Run the ACE overseer loop in-process — pick, execute, and close backlog tasks one after another until a stop condition fires
-argument-hint: "[task-ref]"
-source: ace-handbook-integration-pi
-last_modified: 2026-09-27
----
-
-Run the ACE overseer loop **in-process**: this pi session is the overseer. Work the task backlog one task at a time from selection to terminal state, then continue with the next task -- no tmux windows, no detached workers, no external orchestrator. The loop lives in this session; every cycle uses the project's ACE CLI tools.
-
-## Arguments
-
-`${1:-}` is an optional task ref for the first cycle. When omitted, select from the backlog.
-
-## Loop cycle
-
-Repeat until a stop condition fires:
-
-1. **Select.** If `${1:-}` is set and not yet consumed, use it for this cycle and clear it afterwards. Otherwise run `ace-task list` and pick the first `pending` task in priority order that is actionable. Never pick a `done` task; skip tasks whose blocker is confirmed by an executed check (see below).
-2. **Execute.** Load the canonical `as-task-work` skill (`/skill:as-task-work <ref>`, or read `.pi/skills/as-task-work/SKILL.md`) and follow it end-to-end for the chosen ref: load the task spec and plan, mark the task in-progress, then work the plan step by step -- test after every change, commit each logical step with `ace-git-commit <paths>`, and leave the task in-progress (final delivery owns `done`).
-3. **Verify.** Before closing the cycle: `git status --short` is clean for everything your work produced, and the task's plan checklist and success criteria are satisfied -- or blockers are recorded with executed evidence.
-4. **Report.** One progress update per cycle: task ref, outcome (completed / blocked / skipped), and the executed command + observed output that proves it.
-
-## Stop conditions
-
-Stop the loop and give a final summary only when one of these holds:
-
-- **Backlog drained.** `ace-task list` shows no actionable `pending` work.
-- **Human decision required.** A task's spec is ambiguous or incomplete, or a blocker cannot be verified or cleared without the user. Do not assume and do not silently skip -- report the blocker together with the executed check that surfaced it.
-- **Interrupted.** The user interjects. Yield immediately and summarize the state of every cycle run so far.
-
-## Non-negotiable rules
-
-- Do not stop after intermediate progress; do not pause between cycles for confirmation.
-- A cycle that ends blocked on an owner dependency (confirmed by a runnable, non-secret executed check) does not stop the loop: record the blocker on the task with `ace-task update`, close stale blockers in the same pass, and continue with the next task. Only unverifiable or human-only blockers stop the loop.
-- Status truth: recorded blockers are claims, not state. Confirm or refute each blocker you rely on with an executed check in this session.
-- Never modify task frontmatter directly -- use `ace-task update <ref> --set key=value`.
-- Never reset or discard unrelated changes; commit path-scoped with `ace-git-commit <paths>`.
-- Temp files go to `/tmp/` or `.ace-local/<subfolder>/`, never the project root.