@plannotator/pi-extension 0.28.42 → 0.28.44

package/generated/ai/endpoints.ts

@@ -148,6 +148,13 @@ export interface AIEndpointDeps {
    * `authorizeSessionBridgeRequest` (loopback Host) before the token check.
    */
   pullBridge?: { handle(req: Request): Promise<Response> | null };
+  /**
+   * A dropped `/api/ai/query` stream leaves the question running: the answer
+   * keeps draining and the provider decides what to do with it. The Inbox's
+   * Ask AI saves it, so a reload or a sleeping phone stops nothing. Default off:
+   * a disconnect aborts. `/api/ai/abort` aborts either way.
+   */
+  keepRunningOnDisconnect?: boolean;
 }
 
 /** Error code for a bridge request refused by `authorizeSessionBridgeRequest`. */
@@ -266,6 +273,7 @@ export function createAIEndpoints(deps: AIEndpointDeps) {
     beforeProviderSession,
     authorizeSessionBridgeRequest,
     pullBridge,
+    keepRunningOnDisconnect = false,
   } = deps;
 
   // Streams whose question /api/ai/abort already handled. The browser drops a
@@ -465,31 +473,31 @@ export function createAIEndpoints(deps: AIEndpointDeps) {
         markers!.delete(marker);
         if (markers!.size === 0 && liveStreams.get(sessionId) === markers) liveStreams.delete(sessionId);
       };
