ace-handbook-integration-pi 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aecac8cdb81dfb6b51efda48199aeaf10e7267bbaed81dcec49acb0fa985553
-  data.tar.gz: baeff1aa2723ed7a0333c28d78fc5825d6b32dc5b6cdb7090900f3350358239f
+  metadata.gz: 4e1e1f851408ab94551b1f23f43b258fdd064b8df2790f0bb2a80ab05363983a
+  data.tar.gz: 7fa298d85b1ce4844320dc980d323b28079c2a05a37dd26ea3dc46d159a41f47
 SHA512:
-  metadata.gz: 761967528dfe314d715ea45cbc25476f27d2d5a2835bd12a3b39b3b2faba352adae6ff81ec7e91b0168fd9af44bb28f71a3a7e98f35fb55edf69cb1bae98edfd
-  data.tar.gz: bf06c8004e8b1c865093685cf7d17e3463857d3521fcfc3dfe89d088a4f6fd73d9b2f5d27b539d8e3555a843b4c7ed3e906a47aab92befeee9a4803311dd4c2d
+  metadata.gz: 75c4ed2da5fce4f238a8e8d7b401ee4ac524548f15fb3e5f574a9bd5f526f7b73eecbefc80241e814e6ac71d055253e619dffb2c87443b8c949f94b34ce304d1
+  data.tar.gz: 53bff4c326bad616aff1ddfcf417d16496cd3177f38c6cb35c95d40b2bd5fdcbe6b923883e55241af306c5f03671b96d1538dd2c244417af5928b96fd769560c

data/.ace-defaults/handbook/providers/pi.yml

@@ -1,3 +1,4 @@
 provider: pi
 output_dir: .pi/skills
 prompts_dir: .pi/prompts
+extensions_dir: .pi/extensions

data/CHANGELOG.md

@@ -4,89 +4,28 @@ All notable changes to ace-handbook-integration-pi will be documented in this fi
 
 ## [Unreleased]
 
-## [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,7 +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 `/loop`** - the canonical `handbook/prompts/loop.md` template projects to `.pi/prompts/loop.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, 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).
 
@@ -29,10 +31,11 @@
 
 ## Testing
 
-This package is **fast-only** in the ACE testing model.
+This package ships fast tests plus one installed-extension acceptance level.
 
-- Deterministic test coverage lives under `test/fast/`.
-- This migration does not introduce `test/feat/` or `test/e2e/` for this package.
+- Deterministic coverage (including the JavaScript wake suite run via Node) lives under `test/fast/` and `test/js/`.
+- `test/feat/` runs the ace-wake acceptance scenario against the projected extension inside the real Pi SDK runtime; it requires the `pi` CLI and Node.
+- This package does not introduce `test/e2e/`.
 
 Verification commands:
 

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

