ace-wake 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c70984a4740dce94a78731fd0852370b10a23a4b05e43286450ad83b7121bad3
+  data.tar.gz: 757c46a35a41081cfc85666681326a0275d127d8d2490c6470e6e8dbb1db4fc6
+SHA512:
+  metadata.gz: bd19ae88ac86295da911337b06c20aa07f6c282fc14cc5f900527b93fb3b2c6989083789863565f49af0d17e77faee14b543a90995c514a4236ab33710f9ba40
+  data.tar.gz: 41b39de4a48e8dfc036774424161bcbc416aa25f36090daa7d181bb021223e2b2a5e1d1b863c810f94309c5adb03760821400a6bea502bdc008729746ab11e02

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-30
+
+First publishable release of the ace-wake asset package (task family
+8xs.t.pu0).
+
+### Added
+
+- Publishable gem packaging: `ace-wake.gemspec`, `lib/ace/wake/version.rb`,
+  changelog, Rakefile.
+- Extension source under `handbook/extensions/ace-wake/` — the standard
+  handbook projection tree — as the single copy (task 8xs.t.pu0.0);
+  deployment converged from the gem (`ace-handbook sync --provider pi`,
+  `ace-lab install` extension projections) instead of the manual host copy.
+- Minitest wrapper executing the JavaScript suite (`node --test`) so
+  `ace-test ace-wake` runs the real extension tests.
+- Zero-idle window coverage (8xs.t.pu0.f): 30 minutes of healthy silence
+  consume zero model turns while technical polling is counted separately.
+- Secret-ask coverage: a redacted watch wakes with the case reference only.
+
+### Changed
+
+- Eyes and user subscriptions coexist (task 8xs.t.pu0.2): `/eyes start` no
+  longer retires active loops/watches, and `/watch add`/`/loop add` are no
+  longer rejected while eyes observes — one shared delivery infrastructure,
+  no competing observation ownership.
+- Secret asks wake with the reference only (task 8xs.t.pu0.9): a watch armed
+  with `redact` (secret HITL cases) strips the delta's content excerpt, so a
+  delivered OTP never passes through the model; the message points at the
+  secure channel. Normal asks still name the answer.
+
+### Fixed
+
+- macOS environment fixture: watch delta path assertions compare against
+  the canonical realpath of the watched case file (`/var` vs
+  `/private/var` tmpdir).

data/README.md

