ace-handbook-integration-pi 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c5ab037a9338b9466fc32aaed92e0418c5ef05e436ca790a6ef6c6706b88ffb
-  data.tar.gz: 1181cb6b7863f29e907af9e3cd9a008b10265225dd00537d55aa6127cfe80a05
+  metadata.gz: 9a4d798b4819221f1fc95c725700fc5911859b62a197ce3973389d18e208f6d4
+  data.tar.gz: 66c216a3a9c9ebd4164b1e6ea2e3d096b0e0f4468d3efc9ebb7941e6f652be47
 SHA512:
-  metadata.gz: 85683a4338df4a155fbc01bee9d8324b5be22cc9a5a0eaad3501d2359a5497d38545b7f45eae03b3eaf180095236bbaed7c8b5081130ed7300a89e72522e1c77
-  data.tar.gz: da305a0888d369118bc6c6c1e2ac965bc0468f807138a4f3a0a60e1c95f146f841fd083c125137d7a55718d1a3c91993ee2ca0c4751a05b2af9ae5531cb98fc7
+  metadata.gz: 1b2818ac03f7a22254d4247ae0a6374e738dbdad853ebf06d08c92c76619bc746ed0d9365f42590d1057322bdede120459ec6de718b795cd702182f24a1d3047
+  data.tar.gz: 8b31425debbb283d7694fbb8e38222271f55762f4eae14c59f84e3719d97d41b96d85e6921605e5c14e76a1564b4593513324fa5d65a3f8518794343d8f79533

data/CHANGELOG.md

@@ -4,100 +4,34 @@ All notable changes to ace-handbook-integration-pi will be documented in this fi
 
 ## [Unreleased]
 
-## [0.5.0] - 2026-09-28
+## [0.7.0] - 2026-10-23
 
 ### 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).
+- Add durable in-process semantic eyes, coalescing, explicit deadlines, bounded budgets and actual Pi notification acceptance; retire the actor’s old loops when enabled.
 
-## [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

@@ -18,6 +18,7 @@
 
 import { clearInterval, setInterval } from "node:timers";
 
+import { registerEyes } from "./wake/eyes-runtime.js";
 import { WakeDispatcher } from "./wake/wake-dispatcher.js";
 import { parseWakeCommand } from "./wake/wake-command-parser.js";
 import { createLoopPort } from "./wake/loop-subscription.js";
