ace-wake 0.1.0

data/handbook/extensions/ace-wake/wake/ask-bridge.js

@@ -0,0 +1,102 @@
+import * as nodeFs from "node:fs";
+import * as nodePath from "node:path";
+
+// Contract with the ace-hitl CLI (`ace-hitl ask`): the asker's Ruby process
+// drops one request file per asked case into
+// `<cwd>/.ace-local/hitl/wake-requests/<case id>.json`; this bridge consumes
+// the folder through the extension's own reconcile pass and arms one scoped
+// watch on the case file. When the answer lands, the case file's fingerprint
+// changes and the wake carries the answer content (the excerpt prefers the
+// `## Answer` section). The request file is consumed once the watch is armed;
+// the armed watch itself persists through the registry (reload/restart safe),
+// and nothing expires on the asker side.
+export const ASK_REQUEST_SCHEMA = "ace.wake.ask/v1";
+
+/**
+ * The wake-request folder for one agent session.
+ *
+ * @param {string} cwd Session working directory (the asking agent's worktree).
+ * @returns {string}
+ */
+export function requestsDirFor(cwd) {
+  return nodePath.join(cwd, ".ace-local", "hitl", "wake-requests");
+}
+
+/**
+ * Arm one scoped `ask-<case id>` watch per pending wake request. Idempotent:
+ * a request whose watch is already armed (a previous pass, a reload, or a
+ * restart re-registration) is consumed without re-arming, because a restart
+ * of a watch would reset its baseline fingerprint and could swallow an
+ * answer that already landed. A request whose case file is unreadable stays
+ * pending for the next pass. Torn or partial request files (never produced
+ * by the atomic ask writer, but never trusted either) stay untouched.
+ *
+ * @param {{requestsDir: string, registry: import("./wake-registry.js").WakeRegistry}} inputs
+ * @returns {number} Number of watches newly armed.
+ */
+export function armPendingAskWatches({ requestsDir, registry }) {
+  let entries;
+  try {
+    entries = nodeFs.readdirSync(requestsDir);
+  } catch {
+    // No requests folder (or unreadable): nothing to arm.
+    return 0;
+  }
+  let armed = 0;
+  for (const name of entries.filter((entry) => entry.endsWith(".json")).sort()) {
+    const requestPath = nodePath.join(requestsDir, name);
+    let request;
+    try {
+      request = JSON.parse(nodeFs.readFileSync(requestPath, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!isAskRequest(request)) {
+      continue;
+    }
+    const watchName = `ask-${request.case_id}`;
+    if (registry.list().some((entry) => entry.kind === "watch" && entry.name === watchName)) {
+      consumeRequest(requestPath);
+      continue;
+    }
+    try {
+      registry.addWatch({
+        name: watchName,
+        path: request.case_path,
+        message: request.secret
+          ? `HITL answer for case ${request.case_id}: the value was delivered to the case file; read it through the secure channel (never this wake)`
+          : `HITL answer for case ${request.case_id}: run /continue-work only when this wake names the answer`,
+        redact: request.secret === true,
+      });
+    } catch {
+      // The case file is unreadable or the watch is invalid: keep the
+      // request pending for the next reconcile pass.
+      continue;
+    }
+    consumeRequest(requestPath);
+    armed += 1;
+  }
+  return armed;
+}
+
+/**
+ * @param {string} path
+ */
+function consumeRequest(path) {
+  try {
+    nodeFs.unlinkSync(path);
+  } catch {
+    // Already consumed by a concurrent pass.
+  }
+}
+
+/**
+ * @param {unknown} request
+ * @returns {request is {schema: string, kind: string, case_id: string, case_path: string}}
+ */
+function isAskRequest(request) {
+  return typeof request === "object" && request !== null &&
+    request.schema === ASK_REQUEST_SCHEMA && request.kind === "ask" &&
+    typeof request.case_id === "string" && request.case_id.length > 0 &&
+    typeof request.case_path === "string" && request.case_path.length > 0;
+}

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

@@ -0,0 +1,147 @@
+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 source of config.syncRoutes) {
+    // One source per project: each entry names the project hitl config and,
+    // when several hermes_native routes exist there, the route to reconcile.
+    const argv = ["sync", "--config", source.config];
+    if (source.route !== undefined) argv.push("--route", source.route);
+    const { stdout } = await execute("ace-hitl-hermes", argv, 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, { 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;
+    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;
+      } });
+    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); 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(); 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,152 @@
+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");
+  const validSource = (p) => typeof p === "object" && p !== null && typeof p.config === "string" && p.config.startsWith("/") &&
+    (p.route === undefined || (typeof p.route === "string" && /^[a-zA-Z0-9_-]{1,64}$/.test(p.route)));
+  if (!["current", "all"].includes(config.scope) || !Array.isArray(config.syncRoutes) || config.syncRoutes.length > 10 ||
+      config.syncRoutes.some((p) => !validSource(p))) 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" });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Loop subscription port owning native interval handles.
+ *
+ * Each start schedules an in-process interval from "now". After disposal and
+ * re-registration (reload, restart, reconcile) the next tick is a full
+ * interval away: no missed or catch-up ticks are ever replayed.
+ *
+ * @param {object} ports
+ * @param {(callback: () => void, ms: number) => unknown} ports.setIntervalFn
+ * @param {(handle: unknown) => void} ports.clearIntervalFn
+ * @returns {{
+ *   start: (definition: import("./types.js").LoopDefinition, onTick: (definition: import("./types.js").LoopDefinition) => void) => void,
+ *   stop: (name: string) => void,
+ *   stopAll: () => void,
+ *   errorOf: (name: string) => string | undefined,
+ *   activeCount: () => number,
+ * }}
+ */
+export function createLoopPort({ setIntervalFn, clearIntervalFn }) {
+  /** @type {Map<string, unknown>} */
+  const handles = new Map();
+
+  return {
+    start(definition, onTick) {
+      stopExisting(definition.name);
+      const milliseconds = definition.intervalSeconds * 1000;
+      const handle = setIntervalFn(() => onTick(definition), milliseconds);
+      // Never hold the host process open on the extension's behalf.
+      handle?.unref?.();
+      handles.set(definition.name, handle);
+    },
+
+    stop(name) {
+      stopExisting(name);
+    },
+
+    stopAll() {
+      for (const handle of handles.values()) {
+        clearIntervalFn(handle);
+      }
+      handles.clear();
+    },
+
+    errorOf() {
+      // Intervals do not produce runtime errors; the clock either runs or the
+      // process is gone.
+      return undefined;
+    },
+
+    activeCount() {
+      return handles.size;
+    },
+  };
+
+  function stopExisting(name) {
+    const handle = handles.get(name);
+    if (handle !== undefined) {
+      clearIntervalFn(handle);
+      handles.delete(name);
+    }
+  }
+}