@plannotator/pi-extension 0.28.42 → 0.28.43

package/generated/ai/providers/codex-app-server.ts

@@ -57,6 +57,13 @@ const IDLE_TIMEOUT_MS = 10 * 60_000;
 /** Reject a JSON-RPC request that gets no response in this long (RPC acks are
  *  fast — turn output streams via notifications, not the turn/start response). */
 const RPC_TIMEOUT_MS = 30_000;
+/**
+ * The longest unfinished stdout line, in characters. One line can hold a whole `thread/resume` answer or a command's
+ * `aggregatedOutput`, and neither has a size Plannotator knows, so this stops a runaway and not a long message.
+ */
+export const CODEX_LINE_MAX = 256 * 1024 * 1024;
+/** How long a Codex gets to stop on SIGTERM before SIGKILL. */
+const CODEX_STOP_GRACE_MS = 2_000;
 /** Model discovery must not gate the AI panel: cap its handshake + model/list
  *  RPCs much shorter than RPC_TIMEOUT_MS so a codex that's installed but not
  *  logged in (or otherwise unresponsive) falls back to the static model list
@@ -297,10 +304,25 @@ export function mapApprovalRequest(
 // JSON-RPC over stdio (bidirectional: responses, notifications, server requests)
 // ---------------------------------------------------------------------------
 
+/** SIGTERM, then SIGKILL for a Codex that ignores it. On Windows the tree kill is already forced. */
+function stopChild(proc: ChildProcess, now = false): void {
+  if (killWindowsProcessTree(proc.pid)) return;
+  if (now) {
+    proc.kill("SIGKILL");
+    return;
+  }
+  proc.kill();
+  const timer = setTimeout(() => {
+    if (proc.exitCode === null && proc.signalCode === null) proc.kill("SIGKILL");
+  }, CODEX_STOP_GRACE_MS);
+  timer.unref();
+  proc.once("exit", () => clearTimeout(timer));
+}
+
 type NotificationListener =(notification: { method: string; params: RpcMessage }) => void;
 type RequestHandler = (method: string, id: string | number, params: RpcMessage) => void;
 
