@macintacos/caret 1.8.1 → 1.9.0

package/pi/doctor.ts

@@ -0,0 +1,149 @@
+// `/caret:doctor` for pi: runs `caret doctor` and shows its report in pi's transcript as
+// a custom entry, which never reaches the model.
+
+import { Text } from "@earendil-works/pi-tui";
+
+import { errorMessage, type SpawnRunner } from "../bridge/review-bridge.ts";
+import type { PiTheme } from "./render.ts";
+
+/** The customType of the transcript entry, and the key of the footer status. */
+export const DOCTOR_ENTRY = "caret-doctor";
+export const DOCTOR_TIMEOUT_MS = 60_000;
+/** Verdict lines without their glyph; doctorText adds it. */
+export const PASSED_VERDICT = "caret doctor: every check passed";
+export const FAILED_VERDICT = "caret doctor: at least one check failed";
+export const NO_REPORT_VERDICT = "caret doctor produced no report";
+
+/** What one `caret doctor` run came to; persisted as the `caret-doctor` entry's data. */
+export type DoctorOutcome =
+  | { kind: "report"; exitCode: 0 | 1; report: string }
+  | { kind: "no-report"; exitCode: number | null; reason: string };
+
+export type DoctorCommandContext = {
+  mode: "tui" | "rpc" | "json" | "print";
+  ui: { setStatus(key: string, text: string | undefined): void };
+};
+
+/** The slice of pi's extension API `/caret:doctor` calls; pinned by
+ * test/pi/sdk-conformance.ts. It has no send method: the report stays out of model
+ * context. */
+export type DoctorApi = {
+  registerCommand(
+    name: string,
+    options: {
+      description: string;
+      handler: (args: string, ctx: DoctorCommandContext) => Promise<void>;
+    },
+  ): void;
+  appendEntry(customType: string, data: DoctorOutcome): void;
+  registerEntryRenderer(customType: string, renderer: typeof renderDoctorEntry): void;
+};
+
+export type DoctorDeps = {
+  bin: string;
+  run: SpawnRunner;
+  env: Record<string, string | undefined>;
+};
+
+/** Runs `caret doctor` and describes the outcome; never throws. */
+export async function runDoctor({ bin, run, env }: DoctorDeps): Promise<DoctorOutcome> {
+  let stderr = "";
+  try {
+    const { stdout, exitCode } = await run(
+      [bin, "doctor", "--no-color"],
+      { ...env, CARET_AGENT: "pi" },
+      "",
+      (chunk) => {
+        stderr += chunk;
+      },
+      AbortSignal.timeout(DOCTOR_TIMEOUT_MS),
+    );
+    const report = stdout.trim();
+    if ((exitCode === 0 || exitCode === 1) && report) return { kind: "report", exitCode, report };
+    return {
+      kind: "no-report",
+      exitCode,
+      reason: stderr.trim() || `caret doctor exited ${exitCode} without a report.`,
+    };
+  } catch (err) {
+    // The timeout is the only abort source.
+    if (err instanceof Error && err.name === "AbortError")
+      return {
+        kind: "no-report",
+        exitCode: null,
+        reason: `caret doctor didn't finish within ${DOCTOR_TIMEOUT_MS / 1000} seconds.`,
+      };
+    return {
+      kind: "no-report",
+      exitCode: null,
+      reason: `Couldn't start caret at ${bin}: ${errorMessage(err)}`,
+    };
+  }
+}
+
+type Paint = (tone: "success" | "error", text: string) => string;
+
+/** The verdict line, a blank line, then the report or the reason. */
+export function doctorText(outcome: DoctorOutcome, paint: Paint = (_tone, s) => s): string {
+  if (outcome.kind === "no-report")
+    return `${paint("error", `✕ ${NO_REPORT_VERDICT}`)}\n\n${outcome.reason}`;
+  const verdict =
+    outcome.exitCode === 0
+      ? paint("success", `✓ ${PASSED_VERDICT}`)
+      : paint("error", `✕ ${FAILED_VERDICT}`);
+  return `${verdict}\n\n${outcome.report}`;
+}
+
+function isDoctorOutcome(data: unknown): data is DoctorOutcome {
+  if (typeof data !== "object" || data === null || !("kind" in data)) return false;
+  if (data.kind === "report")
+    return (
+      "exitCode" in data &&
+      (data.exitCode === 0 || data.exitCode === 1) &&
+      "report" in data &&
+      typeof data.report === "string"
+    );
+  if (data.kind === "no-report")
+    return (
+      "exitCode" in data &&
+      (data.exitCode === null || typeof data.exitCode === "number") &&
+      "reason" in data &&
+      typeof data.reason === "string"
+    );
+  return false;
+}
+
+/** The entry's row. Draws from the entry's data alone, since pi re-renders persisted
+ * entries on resume. */
+export function renderDoctorEntry(
+  entry: { data?: unknown },
+  _options: unknown,
+  theme: PiTheme,
+): Text | undefined {
+  if (!isDoctorOutcome(entry.data)) return undefined;
+  return new Text(
+    doctorText(entry.data, (tone, s) => theme.fg(tone, s)),
+    0,
+    0,
+  );
+}
+
+/** Registers `/caret:doctor` and the renderer for its transcript entry. */
+export function installDoctor(
+  pi: DoctorApi,
+  deps: DoctorDeps & { stdout: (text: string) => void },
+): void {
+  pi.registerEntryRenderer(DOCTOR_ENTRY, renderDoctorEntry);
+  pi.registerCommand("caret:doctor", {
+    description: "Check this caret install and show the report",
+    handler: async (_args, ctx) => {
+      ctx.ui.setStatus(DOCTOR_ENTRY, "running caret doctor…");
+      const outcome = await runDoctor(deps);
+      ctx.ui.setStatus(DOCTOR_ENTRY, undefined);
+      pi.appendEntry(DOCTOR_ENTRY, outcome);
+      // json mode already streams the entry as an `entry_appended` event; raw text there
+      // would corrupt the JSONL stream.
+      if (ctx.mode === "print") deps.stdout(`${doctorText(outcome)}\n`);
+    },
+  });
+}