@@ -0,0 +1,345 @@
+// ace-wake — in-process loop and file-watch wakes for Pi agents.
+//
+// Named /loop timers and /watch file subscriptions queue a bounded wake
+// message to the agent through sendUserMessage only. The agent decides what
+// to do after waking; the extension never executes tasks and never depends on
+// cron, systemd, or any external heartbeat service. While the agent is busy a
+// wake is queued as a follow-up instead of interrupting an in-flight tool
+// operation. Definitions persist as session entries, survive compaction, and
+// reconcile exactly once per session start, reload, or branch switch.
+//
+// Commands:
+//   /loop add NAME --interval SECONDS --message TEXT
+//   /loop list
+//   /loop remove NAME
+//   /watch add NAME --path PATH --message TEXT
+//   /watch list
+//   /watch remove NAME
+
+import { clearInterval, setInterval } from "node:timers";
+
+import { WakeDispatcher } from "./wake/wake-dispatcher.js";
+import { parseWakeCommand } from "./wake/wake-command-parser.js";
+import { createLoopPort } from "./wake/loop-subscription.js";
+import { createWatchPort, nodeStatFn, nodeWatchFactory } from "./wake/watch-subscription.js";
+import {
+  SESSION_ENTRY_TYPE,
+  WakeError,
+  boundMessage,
+} from "./wake/types.js";
+import { WakeRegistry } from "./wake/wake-registry.js";
+
+const STATUS_KEY = "ace-wake";
+
+/**
+ * Extension factory. Pi calls it as `factory(pi)`; the optional second
+ * argument exists so tests can inject deterministic clock, watcher, and
+ * stat ports. Production defaults are real Node timers and fs.
+ *
+ * All mutable state lives inside this factory closure: one extension runtime
+ * (one pi process, or one SDK session) owns exactly one state slot, and
+ * multiple runtimes in one process never share state.
+ *
+ * @param {object} pi ExtensionAPI surface provided by Pi.
+ * @param {object} [ports] Injectable host ports for deterministic tests.
+ */
+export default function (pi, ports = {}) {
+  /** @type {{registry: WakeRegistry} | undefined} */
+  let runtime;
+
+  const getRuntime = () => runtime;
+  const bindRuntime = (ctx) => {
+    runtime?.registry.dispose();
+    runtime = { registry: createRegistry(pi, ctx, ports) };
+    runtime.registry.reconcile();
+  };
+
+  pi.registerCommand("loop", {
+    description: "Manage named timer loops that wake this agent (add | list | remove)",
+    handler: async (args, ctx) => {
+      await handleCommand(ctx, "loop", args, getRuntime, bindRuntime);
+    },
+  });
+
+  pi.registerCommand("watch", {
+    description: "Manage named file watches that wake this agent (add | list | remove)",
+    handler: async (args, ctx) => {
+      await handleCommand(ctx, "watch", args, getRuntime, bindRuntime);
+    },
+  });
+
+  // session_start covers startup, reload, resume, fork, and new sessions;
+  // session_tree covers branch switches. Reconciliation is idempotent, so a
+  // reload re-registers each configured subscription exactly once.
+  pi.on("session_start", async (_event, ctx) => {
+    bindRuntime(ctx);
+  });
+  pi.on("session_tree", async (_event, ctx) => {
+    bindRuntime(ctx);
+  });
+
+  // A run has begun: wakes dispatched concurrently during the idle-to-running
+  // transition can now enter the follow-up queue safely, so the registry
+  // drains anything it serialized.
+  pi.on("agent_start", async () => {
+    runtime?.registry.noteRunStarted();
+  });
+
+  // The agent consumed every queued continuation; same-source wakes may
+  // deliver again. Watches whose change was absorbed by a pending wake are
+  // re-checked so no change is lost without a new filesystem event.
+  pi.on("agent_settled", async () => {
+    runtime?.registry.settleAll();
+  });
+
+  // Manual compaction rejects sendUserMessage asynchronously (before, during,
+  // and briefly after the compaction events) and never emits agent_settled:
+  // wakes are retained while it runs and flushed once the context is actually
+  // idle again. Automatic compaction happens inside a run whose pending wakes
+  // stay legitimately queued, so it is left untouched.
+  pi.on("session_before_compact", async (event) => {
+    if (event.reason === "manual") {
+      runtime?.registry.pauseDelivery();
+    }
+  });
+  pi.on("session_compact", async (event, ctx) => {
+    if (event.reason === "manual") {
+      runtime?.registry.resumeDelivery();
+      scheduleManualCompactionFlush(ctx);
+    }
+  });
+  pi.on("session_compact_failed", async (event, ctx) => {
+    if (event.reason === "manual") {
+      runtime?.registry.resumeDelivery();
+      scheduleManualCompactionFlush(ctx);
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    runtime?.registry.dispose();
+    runtime = undefined;
+  });
+
+  /**
+   * Poll until the host context is genuinely idle (no run, no compaction) and
+   * then flush retained wakes. A single deferred callback is not enough: other
+   * session_compact handlers may await asynchronous work while Pi still rejects
+   * prompts. Bounded polling covers the idle-after-compaction case; a run that
+   * continues after compaction flushes via agent_settled instead.
+   */
+  function scheduleManualCompactionFlush(ctx) {
+    const pollMs = 100;
+    // Bound the poll to the session that scheduled it: a rebind or shutdown
+    // replaces the registry, and the old poll must not flush the new one.
+    const registry = runtime.registry;
+    const attempt = () => {
+      if (runtime?.registry !== registry) {
+        return;
+      }
+      let idle;
+      try {
+        idle = ctx.isIdle();
+      } catch {
+        return; // Stale context: session_start rebinds.
+      }
+      if (idle) {
+        registry.completeResume();
+        return;
+      }
+      const timer = setTimeout(attempt, pollMs);
+      timer.unref?.();
+    };
+    attempt();
+  }
+}
+
+function createRegistry(pi, ctx, ports) {
+  const dispatcher = new WakeDispatcher({
+    deliver: (sourceKey, text) => deliverWake(pi, ctx, sourceKey, text),
+  });
+  /** The registry is created after its watch port, so deactivation hooks go
+   * through this holder once it exists. */
+  let registry;
+  const built = new WakeRegistry({
+    loops: createLoopPort({
+      setIntervalFn: ports.setIntervalFn ?? ((callback, ms) => setInterval(callback, ms)),
+      clearIntervalFn: ports.clearIntervalFn ?? ((handle) => clearInterval(handle)),
+    }),
+    watches: createWatchPort({
+      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(),
+    }),
+    state: sessionStatePort(pi, ctx),
+    status: statusPort(ctx),
+    dispatcher,
+    dispatchRecoveryMs: ports.dispatchRecoveryMs,
+    isHostQueued: () => {
+      try {
+        return ctx.hasPendingMessages();
+      } catch {
+        return true;
+      }
+    },
+    isHostIdle: () => {
+      try {
+        return ctx.isIdle();
+      } catch {
+        return false;
+      }
+    },
+  });
+  registry = built;
+  return built;
+}
+
+/**
+ * Queue-only delivery, always as a queued follow-up. Pi runs a follow-up
+ * immediately when nothing is in flight and queues it behind any active run
+ * otherwise, so no window — between runs, during a tool, or while earlier
+ * wakes are queued — can drop a wake or interrupt an in-flight operation.
+ * The complete rendered message (source prefix included) is bounded.
+ */
+function deliverWake(pi, ctx, sourceKey, text) {
+  const message = boundMessage(`[ace-wake ${sourceKey}] ${text}`);
+  try {
+    // Known synchronous preflight: without a selected model Pi rejects the
+    // prompt asynchronously and no lifecycle event ever acknowledges it, so
+    // the wake is refused here and the next tick re-attempts instead of
+    // coalescing behind a stranded pending marker.
+    if (!ctx.model) {
+      return false;
+    }
+    pi.sendUserMessage(message, { deliverAs: "followUp" });
+    return true;
+  } catch {
+    // A stale context (session replaced/reloaded) or a rejecting host must
+    // not crash the timer callback; the next session_start rebinds.
+    return false;
+  }
+}
+
+function sessionStatePort(pi, ctx) {
+  return {
+    load() {
+      let snapshot;
+      for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type === "custom" && entry.customType === SESSION_ENTRY_TYPE && entry.data) {
+          snapshot = entry.data;
+        }
+      }
+      // getBranch() returns the stored entries themselves; cloning keeps
+      // registry mutations from rewriting historical session entries, which
+      // would leak later edits back into branched-away history.
+      return snapshot ? structuredClone(snapshot) : { loops: [], watches: [] };
+    },
+    save(snapshot) {
+      pi.appendEntry(SESSION_ENTRY_TYPE, snapshot);
+    },
+  };
+}
+
+function statusPort(ctx) {
+  return {
+    render(entries) {
+      try {
+        // Every context access — including hasUI — throws once the context
+        // is stale after session replacement, reload, or disposal.
+        if (!ctx.hasUI) {
+          return;
+        }
+        if (entries.length === 0) {
+          ctx.ui.setStatus(STATUS_KEY, undefined);
+          return;
+        }
+        const parts = entries.map((entry) => {
+          const state = entry.error ? " error" : entry.pending ? " pending" : "";
+          return `${entry.kind} ${entry.name}${state} ${entry.detail}`;
+        });
+        ctx.ui.setStatus(STATUS_KEY, parts.join(" | "));
+      } catch {
+        // Stale context: skip the render; the next session_start rebinds.
+      }
+    },
+  };
+}
+
+async function handleCommand(ctx, kind, args, getRuntime, bindRuntime) {
+  try {
+    if (!getRuntime()) {
+      bindRuntime(ctx);
+    }
+    const registry = getRuntime().registry;
+    const parsed = parseWakeCommand(kind, args);
+    switch (parsed.subcommand) {
+      case "add":
+        addSubscription(registry, kind, parsed);
+        notify(ctx, `${kind} "${parsed.name}" added`, "info");
+        break;
+      case "list":
+        notify(ctx, formatList(kind, registry.list()), "info");
+        break;
+      case "remove":
+        removeSubscription(registry, kind, parsed.name);
+        notify(ctx, `${kind} "${parsed.name}" removed; no further wakes will fire`, "info");
+        break;
+      default:
+        throw new WakeError(`unknown ${kind} subcommand: ${parsed.subcommand}`);
+    }
+  } catch (error) {
+    notify(ctx, error instanceof WakeError ? error.message : `${kind} failed: ${error.message}`, "error");
+  }
+}
+
+function addSubscription(registry, kind, parsed) {
+  if (kind === "loop") {
+    registry.addLoop({
+      name: parsed.name,
+      intervalSeconds: parsed.flags.interval,
+      message: parsed.message,
+    });
+    return;
+  }
+  registry.addWatch({
+    name: parsed.name,
+    path: parsed.flags.path,
+    message: parsed.message,
+  });
+}
+
+function removeSubscription(registry, kind, name) {
+  if (kind === "loop") {
+    registry.removeLoop(name);
+    return;
+  }
+  registry.removeWatch(name);
+}
+
+/**
+ * @returns {string}
+ */
+function formatList(kind, entries) {
+  const plural = kind === "watch" ? "watches" : `${kind}s`;
+  const scoped = entries.filter((entry) => entry.kind === kind);
+  if (scoped.length === 0) {
+    return `no ${plural} configured`;
+  }
+  return scoped
+    .map((entry) => {
+      const state = entry.error ? ` ERROR: ${entry.error}` : entry.pending ? " (wake pending)" : "";
+      return `${entry.name} — ${entry.detail}${state}`;
+    })
+    .join("\n");
+}
+
+function notify(ctx, message, type) {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, type);
+  }
+}

data/handbook/extensions/ace-wake/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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" });
+}