-class CodexAppServerProcess {
+export class CodexAppServerProcess {
   private proc: ChildProcess | null = null;
   private listeners: NotificationListener[] = [];
   private requestHandlers: RequestHandler[] = [];
@@ -318,11 +340,15 @@ class CodexAppServerProcess {
   /** The initialize response's `userAgent` ("plannotator/<codex version> (…)"). */
   userAgent: string | undefined;
 
+  /** `lineMax`: past this many characters with no newline, the process is failed and stopped. */
+  constructor(private readonly lineMax: number = CODEX_LINE_MAX) {}
+
   /** Spawn + JSON-RPC initialize handshake, once. `initTimeoutMs` bounds the
-   *  initialize wait (model discovery passes a short value so it can't hang). */
-  start(codexPath: string, cwd: string, initTimeoutMs?: number): Promise<void> {
+   *  initialize wait (model discovery passes a short value so it can't hang).
+   *  `env`: the environment Codex runs in and whose config it reads; default this process's. */
+  start(codexPath: string, cwd: string, initTimeoutMs?: number, env?: Readonly<Record<string, string | undefined>>): Promise<void> {
     if (!this.startPromise) {
-      this.startPromise = this.doStart(codexPath, cwd, initTimeoutMs).catch((err) => {
+      this.startPromise = this.doStart(codexPath, cwd, initTimeoutMs, env).catch((err) => {
         this.startPromise = null;
         throw err;
       });
@@ -330,9 +356,9 @@ class CodexAppServerProcess {
     return this.startPromise;
   }
 
-  private async doStart(codexPath: string, cwd: string, initTimeoutMs?: number): Promise<void> {
+  private async doStart(codexPath: string, cwd: string, initTimeoutMs?: number, env: Readonly<Record<string, string | undefined>> = process.env): Promise<void> {
     const commandPath = resolveWindowsCommandShim(codexPath);
-    const appServerArgs = [...codexAskAiConfigArgs(readCodexConfigTexts(cwd)), "app-server"];
+    const appServerArgs = [...codexAskAiConfigArgs(readCodexConfigTexts(cwd, env)), "app-server"];
     const command =
       buildWindowsCommandScriptSpawnCommand(commandPath, appServerArgs) ?? [
         commandPath,
@@ -346,7 +372,7 @@ class CodexAppServerProcess {
       // stderr pipe deadlocks the child once its buffer fills. The env turns
       // Plannotator's integration off in this Codex (ask-ai-env.ts): its hooks
       // read the marker; the Inbox MCP server is off by the `-c` overrides.
-      proc = spawn(file, args, { cwd, env: askAiChildEnv(), stdio: ["pipe", "pipe", "ignore"] });
+      proc = spawn(file, args, { cwd, env: askAiChildEnv(env), stdio: ["pipe", "pipe", "ignore"] });
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       this.handleProcessEnd(error);
@@ -412,7 +438,7 @@ class CodexAppServerProcess {
     this.handleProcessEnd(error);
     if (proc) {
       try {
-        if (!killWindowsProcessTree(proc.pid)) proc.kill();
+        stopChild(proc);
       } catch {
         // Already gone.
       }
@@ -432,18 +458,30 @@ class CodexAppServerProcess {
 
   private readStream(): void {
     if (!this.proc?.stdout) return;
-    this.proc.stdout.on("data", (chunk: Buffer) => {
-      this.buffer += this.decoder.decode(chunk, { stream: true });
-      const lines = this.buffer.split("\n");
-      this.buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        const trimmed = line.replace(/\r$/, "");
-        if (!trimmed) continue;
-        try {
-          this.routeMessage(JSON.parse(trimmed));
-        } catch {
-          // Ignore malformed lines.
+    const stdout = this.proc.stdout;
+    stdout.on("data", (chunk: Buffer) => {
+      const text = this.decoder.decode(chunk, { stream: true });
+      // Only a chunk with a newline splits: searching the whole buffer on every chunk starves the event loop on a long line.
+      const end = text.lastIndexOf("\n");
+      if (end >= 0) {
+        const lines = `${this.buffer}${text.slice(0, end)}`.split("\n");
+        this.buffer = text.slice(end + 1);
+        for (const line of lines) {
+          const trimmed = line.replace(/\r$/, "");
+          if (!trimmed) continue;
+          try {
+            this.routeMessage(JSON.parse(trimmed));
+          } catch {
+            // Ignore malformed lines.
+          }
         }
+      } else {
+        this.buffer += text;
+      }
+      if (this.buffer.length > this.lineMax) {
+        this.buffer = "";
+        stdout.destroy();
+        this.failProcess(new Error("Codex app-server wrote a line past the limit"));
       }
     });
   }
@@ -549,14 +587,13 @@ class CodexAppServerProcess {
     return this._alive;
   }
 
-  kill(): void {
+  /** `now`: SIGKILL at once, for when this process is exiting and no later timer would run. */
+  kill(now = false): void {
     this._alive = false;
     this.startPromise = null;
     const proc = this.proc;
     this.proc = null;
-    if (proc) {
-      if (!killWindowsProcessTree(proc.pid)) proc.kill();
-    }
+    if (proc) stopChild(proc, now);
     this.listeners.length = 0;
     this.requestHandlers.length = 0;
     for (const [, pending] of this.pendingRequests) {

package/generated/config.ts

@@ -421,6 +421,13 @@ export interface PlannotatorConfig {
    * once per machine.
    */
   inboxListIntro?: { dueAt?: string; shownAt?: string };
+  /**
+   * Inbox voice dictation (approval "inbox-voice"), off unless turned on. Written by Settings → Voice and the
+   * announcement (`POST /api/inbox/settings` `{ voice }`).
+   */
+  inboxVoice?: { on?: boolean; phonesOnly?: boolean; engine?: "codex" | "api" };
+  /** The voice announcement: the list intro's rule (`dueAt`, or `shownAt` on a fresh install), claimed with `POST /api/inbox/voice/intro`. */
+  inboxVoiceIntro?: { dueAt?: string; shownAt?: string };
   /**
    * The Board (approval "inbox-board", 2026-10-26 amendment): something the
    * person turns on, off by default. On: the sidebar's Board row and page,

package/generated/inbox/connection.ts

@@ -415,6 +415,7 @@ export const INBOX_AGENT_FIELD_DESCRIPTIONS: Readonly<Record<string, Readonly<Re
       '',
       'Context in one to three plain sentences: what it affects, what you know, why you recommend one. The person switches in cold.',
       '',
+      '- [ ] Nowhere — silent loss, as today',
       '- [ ] Local only, purged after 30 days — cheap',
       '- [ ] Server-side per user — needs a retention policy',
       '',
@@ -422,7 +423,7 @@ export const INBOX_AGENT_FIELD_DESCRIPTIONS: Readonly<Record<string, Readonly<Re
       'Holds up: sync release',
       ':::',
       '',
-      'Your recommendation goes on the `Recommended:` line, never in a choice label. `:::question-multi` takes several choices, `:::question-text` free text. The person can always answer Other, add a note or skip, so never add an Other choice yourself. `Stopped: <why>` only when you cannot go on until it is answered (never `Stopped: no`); `Holds up: <work>` names work that waits while you go on. Ask only what you cannot decide alone, about 8 a round at most. Answers come back in the reply under "Answers to your questions".',
+      'Your recommendation goes on the `Recommended:` line, never in a choice label. Keep the choices in their natural order; never move yours first. `:::question-multi` takes several choices, `:::question-text` free text. The person can always answer Other, add a note or skip, so never add an Other choice yourself. `Stopped: <why>` only when you cannot go on until it is answered (never `Stopped: no`); `Holds up: <work>` names work that waits while you go on. Ask only what you cannot decide alone, about 8 a round at most. Answers come back in the reply under "Answers to your questions".',
       '',
       'Optional lines after the question; most questions need none of these: `Stakes: <what it affects>` (give one with every Stopped or Holds up), `Shows: ![alt](path)` or `Shows: [name](file)` (the one picture or file it is about), `Why: <why your recommendation>` on its own line, `Reversible: no — <why>` only when it cannot be undone. Visual options can be picture choices, `- [ ] Label — ![alt](path)`: the picture picks it, the label comes back.',
       '',
@@ -457,14 +458,14 @@ export const INBOX_AGENT_FIELD_DESCRIPTIONS: Readonly<Record<string, Readonly<Re
  * the send, before anything about the chat, so it reads as about the Inbox.
  */
 export const INBOX_REMINDER_TEXT =
-  `Plannotator Inbox is on: when you finish long work, or need a decision only the person can make, send it with plannotator_inbox send_message and keep going. ${INBOX_FOLLOW_THROUGH_RULE} ${INBOX_THREAD_RULE} Their reply comes back here. A decision in the Inbox stays there: when the person writes here, say what waits and link its thread, but never also ask it in the chat with a blocking question tool (AskUserQuestion or similar). Run \`plannotator inbox --help\` for how it works.`
+  `Plannotator Inbox is on: when you finish long work, or need a decision only the person can make, send it with plannotator_inbox send_message (each decision as a \`:::question\` block) and keep going. ${INBOX_FOLLOW_THROUGH_RULE} ${INBOX_THREAD_RULE} Their reply comes back here. A decision in the Inbox stays there: when the person writes here, say what waits and link its thread, but never also ask it in the chat with a blocking question tool (AskUserQuestion or similar). Run \`plannotator inbox --help\` for how it works.`
 
 /**
  * The same line for a host without the wake (OpenCode 1): the reply does not
  * come back by itself there, so it names wait_for_reply instead.
  */
 export const INBOX_REMINDER_TEXT_NO_WAKE =
-  `Plannotator Inbox is on: when you finish long work, or need a decision only the person can make, send it with plannotator_inbox send_message and keep going. ${INBOX_FOLLOW_THROUGH_RULE} ${INBOX_THREAD_RULE} Call wait_for_reply when you need their answer. A decision in the Inbox stays there: when the person writes here, say what waits and link its thread, but never also ask it in the chat with a blocking question tool (AskUserQuestion or similar). Run \`plannotator inbox --help\` for how it works.`
+  `Plannotator Inbox is on: when you finish long work, or need a decision only the person can make, send it with plannotator_inbox send_message (each decision as a \`:::question\` block) and keep going. ${INBOX_FOLLOW_THROUGH_RULE} ${INBOX_THREAD_RULE} Call wait_for_reply when you need their answer. A decision in the Inbox stays there: when the person writes here, say what waits and link its thread, but never also ask it in the chat with a blocking question tool (AskUserQuestion or similar). Run \`plannotator inbox --help\` for how it works.`
 
 /**
  * The reminder naming the tool as the host registered it. Claude Code defers

package/generated/question-block.ts

@@ -1873,11 +1873,11 @@ Ask what only the reviewer can decide as a question block. Answers come back at
 :::question
 Where should we keep the edit that loses a sync conflict?
 
-When two devices edit one note offline, the later save wins and the other edit is lost. Local storage keeps it with no server work.
+When two devices edit one note offline, the later save wins and the other is lost. Local storage keeps it with no server work.
 
-- [ ] Local only, purged after 30 days — cheap, no server change
+- [ ] Nowhere — silent loss, as today
+- [ ] Local only, purged after 30 days — cheap
 - [ ] Server-side per user — survives reinstall, needs a retention policy
-- [ ] Nowhere — accept silent loss for v1
 
 Recommended: Local only, purged after 30 days
 :::
@@ -1889,8 +1889,8 @@ Recommended: Local only, purged after 30 days
   - Be terse: one to three short sentences, plain words, no jargon or internal names.
   - Add a screenshot (\`![alt](path)\`) for anything visual.
   - Link a file that shows it better (a plan, a mock): \`[the mock](mock.html)\`. In the Inbox, attach it too; the link opens it beside the thread.
-- Choices: \`- [ ] label\`, optionally \`- [ ] label — why\`. The reviewer can also answer "Other", add a note, or skip.
-- \`Recommended: <label>\` marks yours (\`A, B and C\` on \`:::question-multi\`); other text is one more answer, tagged Recommended. Keep A, B, C order.
+- Choices: \`- [ ] label\`, optionally \`- [ ] label — why\`, in natural order. The reviewer can also answer "Other", add a note, or skip.
+- \`Recommended: <label>\` marks yours (\`A, B and C\` on \`:::question-multi\`); other text is one more answer, tagged Recommended. Never move yours first.
 - Ask only what you cannot decide alone, about 8 a round. Do not ask rhetorical questions or questions the codebase answers.
 - \`- [x]\` marks a settled choice. On resubmit, check the chosen answer, or drop the block and state the decision in prose.
 - Leave blank lines between the parts so the block reads well on GitHub.

package/generated/tailscale.ts

@@ -12,11 +12,13 @@
  *
  * Pure parsers live here so both runtimes (Bun server, Pi extension) share
  * them. The only process-spawning edge is `runTailscale`, which never invokes
- * a shell and is injectable for tests.
+ * a shell and is injectable for tests; it and the Inbox's async runner
+ * (inbox-pairing-checks.ts) share one lookup, `tailscaleAppFallback`.
  */
 
 import { childEnv } from "./child-env.ts";
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { isValidUrlHost } from "./config.ts";
 
 /** Detection commands answer from local state; keep the wait short. */
@@ -79,10 +81,66 @@ export interface TailscaleRunResult {
 
 export type TailscaleRunner = (args: string[], timeoutMs: number) => TailscaleRunResult;
 
-/** Run the `tailscale` CLI without a shell. */
-export const runTailscale: TailscaleRunner = (args, timeoutMs) => {
-  const result = spawnSync("tailscale", args, {
-    env: childEnv(),
+/**
+ * The Mac Tailscale app's own program, which is also its CLI when run by
+ * this exact path (Tailscale's "Install CLI" writes a `/usr/local/bin/tailscale`
+ * script that runs it). Never through a symlink: invoked under another name
+ * it crashes on its bundle identifier.
+ */
+export const MAC_TAILSCALE_APP_CLI = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
+
+/** What the app fallback reads; each part replaceable so tests never look at the real /Applications. */
+export interface TailscaleAppLookup {
+  platform?: NodeJS.Platform;
+  exists?: (path: string) => boolean;
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * The command to try when `tailscale` on PATH was not found (`ENOENT`): on
+ * macOS, the Tailscale app's own CLI if the app is installed, so a Mac whose
+ * app never had its command-line tool turned on still works. Undefined for
+ * any other failure, any other platform, or a test run
+ * (`PLANNOTATOR_TEST_SANDBOX`, so no test reaches the real app). PATH always
+ * comes first.
+ */
+export function tailscaleAppFallback(result: TailscaleRunResult, lookup: TailscaleAppLookup = {}): string | undefined {
+  if ((result.error as NodeJS.ErrnoException | undefined)?.code !== "ENOENT") return undefined;
+  if ((lookup.env ?? process.env).PLANNOTATOR_TEST_SANDBOX) return undefined;
+  if ((lookup.platform ?? process.platform) !== "darwin") return undefined;
+  return (lookup.exists ?? existsSync)(MAC_TAILSCALE_APP_CLI) ? MAC_TAILSCALE_APP_CLI : undefined;
+}
+
+/**
+ * The environment for the app's CLI: `env` with `SHLVL=1` when it has none.
+ * The app's program acts as a CLI only when its environment looks like a
+ * shell's (SHLVL or a non-empty TERM); with neither it tries to start the
+ * GUI instead. Tailscale's own `/usr/local/bin/tailscale` wrapper gets SHLVL
+ * from `sh`; an Inbox started without a terminal (the Claude app, launchd)
+ * has neither. TERM is left alone.
+ */
+export function tailscaleAppEnv(env: Record<string, string | undefined>): Record<string, string | undefined> {
+  return env.SHLVL ? env : { ...env, SHLVL: "1" };
+}
+
+/** What Tailscale's Mac app prints (exit 0) when run as a CLI without a shell-like environment. */
+const APP_GUI_FAILED = /The Tailscale GUI failed to start/;
+
+export const TAILSCALE_APP_NOT_CLI =
+  "The Tailscale app did not answer as a command-line tool; turn on Tailscale → Settings → Install CLI, then try again.";
+
+/** The app's CLI answer, with "the GUI failed to start" (which exits 0) turned into a failure callers report in plain words. */
+export function checkTailscaleAppAnswer(result: TailscaleRunResult): TailscaleRunResult {
+  if (result.error || !APP_GUI_FAILED.test(`${result.stdout}\n${result.stderr}`)) return result;
+  return { ...result, error: new Error(TAILSCALE_APP_NOT_CLI) };
+}
+
+/** Spawn one `tailscale` command (bare name or absolute path) without a shell, in `env`. */
+export type TailscaleSpawn = (command: string, args: string[], timeoutMs: number, env: Record<string, string | undefined>) => TailscaleRunResult;
+
+const spawnTailscale: TailscaleSpawn = (command, args, timeoutMs, env) => {
+  const result = spawnSync(command, args, {
+    env,
     encoding: "utf8",
     windowsHide: true,
     timeout: timeoutMs,
@@ -95,6 +153,26 @@ export const runTailscale: TailscaleRunner = (args, timeoutMs) => {
   };
 };
 
+/**
+ * A runner that tries `tailscale` on PATH, then the app's CLI
+ * (`tailscaleAppFallback`) with the same args and timeout, in `tailscaleAppEnv`.
+ * `baseEnv` is the child environment (the live `process.env` by default).
+ */
+export function createTailscaleRunner(
+  spawn: TailscaleSpawn = spawnTailscale,
+  lookup: TailscaleAppLookup = {},
+  baseEnv: () => Record<string, string | undefined> = childEnv,
+): TailscaleRunner {
+  return (args, timeoutMs) => {
+    const onPath = spawn("tailscale", args, timeoutMs, baseEnv());
+    const app = tailscaleAppFallback(onPath, lookup);
+    return app ? checkTailscaleAppAnswer(spawn(app, args, timeoutMs, tailscaleAppEnv(baseEnv()))) : onPath;
+  };
+}
+
+/** Run the `tailscale` CLI without a shell (PATH first, then the Mac app's CLI). */
+export const runTailscale: TailscaleRunner = createTailscaleRunner();
+
 /**
  * A failure whose cause is Tailscale's own state on this computer or tailnet,
  * in plain words with the next step, from what the CLI printed. Undefined for
@@ -112,6 +190,7 @@ export const runTailscale: TailscaleRunner = (args, timeoutMs) => {
 export function explainTailscaleSetup(result: TailscaleRunResult): string | undefined {
   const output = `${result.stdout}\n${result.stderr}`;
   const links = output.match(/https:\/\/[^\s"'<>]+/g) ?? [];
+  if (APP_GUI_FAILED.test(output)) return TAILSCALE_APP_NOT_CLI;
   const enableLink = links.find((link) => /\/f\/(?:serve|https)\b/.test(link));
   if (enableLink || /\b(?:serve|https)\b[^\n]*\bnot enabled\b/i.test(output)) {
     const link = enableLink ?? links.find((candidate) => /login\.tailscale\.com/.test(candidate));
@@ -145,7 +224,7 @@ export function describeTailscaleFailure(result: TailscaleRunResult): string {
   if (result.error) {
     const code = (result.error as NodeJS.ErrnoException).code;
     if (code === "ENOENT") {
-      return "`tailscale` CLI not found on PATH. Install Tailscale (https://tailscale.com/download) and sign in with `tailscale up`.";
+      return "`tailscale` CLI not found on PATH (on a Mac, Plannotator also looks for the app at /Applications/Tailscale.app). With the Tailscale app, turn on its command-line tool (Tailscale → Settings → Install CLI); otherwise install Tailscale from https://tailscale.com/download and sign in.";
     }
     if (code === "ETIMEDOUT") {
       return "Timed out waiting for the `tailscale` CLI.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/pi-extension",
-  "version": "0.28.42",
+  "version": "0.28.43",
   "type": "module",
   "description": "Plannotator Pi extension - interactive plan review with annotations, annotate agent messages, and review code/PRs",
   "author": "backnotprop",