@@ -0,0 +1,96 @@
+# ace-wake
+
+Pi agent extension: `/loop` timers and `/watch` file subscriptions that wake
+idle agents with bounded, coalesced wake messages through `sendUserMessage`
+only. Definitions survive reload/restart with exactly-once re-registration;
+there is no cron, daemon, heartbeat, or delivery-queue engine.
+
+## Provenance
+
+This directory is the canonical source of the ace-wake extension. It was
+developed and tested inside `ace-handbook-integration-pi/handbook/extensions/ace-wake/`
+and moved here (verbatim, with its JavaScript test suite) as its top-level
+home. The deployed copy at `~/.pi/agent/extensions/ace-wake` is root-owned,
+dated 2026-10-16, and is a STALE generation of this source (no eyes, no
+worktree inbox discovery, no watch deltas); it was intentionally left
+untouched.
+
+This package is a publishable gem (task 8xs.t.pu0.0). The extension source
+lives at `handbook/extensions/ace-wake/` (single copy) and ships in the
+`ace-wake` gem; deployment is converged, not manual:
+
+- `ace-handbook sync --provider pi` projects it into a project's
+  `.pi/extensions` (the pi provider manifest declares
+  `extensions_package: ace-wake`);
+- the `ace-lab` installer projects it from the EXACT installed gem version
+  into each manifest-declared extension directory (`gemset.extensions`),
+  reporting the loaded version and any restart need.
+
+## Mount-aware poll fallback
+
+`/lab/state/hitl-address/ace` (the HITL transport folder) is a FUSE/virtiofs
+mount where inotify event delivery is unreliable: a registered `/watch` never
+fires there. The watch port (`wake/watch-subscription.js`) classifies every
+watched target through a `statfsFn` port (`node:fs.statfsSync` by default;
+string fstype or Linux `f_type` magic number) and, for targets on unreliable
+mounts (virtiofs, fuse, fuseblk, fusectl), runs a 2.5 s reconcile timer that
+re-stats the aggregate fingerprint and wakes on change. `fs.watch` stays
+primary everywhere else; a failing or unsupported statfs keeps `fs.watch`
+primary rather than failing the watch.
+
+## Ask bridge (the `ace-hitl ask` contract)
+
+`ace-hitl ask` is create + send + arm + END TURN: it never blocks and never
+polls. The asking agent's Ruby process drops one wake-request file into
+`<session cwd>/.ace-local/hitl/wake-requests/<case id>.json`:
+
+```json
+{"schema": "ace.wake.ask/v1", "kind": "ask", "case_id": "8xhkep",
+ "case_path": "/abs/worktree/.ace-local/hitl/8xhkep-slug/8xhkep-slug.hitl.s.md"}
+```
+
+The extension consumes that folder WITHOUT any agent turn activity
+(`wake/ask-bridge.js`, wired in `index.js` as `startAskBridge`): a small
+internal watch port anchors on the folder — or, while it does not exist yet
+(the first `ask` creates it), on its nearest existing ancestor and promotes
+itself once it appears — and its reconcile passes arm one scoped registry
+watch named `ask-<case id>` on the case file, then consume the request.
+When the answer lands (the Captain's reply flows through the transport into
+the case file), the case file's fingerprint changes and the wake fires with
+the `## Answer` section as its excerpt, so the wake carries the answer
+content; the agent acts immediately on wake. Arming is idempotent (an
+already-armed case consumes a stale request without re-arming, which would
+reset the baseline and could swallow a landed answer), an unreadable case
+file leaves the request pending, and the armed watch persists through
+reload/restart like any registry watch — nothing expires on the asker side.
+On unreliable mounts the armed watch fires only through the poll fallback
+above; that fallback is what makes ask work end to end there.
+
+## Tests
+
+```sh
+node --test test/*.test.mjs
+```
+
+Run from this directory. The glob covers the deterministic unit/acceptance
+suites only; the env-gated real-runtime acceptance in `test/acceptance/` is
+excluded and skipped when its environment is missing.
+
+Two environment caveats:
+
+- `test/report-wake-worktree.test.mjs` spawns this clone's `bin/ace-hitl`,
+  which needs the repository's bundler setup and `ACE_TOOLCHAIN=auto` (the
+  repo dev default). An inherited `ACE_TOOLCHAIN=installed` shell makes
+  those two tests fail.
+- `test/acceptance/pi-sdk-acceptance.test.mjs` runs the extension inside the
+  REAL Pi SDK runtime. It needs `PI_PKG_ROOT` (the pi-coding-agent package
+  directory) and `EXT_PATH` (the published entrypoint
+  `handbook/extensions/ace-wake/index.js`), and is normally driven by the
+  ace-handbook-integration-pi feat harness
+  (`bin/ace-test ace-handbook-integration-pi feat`):
+
+  ```sh
+  PI_PKG_ROOT="$(npm root -g)/@earendil-works/pi-coding-agent" \
+    EXT_PATH="$PWD/handbook/extensions/ace-wake/index.js" \
+    node --test test/acceptance/pi-sdk-acceptance.test.mjs
+  ```

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