+      // Set only with `keepRunningOnDisconnect`: the question drains into nothing.
+      let draining = false;
       const stream = new ReadableStream({
         async start(controller) {
+          const send = (text: string) => {
+            if (!draining) controller.enqueue(encoder.encode(text));
+          };
           try {
             const messages = Object.keys(queryOptions).length > 0
               ? entry.session.query(effectivePrompt, queryOptions)
               : entry.session.query(effectivePrompt);
             for await (const message of messages) {
-              const data = JSON.stringify(message);
-              controller.enqueue(
-                encoder.encode(`data: ${data}\n\n`)
-              );
+              send(`data: ${JSON.stringify(message)}\n\n`);
             }
-            controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+            send("data: [DONE]\n\n");
           } catch (err) {
             const errorMsg: AIMessage = {
               type: "error",
               error: err instanceof Error ? err.message : String(err),
               code: "stream_error",
             };
-            controller.enqueue(
-              encoder.encode(`data: ${JSON.stringify(errorMsg)}\n\n`)
-            );
+            send(`data: ${JSON.stringify(errorMsg)}\n\n`);
           } finally {
             forget();
-            controller.close();
+            if (!draining) controller.close();
           }
         },
         cancel() {
@@ -497,8 +505,9 @@ export function createAIEndpoints(deps: AIEndpointDeps) {
           // close, navigation). Stop the in-flight turn so it doesn't keep
           // running on the now long-lived provider process. Not when an abort
           // request already handled this question (see liveStreams).
+          draining = keepRunningOnDisconnect;
           forget();
-          if (marker.handled) return;
+          if (marker.handled || draining) return;
           entry.session.abort();
         },
       });

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/ai/session-bridge-pull.ts

@@ -114,11 +114,15 @@ export interface PullSessionBridgeOptions extends PullSessionBridgeConfig {
 	interruptTimeoutMs?: number;
 	/** Default 15s: after a cancel, how long to wait for the host to confirm before freeing the slot. */
 	cancelGraceMs?: number;
+	/** Default 1,000,000: the most characters one request may carry. A `done` repeats the whole answer. */
+	maxBodyChars?: number;
 	now?: () => number;
 }
 
 export interface PullSessionBridge {
 	readonly bridge: SessionBridge;
+	/** The host has polled, so `status()` is what it reported, not a new bridge's `ready`. */
+	readonly connected: boolean;
 	/** Handle a request to one of the two bridge paths. `null` for any other path. */
 	handle(req: Request): Promise<Response> | null;
 	/** Server shutdown: answer open polls with `closing`, fail anything still waiting. */
@@ -211,11 +215,14 @@ export function createPullSessionBridge(options: PullSessionBridgeOptions): Pull
 	const resendAfterMs = options.resendAfterMs ?? 5_000;
 	const interruptTimeoutMs = options.interruptTimeoutMs ?? 15_000;
 	const cancelGraceMs = options.cancelGraceMs ?? 15_000;
+	const maxBodyChars = options.maxBodyChars ?? MAX_EVENT_BODY_BYTES;
 	const createdAt = now();
 	const modes = { ...options.modes };
 
 	let hostStatus: SessionBridgeStatus = "ready";
 	let connected = false;
+	/** A poll came: an event alone reports no status, however late it is. */
+	let polled = false;
 	let lastSeen = createdAt;
 	let openPoll: OpenPoll | null = null;
 	let active: ActiveAsk | null = null;
@@ -404,7 +411,7 @@ export function createPullSessionBridge(options: PullSessionBridgeOptions): Pull
 
 	const readJson = async (req: Request): Promise<unknown> => {
 		const text = await req.text();
-		if (text.length > MAX_EVENT_BODY_BYTES) throw new Error("Request body too large.");
+		if (text.length > maxBodyChars) throw new Error("Request body too large.");
 		return text ? JSON.parse(text) : {};
 	};
 
@@ -425,6 +432,7 @@ export function createPullSessionBridge(options: PullSessionBridgeOptions): Pull
 			return json({ error: "Invalid JSON body." }, 400);
 		}
 		noteContact();
+		polled = true;
 		if (isRecord(body)) {
 			applyStatus(body.status);
 			if (isRecord(body.modes)) {
@@ -543,6 +551,9 @@ export function createPullSessionBridge(options: PullSessionBridgeOptions): Pull
 
 	return {
 		bridge,
+		get connected() {
+			return polled;
+		},
 		handle(req) {
 			const path = new URL(req.url).pathname;
 			if (path !== SESSION_BRIDGE_POLL_PATH && path !== SESSION_BRIDGE_EVENT_PATH) return null;

package/generated/config.ts

@@ -360,6 +360,11 @@ export interface PlannotatorConfig {
    * out): on wherever the tool is on.
    */
   inboxReminder?: boolean | Partial<Record<InboxToolHost, boolean>>;
+  /**
+   * The Plannotator Inbox's debug log (`inbox/debug.log` in the data dir), as
+   * `PLANNOTATOR_INBOX_DEBUG=1`. Config-only, read when the Inbox starts.
+   */
+  inboxDebug?: boolean;
   /**
    * The Plannotator Inbox's browser notifications, set from the Inbox page
    * (its one-time ask and its Settings), kept here rather than in the page's
@@ -421,6 +426,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,
@@ -1481,6 +1493,17 @@ export function resolveInboxPhones(
   return coerceConfigBoolean(config.inboxPhones, false);
 }
 
+/**
+ * Whether the Plannotator Inbox offers Ask AI: an environment switch, off by
+ * default, until the owner has used it. Off, the ask routes answer 404, no
+ * question can wait and no agent connects for one. Same words as
+ * PLANNOTATOR_INBOX_PHONES; anything else counts as off.
+ */
+export function resolveInboxAskAi(env: NodeJS.ProcessEnv = process.env): boolean {
+  const v = env.PLANNOTATOR_INBOX_ASK_AI?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "on";
+}
+
 /**
  * The experimental features this build knows: the name PLANNOTATOR_EXPERIMENTAL
  * lists (kebab case) and the key it is saved under in config.json

package/generated/inbox/connection.ts

@@ -361,7 +361,7 @@ export const INBOX_TOOL_LEAD =
  * OpenCode 2 as a user message, and all three carry the wake's first line.
  */
 export const INBOX_TOOL_WAKE_NOTE =
-  "A reply arrives in this session by itself once it is idle, headed `Plannotator Inbox: <subject> (<reply id>)`: end your turn or keep working; do not call wait_for_reply. To answer it, send_message with reply_to set to that reply id, never one from memory."
+  "A reply arrives in this session by itself once it is idle, headed `Plannotator Inbox: <title> (<reply id>)`: end your turn or keep working; do not call wait_for_reply. To answer it, send_message with reply_to set to that reply id, never one from memory."
 
 /**
  * Fixed text, the description's last line: where everything the tool's short
@@ -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
@@ -773,7 +774,12 @@ export interface InboxReplyCommand {
   thread_id: string
   /** The agent message a reply answers; null for a message. */
   reply_to: string | null
-  /** The thread's subject. */
+  /**
+   * The title a wake shows, as the Inbox decided it (`InboxStore.agentTitle`):
+   * on a plain reply the thread's short name, or null when it has none, which
+   * every connection words `a reply`; on everything else the thread's
+   * subject. An older Inbox always sends the subject here.
+   */
   subject: string | null
   /** The reply or message, markdown, verbatim. */
   body: string
@@ -981,6 +987,36 @@ function wakeName(value: unknown): string {
  */
 export const INBOX_SEND_NOW_POLL_FIELD = 'send_now'
 
+/**
+ * The poll field (`true`) by which a connection says it can answer Ask AI
+ * live. An older connection never sends it, so a question never waits for it.
+ */
+export const INBOX_ASK_POLL_FIELD = 'ask'
+
+/**
+ * Set (`true`) on every poll answer while a question waits for this session
+ * and its Ask AI client has not connected, and a held poll ends at once. The
+ * connection then runs the client against `inboxAskBridgeBase(session)`, with
+ * the Inbox's token, until the Inbox says `closing`. It is a state, not an
+ * event: a poll answer that does not read it loses nothing.
+ */
+export const INBOX_ASK_WAITS_FIELD = 'ask_waits'
+
+export const INBOX_ASK_BRIDGE_PREFIX = '/api/inbox/ask/'
+
+/** Where a session's Ask AI client talks to the Inbox: the pull bridge's two paths go after it. */
+export function inboxAskBridgeBase(session: string): string {
+  return `${INBOX_ASK_BRIDGE_PREFIX}${encodeURIComponent(session)}`
+}
+
+export function parseInboxAskWaits(text: string): boolean {
+  try {
+    return (JSON.parse(text) as Record<string, unknown>)[INBOX_ASK_WAITS_FIELD] === true
+  } catch {
+    return false
+  }
+}
+
 /**
  * The turn a connection submits when a reply it put into a running turn
  * arrived as that turn ended, so the model never read it: the reply is in
@@ -1140,8 +1176,9 @@ export function inboxWakeClosingLine(threadId: unknown, toolName: string = INBOX
 }
 
 /**
- * The turn a reply or a message becomes: `Plannotator Inbox: <subject> (<id>)`,
- * the fixed instruction line for its type (a reply, a New message, or a
+ * The turn a reply or a message becomes: `Plannotator Inbox: <title> (<id>)`
+ * (the title is the command's `subject`, or `a reply` / `a message` without
+ * one), the fixed instruction line for its type (a reply, a New message, or a
  * thread the person started; on a redirected reply, the line
  * saying so under it), then the words verbatim, then the closing line
  * (`inboxWakeClosingLine`, naming `toolName`, the tool as the host

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.44",
   "type": "module",
   "description": "Plannotator Pi extension - interactive plan review with annotations, annotate agent messages, and review code/PRs",
   "author": "backnotprop",