@@ -47,6 +48,7 @@ export default function (pi, ports = {}) {
   /** @type {{registry: WakeRegistry} | undefined} */
   let runtime;
 
+  let eyes;
   const getRuntime = () => runtime;
   const bindRuntime = (ctx) => {
     runtime?.registry.dispose();
@@ -57,6 +59,9 @@ export default function (pi, ports = {}) {
   pi.registerCommand("loop", {
     description: "Manage named timer loops that wake this agent (add | list | remove)",
     handler: async (args, ctx) => {
+      if (eyes.active() && args.trim().startsWith("add")) {
+        ctx.ui?.notify?.("Legacy loops are retired while eyes owns observation", "error"); return;
+      }
       await handleCommand(ctx, "loop", args, getRuntime, bindRuntime);
     },
   });
@@ -64,6 +69,9 @@ export default function (pi, ports = {}) {
   pi.registerCommand("watch", {
     description: "Manage named file watches that wake this agent (add | list | remove)",
     handler: async (args, ctx) => {
+      if (eyes.active() && args.trim().startsWith("add")) {
+        ctx.ui?.notify?.("Legacy watches are retired while eyes owns observation", "error"); return;
+      }
       await handleCommand(ctx, "watch", args, getRuntime, bindRuntime);
     },
   });
@@ -78,6 +86,16 @@ export default function (pi, ports = {}) {
     bindRuntime(ctx);
   });
 
+  eyes = registerEyes(pi, { ...ports.eyes,
+    retireLegacy: () => {
+      if (!runtime) return;
+      const list = runtime.registry.list();
+      for (const entry of list) {
+        if (entry.kind === "loop") runtime.registry.removeLoop(entry.name);
+        else runtime.registry.removeWatch(entry.name);
+      }
+    } });
+
   // 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.
@@ -169,6 +187,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/eyes-runtime.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Eyes, EYES_ENTRY } from "./eyes.js";
+
+const execute = promisify(execFile);
+
+/** Existing native sync owns canonical import; HITL owns event projection.
+ * No Ruby parsing, private text, shell command strings or model work here. */
+export async function observeHitl(cwd, config) {
+  const options = { cwd, timeout: config.timeoutMs, maxBuffer: 1024 * 1024, encoding: "utf8" };
+  for (const route of config.syncRoutes) {
+    const { stdout } = await execute("ace-hitl-hermes", ["sync", "--config", route], options);
+    const result = JSON.parse(stdout);
+    if (!Array.isArray(result.errors) || result.errors.length) throw new Error("Native synchronization incomplete");
+  }
+  const { stdout } = await execute("ace-overseer", ["observe", "--owner", config.recipient, "--scope", config.scope, "--limit", String(config.maxEvents)], options);
+  return JSON.parse(stdout);
+}
+
+export function registerEyes(pi, { retireLegacy, observe = observeHitl, now = Date.now,
+  schedule = (fn, ms) => setInterval(fn, ms), cancel = clearInterval } = {}) {
+  let eyes, timer, attempt, compacting = false, running = false;
+  const stopTimer = () => { if (timer !== undefined) cancel(timer); timer = undefined; };
+  function arm() {
+    stopTimer();
+    if (eyes?.s.enabled && !eyes.s.retired && !eyes.s.breaker) {
+      timer = schedule(() => { void eyes.tick(); }, eyes.s.config.intervalSeconds * 1000);
+      timer?.unref?.();
+    }
+  }
+  const bind = (ctx) => {
+    stopTimer(); eyes?.dispose(); attempt = undefined; compacting = false; running = false;
+    const entries = ctx.sessionManager.getBranch();
+    const snapshot = [...entries].reverse().find((e) => e.type === "custom" && e.customType === EYES_ENTRY)?.data;
+    if (snapshot?.enabled || snapshot?.retired) retireLegacy?.();
+    const ownerCwd = path.resolve(ctx.cwd);
+    if (snapshot?.ownerCwd && snapshot.ownerCwd !== ownerCwd) {
+      eyes = undefined;
+      ctx.ui?.setStatus?.("ace-eyes", "eyes blocked: session belongs to another project cwd");
+      throw new Error("Eyes project owner mismatch; preserve this actor and use its original project session");
+    }
+    eyes = new Eyes({ snapshot, now,
+      save: (data) => pi.appendEntry(EYES_ENTRY, { ...data, ownerCwd }),
+      status: (state) => {
+        ctx.ui?.setStatus?.("ace-eyes", `eyes ${state.retired ? "retired" : state.breaker?.reason || (state.enabled ? "observing" : "off")} pending:${state.pending}`);
+        if (state.breaker || state.retired) stopTimer();
+      },
+      observe: (config) => observe(ctx.cwd, config),
+      canDeliver: () => !compacting && (ctx.isIdle() || running),
+      deliveryStatus: () => {
+        if (attempt?.accepted) return "accepted";
+        // sendUserMessage is a void wrapper. Busy/queued is uncertain, not
+        // acceptance or rejection. Idle without confirmation is uncertain:
+        // async input/auth preflight may still be running, so never blind-retry.
+        return compacting || !ctx.isIdle() || ctx.hasPendingMessages() ? "waiting" : "uncertain";
+      },
+      deliver: async (batch) => {
+        if (!ctx.model) return false;
+        const text = `[ace-eyes] Pending canonical HITL/deadline revisions: ${JSON.stringify(batch)}. ` +
+          "Read original events; adopt reports through ace-overseer process-reports and existing task/assignment gates. " +
+          "Reconcile uncertain effects; never repeat external actions on wake alone. After handling each exact revision, " +
+          "acknowledge with the ace_eyes tool (action ack, key, revision). Settlement alone is not acknowledgement.";
+        attempt = { text, accepted: false };
+        const result = pi.sendUserMessage(text, { deliverAs: "followUp" });
+        // Some hosts expose a promise, the standard ExtensionAPI exposes void.
+        // Neither completion nor void is proof of message consumption.
+        if (result?.then) await result;
+        return result !== false;
+      } });
+    if (eyes.s.enabled || eyes.s.retired) retireLegacy?.();
+    arm();
+    if (eyes.s.enabled) void eyes.tick();
+  };
+  pi.on("session_start", async (_event, ctx) => bind(ctx));
+  pi.on("session_tree", async (_event, ctx) => bind(ctx));
+  pi.on("agent_start", async () => { running = true; });
+  pi.on("agent_settled", async () => { running = false; });
+  pi.on("message_start", async (event) => {
+    if (event.message?.role !== "user" || !attempt) return;
+    const text = typeof event.message.content === "string" ? event.message.content :
+      (event.message.content || []).filter(part => part.type === "text").map(part => part.text).join("");
+    if (text === attempt.text) attempt.accepted = true;
+  });
+  pi.on("session_before_compact", async (event) => { if (event.reason === "manual") compacting = true; });
+  pi.on("session_compact", async () => { compacting = false; eyes?.persist(); });
+  pi.on("session_compact_failed", async () => { compacting = false; });
+  pi.on("session_shutdown", async () => { stopTimer(); eyes?.dispose(); });
+  pi.on("message_end", async (event) => {
+    const message = event.message;
+    if (message?.role === "assistant" && message.stopReason === "error") eyes?.quota(message.errorMessage);
+  });
+  pi.registerTool?.({
+    name: "ace_eyes", label: "Eyes acknowledgement", description: "Read pending semantic events or acknowledge an exact handled revision. Does not accept reports, authorize effects, start actors or reset quota. Use existing report/assignment owners first. Deadlines require an operation identity and revision; cancel when no longer active.",
+    parameters: { type: "object", properties: {
+      action: { type: "string", enum: ["status", "ack", "deadline", "cancel"] },
+      key: { type: "string" }, revision: { type: "string" }, at: { type: "integer" }
+    }, required: ["action"], additionalProperties: false },
+    execute: async (_id, args, _signal, _onUpdate, ctx) => {
+      if (!eyes) {
+        if (!ctx) throw new Error("Eyes session not initialized");
+        bind(ctx);
+      }
+      if (args.action === "ack") eyes.ack(args.key, args.revision);
+      else if (args.action === "deadline") eyes.deadline(args.key, args.at, args.revision);
+      else if (args.action === "cancel") eyes.cancelDeadline(args.key);
+      else if (args.action !== "status") throw new Error("Unknown eyes action");
+      // Do not send a second wake from inside the running model turn. The next
+      // observation delivers remaining coalesced revisions through the same owner.
+      const details = { ...eyes.summary(), pending: eyes.s.pending, deadlines: eyes.s.deadlines };
+      return { content: [{ type: "text", text: JSON.stringify(details) }], details };
+    }
+  });
+  pi.registerCommand("eyes", { description: "Event-driven HITL observation: start CONFIG | status | ack KEY REV | deadline NAME REVISION EPOCH_MS | cancel NAME | resume quota-verified | retire",
+    handler: async (args, ctx) => {
+      try {
+        if (!eyes) bind(ctx);
+        const [command, a, b, ...rest] = args.trim().split(/\s+/);
+        if (rest.length && command !== "deadline") throw new Error("Too many arguments");
+        switch (command) {
+          case "start": {
+            if (!a || b) throw new Error("Use eyes start CONFIG_JSON");
+            const config = JSON.parse(fs.readFileSync(path.resolve(ctx.cwd, a), "utf8"));
+            eyes.start(config); retireLegacy?.(); arm(); await eyes.tick(); break;
+          }
+          case "status": ctx.ui?.notify?.(JSON.stringify({ ...eyes.summary(), pending: eyes.s.pending, deadlines: eyes.s.deadlines }), "info"); break;
+          case "ack": eyes.ack(a, b); await eyes.tick(); break;
+          case "deadline":
+            if (rest.length !== 1) throw new Error("Deadline requires operation identity, revision and epoch milliseconds");
+            eyes.deadline(a, Number(rest[0]), b); await eyes.tick(); break;
+          case "cancel": eyes.cancelDeadline(a); break;
+          case "resume":
+            if (a !== "quota-verified" || b) throw new Error("Explicit owner verification required: eyes resume quota-verified");
+            await eyes.resume(); arm(); break;
+          case "retire": eyes.retire(); retireLegacy?.(); stopTimer(); break;
+          default: throw new Error("Unknown eyes command; use start, status, ack, deadline, cancel, resume or retire");
+        }
+      } catch (error) {
+        // Never echo process stdout/stderr: a failed native sync may carry private data.
+        ctx.ui?.notify?.(`Eyes operation refused (${error.name}); check configuration or /eyes status`, "error");
+      }
+    } });
+  return { active: () => Boolean(eyes?.s.enabled || eyes?.s.retired) };
+}

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

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const EYES_ENTRY = "ace-wake-eyes";
+export const defaults = { intervalSeconds: 30, maxEvents: 500, maxObservationsPerHour: 120, maxWakesPerHour: 20,
+  timeoutMs: 10000, maxErrors: 3, maxPending: 2000, scope: "current", recipient: "self", syncRoutes: [] };
+
+export function validateConfig(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input) ||
+      Object.keys(input).some(key => !(key in defaults))) throw new Error("Invalid eyes configuration");
+  const config = { ...defaults, ...input };
+  for (const [key, min, max] of [["intervalSeconds", 1, 3600], ["maxEvents", 1, 2000],
+    ["maxObservationsPerHour", 1, 3600], ["maxWakesPerHour", 1, 1000], ["timeoutMs", 100, 30000], ["maxErrors", 1, 10], ["maxPending", 1, 10000]]) {
+    if (!Number.isInteger(config[key]) || config[key] < min || config[key] > max) throw new Error(`Invalid ${key}`);
+  }
+  if (typeof config.recipient !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(config.recipient)) throw new Error("Invalid observer recipient");
+  if (!["current", "all"].includes(config.scope) || !Array.isArray(config.syncRoutes) || config.syncRoutes.length > 10 ||
+      config.syncRoutes.some((p) => typeof p !== "string" || !p.startsWith("/"))) throw new Error("Invalid eyes sources");
+  return config;
+}
+
+/** Observation/delivery bookkeeping in the existing Pi session, not a work
+ * queue. It never starts tasks or accepts reports on behalf of their owner. */
+export class Eyes {
+  constructor({ snapshot, save, observe, deliver, now = Date.now, status = () => {}, deliveryStatus = () => "accepted", canDeliver = () => true }) {
+    this.s = structuredClone(snapshot || { enabled: false, retired: false, config: defaults,
+      pending: {}, acknowledged: {}, deadlines: {}, breaker: null, errors: 0, window: null });
+    this.s.config = validateConfig(this.s.config);
+    for (const key of ["pending", "acknowledged", "deadlines"])
+      if (!this.s[key] || typeof this.s[key] !== "object" || Array.isArray(this.s[key])) throw new Error("Invalid persisted eyes state");
+    if (typeof this.s.enabled !== "boolean" || typeof this.s.retired !== "boolean" ||
+        !Number.isInteger(this.s.errors) || this.s.errors < 0) throw new Error("Invalid persisted eyes state");
+    this.save = save; this.observe = observe; this.deliver = deliver; this.now = now; this.status = status;
+    this.deliveryStatus = deliveryStatus; this.canDeliver = canDeliver;
+    this.busy = false; this.disposed = false;
+    // A process restart does not imply receipt acknowledgement. Reconcile the
+    // same pending revisions; business-effect idempotence remains with .5.4.
+    this.inflight = false;
+    this.sent = new Map();
+    this.generation = 0;
+  }
+  persist() { this.save(structuredClone(this.s)); this.status(this.summary()); }
+  summary() { return { enabled: this.s.enabled, retired: this.s.retired, pending: Object.keys(this.s.pending).length,
+    breaker: this.s.breaker, errors: this.s.errors, observations: this.s.window?.count || 0, wakes: this.s.window?.wakes || 0 }; }
+  start(config) {
+    if (this.s.retired) throw new Error("Retired actor cannot restart its eyes; hand off pending to its owner");
+    if (this.s.breaker) throw new Error("Resolve breaker with explicit resume first");
+    this.s.config = validateConfig(config); this.s.enabled = true; this.persist();
+  }
+  block(reason) {
+    if (!this.s.breaker) { this.s.breaker = { reason, at: this.now() }; this.persist(); }
+  }
+  async resume() {
+    if (this.s.retired) throw new Error("Retired actor cannot resume");
+    // Explicit operator action; check source/transport readiness without a model
+    // request. Quota availability must have been verified by the owner.
+    const result = await this.observe(this.s.config);
+    this.validate(result);
+    this.s.breaker = null; this.s.errors = 0; this.s.window = null; this.inflight = false;
+    this.s.enabled = true; this.persist();
+    await this.tick();
+  }
+  retire() { this.generation++; this.s.enabled = false; this.s.retired = true; this.persist(); }
+  dispose() { this.disposed = true; this.generation++; }
+  quota(message) {
+    if (/quota|insufficient.?(?:credit|balance)|billing.?limit|budget.?exceed|usage.?limit|rate.?limit|\b429\b/i.test(String(message))) this.block("quota-or-budget");
+  }
+  deadline(name, at, operationRevision) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name) || !Number.isSafeInteger(at) || at < 0 || typeof operationRevision !== "string" || !/^[a-zA-Z0-9._:-]{1,128}$/.test(operationRevision)) throw new Error("Invalid deadline");
+    const key = `deadline:${name}`;
+    delete this.s.pending[key];
+    this.sent.delete(key); this.inflight = this.sent.size > 0;
+    this.s.deadlines[name] = { at, operationRevision }; this.persist();
+  }
+  cancelDeadline(name) {
+    delete this.s.deadlines[name]; delete this.s.pending[`deadline:${name}`];
+    this.sent.delete(`deadline:${name}`); this.inflight = this.sent.size > 0; this.persist();
+  }
+  ack(key, revision) {
+    if (this.s.pending[key]?.revision !== revision && this.sent.get(key) !== revision)
+      throw new Error("Ack does not match an observed pending or delivered revision");
+    this.s.acknowledged[key] = revision;
+    if (this.s.pending[key]?.revision === revision) delete this.s.pending[key];
+    this.sent.delete(key);
+    this.inflight = this.sent.size > 0; this.persist();
+  }
+  validate(result) {
+    if (result?.schema !== "ace.hitl.observation/v1" || !Array.isArray(result.events) || result.events.length > this.s.config.maxEvents)
+      throw new Error("Invalid or over-budget HITL observation");
+    if (result.settled !== undefined && !Array.isArray(result.settled)) throw new Error("Invalid settlement projection");
+    const rows = [...result.events, ...(result.settled || [])];
+    if (rows.length > this.s.config.maxEvents) throw new Error("Over-budget projection");
+    const keys = new Set();
+    for (const event of rows) {
+      if (!/^[a-f0-9]{64}$/.test(event.key) || !/^[a-f0-9]{64}$/.test(event.revision) ||
+          typeof event.id !== "string" || !/^[a-z0-9_-]{1,64}$/i.test(event.id) || keys.has(event.key)) throw new Error("Invalid event identity");
+      keys.add(event.key);
+    }
+  }
+  async tick() {
+    if (this.busy || this.disposed || !this.s.enabled || this.s.retired || this.s.breaker) return;
+    const now = this.now();
+    if (!this.s.window || now - this.s.window.start >= 3600000) this.s.window = { start: now, count: 0, wakes: 0 };
+    if (this.s.window.count >= this.s.config.maxObservationsPerHour) { this.block("observation-budget"); return; }
+    this.s.window.count++; this.persist(); // Budget survives restart too.
+    this.busy = true;
+    const generation = this.generation;
+    try {
+      const result = await this.observe(this.s.config);
+      if (generation !== this.generation || this.disposed) return;
+      this.validate(result);
+      for (const e of result.settled || []) {
+        this.s.acknowledged[e.key] = e.revision;
+        if (this.s.pending[e.key]?.revision === e.revision) delete this.s.pending[e.key];
+        this.sent.delete(e.key);
+      }
+      if (this.inflight && this.sent.size === 0) this.inflight = false;
+      for (const e of result.events) {
+        if (this.s.acknowledged[e.key] !== e.revision) this.s.pending[e.key] = { id: e.id, revision: e.revision };
+      }
+      for (const [name, deadline] of Object.entries(this.s.deadlines)) {
+        const { at, operationRevision } = deadline;
+        const key = `deadline:${name}`, revision = hash([name, at, operationRevision]);
+        if (now >= at && this.s.acknowledged[key] !== revision) this.s.pending[key] = { id: name, revision };
+      }
+      if (Object.keys(this.s.pending).length + Object.keys(this.s.acknowledged).length > this.s.config.maxPending) {
+        this.block("retention-budget"); return;
+      }
+      this.persist();
+      if (this.inflight && this.deliveryStatus() === "uncertain") {
+        this.block("notification-unconfirmed"); return;
+      }
+      if (!this.inflight && !this.s.breaker && Object.keys(this.s.pending).length && this.canDeliver()) {
+        // Retain identities before attempting delivery. A rejected send leaves
+        // pending intact; acceptance by Pi is not application acknowledgement.
+        if ((this.s.window.wakes || 0) >= this.s.config.maxWakesPerHour) { this.block("wake-budget"); return; }
+        this.s.window.wakes = (this.s.window.wakes || 0) + 1;
+        this.persist(); // Includes uncertain notification attempts, never token billing.
+        const batch = Object.entries(this.s.pending).slice(0, 20);
+        this.inflight = Boolean(await this.deliver(batch));
+        if (this.inflight) this.sent = new Map(batch.map(([key, value]) => [key, value.revision]));
+        if (!this.inflight) throw new Error("wake delivery refused");
+      }
+      if (this.s.errors && (!this.inflight || this.deliveryStatus() === "accepted")) { this.s.errors = 0; this.persist(); }
+    } catch {
+      this.s.errors++; this.persist();
+      if (this.s.errors >= this.s.config.maxErrors) this.block("observation-or-delivery-failure");
+    } finally { this.busy = false; }
+  }
+}

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