@@ -0,0 +1,457 @@
+// 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 * as nodePath from "node:path";
+
+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";
+import { createWatchPort, nodeReadFn, nodeStatFn, nodeStatfsFn, nodeWatchFactory } from "./wake/watch-subscription.js";
+import { armPendingAskWatches, requestsDirFor } from "./wake/ask-bridge.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;
+
+  /** The ask bridge's own watch port (one per session, replaced on re-bind). */
+  let askBridgePort;
+
+  let eyes;
+  const getRuntime = () => runtime;
+  const bindRuntime = (ctx) => {
+    runtime?.registry.dispose();
+    askBridgePort?.stopAll();
+    runtime = { registry: createRegistry(pi, ctx, ports) };
+    runtime.registry.reconcile();
+    askBridgePort = startAskBridge(ctx, ports, runtime.registry);
+  };
+
+  // Eyes and user subscriptions coexist by contract (8xs.t.pu0.2):
+  // eyes owns STANDING observation of canonical HITL events, the
+  // registry owns /loop timers and /watch file subscriptions, and both
+  // deliver through the same sendUserMessage infrastructure. Eyes never
+  // rejects /watch (or /loop) add and never removes an active
+  // subscription — there is no competing observation ownership here.
+  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);
+  });
+
+  eyes = registerEyes(pi, ports.eyes);
+
+  // 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;
+    askBridgePort?.stopAll();
+    askBridgePort = 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();
+  }
+}
+
+/**
+ * The ask bridge: consume `ace-hitl ask` wake requests without any agent
+ * turn activity. The bridge owns a small watch port anchored on the
+ * session's wake-request folder — or, while that folder does not exist yet
+ * (a fresh worktree; the first `ask` creates it), on its nearest existing
+ * ancestor, promoted to the real folder as soon as it appears. Its
+ * reconcile passes (registration, the delayed registration-gap reconcile,
+ * folder events — and the poll fallback on unreliable mounts) arm one
+ * scoped `ask-<case id>` watch per pending request through the registry,
+ * which owns delivery, coalescing, and persistence for the wakes.
+ *
+ * @param {object} ctx Session context (cwd selects the request folder).
+ * @param {object} ports Injectable host ports (same surface as the registry).
+ * @param {WakeRegistry} registry
+ * @returns {{stopAll: () => void}}
+ */
+function startAskBridge(ctx, ports, registry) {
+  const requestsDir = requestsDirFor(ctx.cwd);
+  const statFn = ports.statFn ?? nodeStatFn;
+  const armPass = () => {
+    try {
+      armPendingAskWatches({ requestsDir, registry });
+    } catch {
+      // Arming must never break the extension host.
+    }
+  };
+  const bridgePort = createWatchPort({
+    watchFactory: ports.watchFactory ?? nodeWatchFactory,
+    statFn,
+    statfsFn: ports.statfsFn ?? nodeStatfsFn,
+    pollIntervalMs: ports.pollIntervalMs,
+    baseDir: ctx.cwd,
+  });
+  let anchoredTo;
+  const promote = () => {
+    if (anchoredTo === requestsDir) {
+      return;
+    }
+    try {
+      statFn(requestsDir);
+    } catch {
+      return; // Still absent: the ancestor anchor remains the channel.
+    }
+    bridgePort.stop("__ace_ask_requests");
+    startAnchor();
+    // Mirror the registration-gap posture: a request landing between the
+    // anchor switch and the new watcher's effectiveness re-arms once.
+    armPass();
+  };
+  const onEvent = () => {
+    armPass();
+    promote();
+    return { delivered: true };
+  };
+  function startAnchor() {
+    let candidate = requestsDir;
+    let attempts = 0;
+    for (;;) {
+      try {
+        statFn(candidate);
+        break;
+      } catch {
+        if (attempts >= 6 || candidate === nodePath.dirname(candidate)) {
+          return false; // Nothing watchable (synthetic host): arm pass only.
+        }
+        attempts += 1;
+        candidate = nodePath.dirname(candidate);
+      }
+    }
+    try {
+      bridgePort.start(
+        { kind: "watch", name: "__ace_ask_requests", path: candidate, message: "" },
+        onEvent,
+      );
+      anchoredTo = candidate;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  startAnchor();
+  // Requests that landed while the session was down arm at startup; the
+  // port's registration-gap reconcile covers the arming race.
+  armPass();
+  return bridgePort;
+}
+
+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,
+      readFn: ports.readFn ?? nodeReadFn,
+      // Mount classifier for the poll fallback (virtiofs/fuse targets are
+      // deaf to fs.watch and reconcile on a timer instead); injectable for
+      // deterministic tests.
+      statfsFn: ports.statfsFn ?? nodeStatfsFn,
+      pollIntervalMs: ports.pollIntervalMs,
+      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"
+}