pi-insomnia 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-09
+
+### Fixed
+
+- Restrict the footer spinner to TUI mode while preserving sleep-inhibitor lifecycle in other modes.
+
+### Changed
+
+- Update the shared Pi development and contract-test baseline to 1.1.0; require Node.js >=22.19.0 to match the host runtime. Pi remains a host-supplied peer dependency.
+- Share install telemetry mechanics through `@mocito/install-telemetry` while preserving Pi-specific settings and state paths.
+
+### Fixed
+
+- Let `enableInstallTelemetry: false` override an enabled `PI_TELEMETRY` environment flag.
+
+## [0.1.3] - 2026-07-17
+
+### Fixed
+
+- Keep macOS sleep inhibition active across automatic retries, compaction retries, and queued follow-up work until Pi emits `agent_settled`.
+
 ## [0.1.2] - 2026-07-01
 
 ### Changed
@@ -14,7 +35,11 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [0.1.1] - 2026-06-09
 
-## [0.1.0] - TBD
+### Changed
+
+- Replace the static footer icon with an animated Braille spinner while sleep inhibition is active.
+
+## [0.1.0] - 2026-06-08
 
 ### Added
 

package/README.md

@@ -1,18 +1,22 @@
 # pi-insomnia
 
-A source-distributed [Pi](https://pi.dev) package that prevents macOS idle sleep while the Pi agent is working.
+Keep long-running [Pi](https://pi.dev) tasks alive when you step away from your Mac.
+
+`pi-insomnia` automatically prevents idle system sleep while Pi is working, then releases the sleep assertion as soon as the agent fully settles. No commands or manual activation needed.
 
 > [!WARNING]
 > Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.
 
 ## Features
 
-- Automatically starts a macOS sleep assertion when a Pi agent run starts.
-- Automatically releases the assertion when the agent run ends.
-- Cleans up on Pi session shutdown, reloads, and quits.
-- Uses the macOS built-in `/usr/bin/caffeinate` command; no third-party runtime dependency is required.
-- Shows a small `☕ sleep inhibited` footer status while active in UI modes.
-- No slash commands, tools, or manual activation needed.
+- **Automatic protection** — inhibit idle sleep only while Pi has active work.
+- **Full-run awareness** — stay awake through retries, compaction, and queued follow-up work, then release when Pi settles.
+- **Zero setup** — use macOS built-in `caffeinate`; no commands, configuration, or third-party runtime dependency.
+- **Visible state** — show a small braille spinner with `sleep inhibited` in the TUI footer while active.
+- **Safe cleanup** — release assertions on session shutdown, reload, and quit.
+
+The spinner uses palette-neutral text and does not run in print, JSON or RPC
+mode. Sleep inhibition itself follows the same active-work lifecycle in all modes.
 
 ## Platform support
 
@@ -24,7 +28,7 @@ On macOS, the extension launches:
 /usr/bin/caffeinate -i -w <pi-pid>
 ```
 
-`-i` prevents idle system sleep while the process is running. `-w <pi-pid>` also ties the assertion to the Pi process so the helper exits if Pi exits unexpectedly. The extension still explicitly terminates the helper when the agent becomes idle.
+`-i` prevents idle system sleep while the process is running. `-w <pi-pid>` also ties the assertion to the Pi process so the helper exits if Pi exits unexpectedly. The extension still explicitly terminates the helper when Pi becomes fully idle after any automatic retries, compaction retries, or queued follow-up work.
 
 ## Installation
 

package/SECURITY.md

@@ -25,4 +25,4 @@ Do not commit API keys, tokens, credentials, local settings, or machine-specific
 
 On macOS, the extension starts the system-provided `/usr/bin/caffeinate` helper while the Pi agent is working. It does not request elevated privileges, pass user prompts to the helper, or run shell commands. The helper is started directly with fixed arguments and is terminated when the agent becomes idle or the Pi session shuts down.
 
-On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, file paths, config values, environment variables, or API keys.
+On startup, `@mocito/install-telemetry` sends a best-effort install/update telemetry ping to the configured telemetry endpoint once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, file paths, config values, environment variables, or API keys.

package/extensions/index.ts

@@ -12,12 +12,12 @@ let spinnerTimer: ReturnType<typeof setInterval> | undefined;
 let spinnerFrame = 0;
 
 function setStatus(ctx: ExtensionContext, text: string | undefined): void {
-  if (!ctx.hasUI) return;
+  if (ctx.mode !== "tui") return;
   ctx.ui.setStatus(STATUS_KEY, text);
 }
 
 function startSpinner(ctx: ExtensionContext): void {
-  if (!ctx.hasUI || spinnerTimer) return;
+  if (ctx.mode !== "tui" || spinnerTimer) return;
   spinnerFrame = 0;
   setStatus(ctx, `${SPINNER_FRAMES[0]} sleep inhibited`);
   spinnerTimer = setInterval(() => {
@@ -34,16 +34,17 @@ function stopSpinner(ctx: ExtensionContext): void {
   setStatus(ctx, undefined);
 }
 
-export default function piInsomnia(pi: ExtensionAPI) {
+export default function piInsomnia(
+  pi: ExtensionAPI,
+  inhibitor = new MacSleepInhibitor(),
+) {
   reportInstallTelemetry();
 
-  const inhibitor = new MacSleepInhibitor();
-
   pi.on("agent_start", async (_event, ctx) => {
     if (inhibitor.acquire()) startSpinner(ctx);
   });
 
-  pi.on("agent_end", async (_event, ctx) => {
+  pi.on("agent_settled", async (_event, ctx) => {
     inhibitor.release();
     if (!inhibitor.isInhibiting) stopSpinner(ctx);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-insomnia",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Prevent macOS idle sleep while Pi agents are working.",
   "type": "module",
   "license": "MIT",
@@ -45,20 +45,25 @@
   "scripts": {
     "check": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "@types/node": "^25.9.3",
-    "typescript": "^6.0.3"
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "^26.6.3",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@mocito/install-telemetry": "0.1.1"
   }
 }

package/src/install-telemetry.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const PACKAGE_NAME = "pi-insomnia";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
 const CI_ENVIRONMENT_VARIABLES = [
   "APPVEYOR",
   "BITBUCKET_BUILD_NUMBER",
@@ -24,10 +23,6 @@ const CI_ENVIRONMENT_VARIABLES = [
   "VERCEL",
 ];
 
-interface InstallTelemetryState {
-  lastReportedVersion?: string;
-}
-
 interface PiSettingsDocument {
   enableInstallTelemetry?: unknown;
 }
@@ -51,18 +46,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isCiEnvironment(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return true;
-  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
-}
-
-function isInstallTelemetryEnabled(): boolean {
-  if (isCiEnvironment()) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as PiSettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {
@@ -70,35 +62,16 @@ function getPackageVersion(): string {
   return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
-}
-
-async function reportInstallTelemetryAsync(): Promise<void> {
+export function reportInstallTelemetry(): void {
   try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const extensionsDir = join(getAgentDir(), "extensions");
-    const statePath = join(extensionsDir, "pi-insomnia-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(extensionsDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "pi-insomnia-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
   } catch {
-    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+    // Best-effort telemetry: ignore local policy and filesystem failures.
   }
 }
-
-export function reportInstallTelemetry(): void {
-  void reportInstallTelemetryAsync();
-}

package/src/sleep-inhibitor.ts

@@ -13,7 +13,7 @@ export class MacSleepInhibitor {
   private readonly pid: number;
   private readonly caffeinatePath: string;
   private child: ChildProcess | undefined;
-  private activeRequests = 0;
+  private active = false;
 
   constructor(options: MacSleepInhibitorOptions = {}) {
     this.platform = options.platform ?? process.platform;
@@ -26,7 +26,7 @@ export class MacSleepInhibitor {
   }
 
   get isActive(): boolean {
-    return this.activeRequests > 0;
+    return this.active;
   }
 
   get isInhibiting(): boolean {
@@ -36,7 +36,7 @@ export class MacSleepInhibitor {
   acquire(): boolean {
     if (!this.isSupported) return false;
 
-    this.activeRequests += 1;
+    this.active = true;
     this.start();
     return this.isInhibiting;
   }
@@ -44,12 +44,12 @@ export class MacSleepInhibitor {
   release(): void {
     if (!this.isSupported) return;
 
-    if (this.activeRequests > 0) this.activeRequests -= 1;
-    if (this.activeRequests === 0) this.stop();
+    this.active = false;
+    this.stop();
   }
 
   forceStop(): void {
-    this.activeRequests = 0;
+    this.active = false;
     this.stop();
   }