package/pi/follow-up.ts

@@ -0,0 +1,19 @@
+// Sends a slash command's prompt as a follow-up and waits for the run it starts, so print
+// mode stays up until the agent has answered.
+
+type FollowUpApi = { sendUserMessage(content: string, options: { deliverAs: "followUp" }): void };
+
+/** Queues `content` as a follow-up and resolves once the run it starts has finished. */
+export async function sendAndWait(
+  pi: FollowUpApi,
+  ctx: { waitForIdle(): Promise<void> },
+  content: string,
+): Promise<void> {
+  pi.sendUserMessage(content, { deliverAs: "followUp" });
+  // ponytail: one macrotask lets the queued run start before waitForIdle; a run whose
+  // preflight awaits I/O (an extension's `input` handler, the auth check) starts later, so
+  // a print-mode run of a command that sends a follow-up may exit early. Fix once pi exposes
+  // the queued run's promise.
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await ctx.waitForIdle();
+}

package/pi/gate.ts

@@ -0,0 +1,49 @@
+// The planning gate's path containment. Imports node: builtins only and uses erasable
+// syntax only: test/pi/gate.test.ts loads it under plain Node, where pi runs.
+import { lstatSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+// pi's UNICODE_SPACES (utils/paths.js), which its edit and write tools turn into " ".
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/** Whether a write to `path`, resolved against `cwd` as pi's edit and write tools resolve
+ * it, lands inside `dir`. Fails closed: false whenever that can't be told, and for a
+ * `file:` URL, the one pi normalisation it does not mirror. */
+export function landsInside(path: string, cwd: string, dir: string): boolean {
+  try {
+    if (/^file:\/\//.test(normalize(path))) return false;
+    return realPathOf(resolveLikePi(path, cwd)).startsWith(realPathOf(dir) + sep);
+  } catch {
+    return false;
+  }
+}
+
+/** `path` resolved lexically against `cwd`, as pi's tools resolve it. */
+export function resolveLikePi(path: string, cwd: string): string {
+  return resolve(cwd, expandHome(normalize(path)));
+}
+
+function normalize(path: string): string {
+  return path.replace(UNICODE_SPACES, " ").replace(/^@/, "");
+}
+
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  return path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+
+/** The nearest existing ancestor's real path, plus the segments below it. Throws on an
+ * existing entry that won't resolve (a dangling symlink, a loop) or a missing root. */
+function realPathOf(path: string): string {
+  const missingSegments: string[] = [];
+  let at = path;
+  while (!lstatSync(at, { throwIfNoEntry: false })) {
+    // An absent win32 root (an unmapped drive) is its own dirname.
+    if (dirname(at) === at) throw new Error(`no such root: ${at}`);
+    missingSegments.unshift(basename(at));
+    at = dirname(at);
+  }
+  // .native: Node's JS realpathSync keeps the input's case on macOS.
+  return join(realpathSync.native(at), ...missingSegments);
+}

package/pi/notice.ts

@@ -0,0 +1,127 @@
+// The pending-plan notice above pi's editor, the `caret` footer status, and the `/caret`
+// command and ctrl+alt+o shortcut that open the waiting review. Colours come only from
+// pi's theme.
+
+import { type Component, MouseRegion, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { DetachedSpawn } from "../bridge/review-bridge.ts";
+import { footerText, type ReviewStore, type SessionReview } from "./state.ts";
+
+export const OPEN_KEY = "ctrl+alt+o";
+const NEWS = "plan waiting for your review";
+const VERB = "open in browser";
+const RPC_LINE = `^ caret  ${NEWS}   /caret ${VERB}`;
+
+/** The slice of pi's theme the notice reads; pinned by test/pi/sdk-conformance.ts. */
+export type NoticeTheme = {
+  fg(color: "warning" | "text" | "muted" | "dim", text: string): string;
+  bold(text: string): string;
+};
+
+type WidgetFactory = (tui: unknown, theme: NoticeTheme) => Component;
+
+/** The slice of pi's session context the notice calls; pinned by test/pi/sdk-conformance.ts. */
+export type NoticeContext = {
+  mode: "tui" | "rpc" | "json" | "print";
+  hasUI: boolean;
+  ui: {
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+    setStatus(key: string, text: string | undefined): void;
+    setWidget(key: string, content: string[] | WidgetFactory | undefined): void;
+  };
+  sessionManager: { getSessionId(): string };
+};
+
+/** The slice of pi's extension API the notice calls; pinned by test/pi/sdk-conformance.ts. */
+export type NoticeApi = {
+  on(event: "session_start", handler: (event: unknown, ctx: NoticeContext) => void): void;
+  on(event: "session_shutdown", handler: () => void): void;
+  registerCommand(
+    name: string,
+    options: { description: string; handler: (args: string, ctx: NoticeContext) => Promise<void> },
+  ): void;
+  registerShortcut(
+    shortcut: string,
+    options: { description: string; handler: (ctx: NoticeContext) => void },
+  ): void;
+};
+
+/** The row at `width`, with a one-column inset each side as pi's own string widgets have. */
+export function noticeLine(theme: NoticeTheme, width: number): string {
+  const innerWidth = width - 2;
+  const left = `${theme.fg("warning", "^")} ${theme.fg("muted", "caret")}  ${theme.bold(theme.fg("text", NEWS))}`;
+  const right = `${theme.fg("dim", OPEN_KEY)} ${theme.fg("muted", VERB)}`;
+  const gap = innerWidth - visibleWidth(`^ caret  ${NEWS}`) - visibleWidth(`${OPEN_KEY} ${VERB}`);
+  if (gap >= 2) return ` ${left}${" ".repeat(gap)}${right} `;
+  return ` ${truncateToWidth(left, Math.max(innerWidth, 0))}`;
+}
+
+/** The clickable row. pi runs a widget factory once, so `render()` must call the theme each
+ * time: a cached string would keep the old theme's colours. */
+export function noticeWidget(theme: NoticeTheme, open: () => void): Component {
+  // No OSC 8 link on the row: a link under the cell takes the click before the row does.
+  const row: Component = { render: (width) => [noticeLine(theme, width)], invalidate: () => {} };
+  // Only `click` opens: pi synthesises it on a still release, and handling `press` would
+  // steal the gesture from text selection.
+  return new MouseRegion(row, (event) => {
+    if (event.type !== "click" || event.button !== "left") return undefined;
+    open();
+    return { handled: true };
+  });
+}
+
+/** Paints the footer status and the row for `state` in the session's UI mode. */
+export function paint(ctx: NoticeContext, state: SessionReview, open: () => void): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.setStatus("caret", footerText(state));
+  if (!state.pending) ctx.ui.setWidget("caret", undefined);
+  else if (ctx.mode === "tui")
+    ctx.ui.setWidget("caret", (_tui, theme) => noticeWidget(theme, open));
+  else ctx.ui.setWidget("caret", [RPC_LINE]);
+}
+
+/** Paints the notice from the store for each session and registers `/caret` and the
+ * shortcut. Call once per pi instance. */
+export function installNotice(
+  pi: NoticeApi,
+  deps: { store: ReviewStore; bin: string; spawn: DetachedSpawn },
+): void {
+  const open = (ctx: NoticeContext) =>
+    deps.spawn(
+      deps.bin,
+      ["band-link", "--session", ctx.sessionManager.getSessionId(), "--open"],
+      (err) => {
+        try {
+          ctx.ui.notify(
+            `caret: open failed: ${err.message}. Run caret doctor to see why.`,
+            "error",
+          );
+        } catch {
+          // The session was replaced before the child reported; there is no UI left to tell.
+        }
+      },
+    );
+
+  let unsubscribe: (() => void) | undefined;
+  pi.on("session_start", (_event, ctx) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const openHere = () => open(ctx);
+    unsubscribe = deps.store.subscribe((id, state) => {
+      if (id === sessionId) paint(ctx, state, openHere);
+    });
+    paint(ctx, deps.store.get(sessionId), openHere);
+  });
+  pi.on("session_shutdown", () => {
+    unsubscribe?.();
+    unsubscribe = undefined;
+  });
+
+  pi.registerCommand("caret", {
+    description: "Open the waiting caret review in the browser",
+    handler: async (_args, ctx) => open(ctx),
+  });
+  pi.registerShortcut(OPEN_KEY, {
+    description: "Open the waiting caret review in the browser",
+    handler: (ctx) => open(ctx),
+  });
+}

package/pi/plan.ts

@@ -0,0 +1,182 @@
+// `/caret:plan`, caret's planning mode for pi: a hidden steer to write and submit a plan,
+// and a gate on edit/write outside the plans folder until a review of a plan in that
+// folder, submitted while planning, is approved. State lives in the review store (which
+// outlives `/reload`) and in session entries, rebuilt from the current branch so a fork or
+// `/tree` jump to before planning began is not planning.
+
+import { mkdirSync } from "node:fs";
+
+import { PLAN_TITLE_INSTRUCTION, REVIEW_TOOL } from "../bridge/review-bridge.ts";
+import { sendAndWait } from "./follow-up.ts";
+import { landsInside } from "./gate.ts";
+import type { ReviewStore } from "./state.ts";
+
+/** The customType of both the hidden steer message and the session entry. */
+export const PLANNING = "caret-planning";
+
+const LEAVE_NOTICE = "caret planning is off; edits are no longer blocked.";
+const EARLIER_TASK = "Plan what I asked for earlier in this session.";
+
+type SessionCtx = { sessionManager: { getSessionId(): string } };
+export type PlanningEntry = { type: string; customType?: string; data?: unknown };
+export type PlanningContext = SessionCtx & {
+  cwd: string;
+  sessionManager: { getBranch(): PlanningEntry[] };
+};
+export type PlanningCommandContext = PlanningContext & {
+  ui: { notify(message: string, type?: "info" | "warning" | "error"): void };
+  waitForIdle(): Promise<void>;
+};
+type SteerResult = { message: { customType: string; content: string; display: boolean } };
+type ToolCall = { toolName: string; toolCallId: string; input: Record<string, unknown> };
+type ToolResult = { toolName: string; toolCallId: string; details?: unknown };
+
+/** The slice of pi's extension API the planning mode calls; pinned by
+ * test/pi/sdk-conformance.ts. */
+export type PlanningApi = {
+  registerCommand(
+    name: string,
+    options: {
+      description: string;
+      handler: (args: string, ctx: PlanningCommandContext) => Promise<void>;
+    },
+  ): void;
+  sendUserMessage(content: string, options: { deliverAs: "followUp" }): void;
+  appendEntry(customType: string, data: { active: boolean }): void;
+  on(
+    event: "before_agent_start",
+    handler: (
+      event: { messageType: "user" | "custom" },
+      ctx: SessionCtx,
+    ) => SteerResult | undefined,
+  ): void;
+  on(
+    event: "context",
+    handler: <M>(event: { messages: M[] }, ctx: SessionCtx) => { messages: M[] } | undefined,
+  ): void;
+  on(
+    event: "tool_call",
+    handler: (event: ToolCall, ctx: PlanningContext) => { block: true; reason: string } | undefined,
+  ): void;
+  on(event: "tool_result", handler: (event: ToolResult, ctx: SessionCtx) => void): void;
+  on(
+    event: "session_start" | "session_tree",
+    handler: (event: unknown, ctx: PlanningContext) => void,
+  ): void;
+};
+
+export interface PlanningDeps {
+  store: ReviewStore;
+  plansDir: string;
+  /** Stands the caret daemon up ahead of the review; best-effort. */
+  warm: () => void;
+}
+
+/** The session id's last 8 characters: pi's ids are UUIDv7, whose leading characters are a
+ * timestamp shared by sessions started close together. */
+export function sessionTag(sessionId: string): string {
+  return sessionId.slice(-8);
+}
+
+/** The hidden message that tells the model to write its plan under `plansDir` and
+ * submit it. */
+export function planningSteer(plansDir: string, sessionId: string): string {
+  const file = `${plansDir}/<short-name>-${sessionTag(sessionId)}.md`;
+  return [
+    "## Planning mode (caret)",
+    "",
+    `You are in caret's planning mode. Research the change — read the relevant code and trace the real flow — but do not modify any file outside \`${plansDir}/\`: edit and write calls elsewhere are blocked until the plan is approved, and do not change files with shell commands either.`,
+    `Write the plan as markdown to \`${file}\`, replacing \`<short-name>\` with a short kebab-case name, then call the \`${REVIEW_TOOL}\` tool with that file as the \`path\` argument.`,
+    "It opens caret's visual review UI in the browser; the user approves or requests changes. A change request comes back as the tool result: re-read the file, revise it with targeted edits rather than rewriting it, and call the tool again with the same `path` until it is approved. Once it is approved, planning ends and you can implement the plan.",
+    PLAN_TITLE_INSTRUCTION,
+  ].join("\n");
+}
+
+/** Whether the branch's last planning entry turned planning on. */
+export function planningFromBranch(entries: readonly PlanningEntry[]): boolean {
+  const lastPlanningEntry = entries.findLast(
+    (e) =>
+      e.type === "custom" &&
+      e.customType === PLANNING &&
+      typeof (e.data as { active?: unknown } | undefined)?.active === "boolean",
+  );
+  return (lastPlanningEntry?.data as { active: boolean } | undefined)?.active === true;
+}
+
+/** Registers `/caret:plan` and its handlers on `pi`. Call once per pi instance: the set
+ * of in-flight review calls is per install. */
+export function installPlanning(pi: PlanningApi, deps: PlanningDeps): void {
+  const { store, plansDir, warm } = deps;
+  const reviewsWhilePlanning = new Set<string>();
+  const sid = (ctx: SessionCtx) => ctx.sessionManager.getSessionId();
+  const isPlanning = (ctx: SessionCtx) => store.get(sid(ctx)).planning;
+  const setPlanning = (ctx: SessionCtx, active: boolean) => {
+    if (active) mkdirSync(plansDir, { recursive: true });
+    pi.appendEntry(PLANNING, { active });
+    store.update(sid(ctx), { planning: active });
+  };
+  const restorePlanningFromBranch = (_event: unknown, ctx: PlanningContext) =>
+    store.update(sid(ctx), { planning: planningFromBranch(ctx.sessionManager.getBranch()) });
+  const pathInPlansDir = (call: ToolCall, ctx: PlanningContext) =>
+    typeof call.input.path === "string" && landsInside(call.input.path, ctx.cwd, plansDir);
+
+  pi.registerCommand("caret:plan", {
+    description: "Plan a change and review it in caret before any file is edited",
+    handler: async (args, ctx) => {
+      const task = args.trim();
+      if (!task && isPlanning(ctx)) {
+        setPlanning(ctx, false);
+        ctx.ui.notify(LEAVE_NOTICE, "info");
+        return;
+      }
+      if (!isPlanning(ctx)) setPlanning(ctx, true);
+      await sendAndWait(pi, ctx, task || EARLIER_TASK);
+    },
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    if (event.messageType !== "user" || !isPlanning(ctx)) return undefined;
+    try {
+      warm();
+    } catch {
+      /* best-effort */
+    }
+    return {
+      message: { customType: PLANNING, content: planningSteer(plansDir, sid(ctx)), display: false },
+    };
+  });
+
+  pi.on("context", (event, ctx) => {
+    if (isPlanning(ctx)) return undefined;
+    return {
+      messages: event.messages.filter(
+        (m) => (m as { customType?: unknown }).customType !== PLANNING,
+      ),
+    };
+  });
+
+  // Must not throw: pi does not catch a tool_call handler's throw.
+  pi.on("tool_call", (event, ctx) => {
+    if (!isPlanning(ctx)) return undefined;
+    if (event.toolName === REVIEW_TOOL) {
+      if (pathInPlansDir(event, ctx)) reviewsWhilePlanning.add(event.toolCallId);
+      return undefined;
+    }
+    if (event.toolName !== "edit" && event.toolName !== "write") return undefined;
+    if (pathInPlansDir(event, ctx)) return undefined;
+    return {
+      block: true,
+      reason: `Planning mode: only files in \`${plansDir}/\` can change until the plan is approved. Finish the plan there and submit it with \`${REVIEW_TOOL}\`.`,
+    };
+  });
+
+  pi.on("tool_result", (event, ctx) => {
+    if (event.toolName !== REVIEW_TOOL || !reviewsWhilePlanning.delete(event.toolCallId)) return;
+    if ((event.details as { state?: unknown } | undefined)?.state === "approved") {
+      setPlanning(ctx, false);
+    }
+  });
+
+  pi.on("session_start", restorePlanningFromBranch);
+  pi.on("session_tree", restorePlanningFromBranch);
+}

package/pi/render.ts

@@ -0,0 +1,51 @@
+// The caret_review_plan row in pi's transcript. Colours come only from pi's theme.
+
+import { basename } from "node:path";
+
+import { hyperlink } from "@earendil-works/pi-tui";
+
+import type { ReviewOutcome } from "./state.ts";
+
+/** The slice of pi's theme the review row and the doctor entry read. */
+export type PiTheme = {
+  fg(color: "toolTitle" | "muted" | "dim" | "warning" | "success" | "error", text: string): string;
+};
+
+export type ReviewDetails = { state: "waiting"; url: string } | { state: ReviewOutcome };
+
+/** The plan's first `# ` heading, else the plan file's name, else "plan". */
+export function planTitle(args: { plan?: string; path?: string }): string {
+  return args.plan?.match(/^# (.+)$/m)?.[1] ?? (args.path ? basename(args.path) : "plan");
+}
+
+export function callLine(args: { plan?: string; path?: string }, theme: PiTheme): string {
+  return `${theme.fg("toolTitle", "caret")} ${theme.fg("muted", planTitle(args))}`;
+}
+
+/** A result as pi hands it back. A call that never reached `execute` (bad schema, a
+ * blocking hook, an abort) carries `details: {}` and pi's reason in `content`, and so
+ * does a session written by a caret with another state set. */
+export type RenderedResult = {
+  content?: { type: string; text?: string }[];
+  details?: Partial<ReviewDetails>;
+};
+
+export function resultLine({ content, details }: RenderedResult, theme: PiTheme): string {
+  switch (details?.state) {
+    case "waiting": {
+      const url = details.url ?? "";
+      return `${theme.fg("warning", "^")} ${theme.fg("muted", "waiting for review")} ${theme.fg("dim", hyperlink(url, url))}`;
+    }
+    case "approved":
+      return theme.fg("success", "✓ approved");
+    case "changes":
+      return theme.fg("warning", "↺ changes requested");
+    case "cancelled":
+      return theme.fg("muted", "cancelled");
+    case "failed":
+      return theme.fg("error", "✕ review failed");
+    default:
+      details?.state satisfies undefined;
+      return theme.fg("error", `✕ ${content?.[0]?.text ?? "review failed"}`);
+  }
+}

package/pi/state.ts

@@ -0,0 +1,74 @@
+// Per-session review state for the pi extension. The notice (EXC-2316) and `/caret:plan`
+// (EXC-2317) consume this store and never redefine it.
+//
+// The data lives on `globalThis` because `/reload` loads a fresh module instance; pi
+// refuses `/reload` while a tool runs, so a pending review never straddles one. Only data
+// is kept there, so each instance runs its own methods over it. That stored shape is a
+// cross-version contract: bump the key when it changes. The listener set outlives
+// `/reload` too, so subscribers must unsubscribe on `session_shutdown`.
+
+export type ReviewOutcome = "approved" | "changes" | "cancelled" | "failed";
+
+export interface SessionReview {
+  /** The waiting review's URL; at most one per session, since the tool runs sequentially. */
+  pending?: string;
+  /** Whether the session is in caret's planning mode. */
+  planning: boolean;
+  /** How the session's most recent review ended. */
+  lastOutcome?: ReviewOutcome;
+}
+
+export type ReviewListener = (sessionId: string, state: SessionReview) => void;
+
+export interface ReviewStore {
+  get(sessionId: string): SessionReview;
+  update(sessionId: string, patch: Partial<SessionReview>): void;
+  /** Returns the unsubscribe function. */
+  subscribe(listener: ReviewListener): () => void;
+}
+
+type ReviewData = { sessions: Map<string, SessionReview>; listeners: Set<ReviewListener> };
+
+const newData = (): ReviewData => ({ sessions: new Map(), listeners: new Set() });
+
+function storeOver({ sessions, listeners }: ReviewData): ReviewStore {
+  const get = (sessionId: string): SessionReview => sessions.get(sessionId) ?? { planning: false };
+  return {
+    get,
+    update(sessionId, patch) {
+      const next = { ...get(sessionId), ...patch };
+      sessions.set(sessionId, next);
+      for (const listener of listeners) {
+        try {
+          listener(sessionId, next);
+        } catch {
+          // A footer must never cost the review its decision.
+        }
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+export function createReviewStore(): ReviewStore {
+  return storeOver(newData());
+}
+
+const DATA_KEY = Symbol.for("caret.pi.reviews.v1");
+
+/** The process-wide store over data kept on `holder` (globalThis in production); every
+ * call on one holder shares sessions and listeners. */
+export function reviewStore(holder: Record<symbol, unknown>): ReviewStore {
+  holder[DATA_KEY] ??= newData();
+  return storeOver(holder[DATA_KEY] as ReviewData);
+}
+
+/** The text of the `caret` footer status key; undefined clears it. */
+export function footerText(state: SessionReview): string | undefined {
+  if (state.pending) return "^ plan waiting";
+  if (state.planning) return "^ planning";
+  return undefined;
+}