@macintacos/caret 1.8.0 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Review, annotate, and approve Claude Code plans in a local web UI.",
   "author": { "name": "macintacos" },
   "homepage": "https://github.com/macintacos/caret",

package/README.md

@@ -35,7 +35,8 @@ Assuming that you installed it as a long-lived service (the default), you can na
 
 After installing:
 
-1. **Restart the agent.** OpenCode installs the plugin package on its next start.
+1. **Restart the agent.** OpenCode installs the plugin package on its next start; in pi,
+   run `/reload` or restart it.
 2. **Run `/caret:demo`.** It presents a short demo plan that points at files in the repo
    you run it from, so you can exercise the whole flow before a real one arrives.
 3. **Run `/caret:plan <what you want done>`** to plan a real change and review it in
@@ -83,9 +84,15 @@ check = false
 loads caret but can't review a plan file the agent wrote, so the agent sends the plan text
 instead. See [the OpenCode adapter](doc/ARCHITECTURE.md#the-opencode-adapter) for the
 by-hand equivalents, for pinning a version in OpenCode's plugin array (`plugin` on v1,
-`plugins` on v2), and for what each agent's install touches;
+`plugins` on v2); [`caret install`](doc/ARCHITECTURE.md#installing-with-caret-install)
+covers what each agent's install touches;
 [the Claude Code adapter](doc/ARCHITECTURE.md#the-claude-code-adapter) covers the hooks
-`caret` registers there.
+`caret` registers there. `caret install` also installs into pi 1.5.0 or later when `pi` is
+on your PATH; run `/reload` in pi or restart it to pick caret up. `caret install` and
+`caret doctor` manage only pi's user-scope packages and ignore a project-scope install
+(`pi install -l`). OpenCode and pi both load caret from its npm package, which runs on
+bun, so `bun` must be on the PATH they run with. See
+[the pi adapter](doc/ARCHITECTURE.md#the-pi-adapter) for the by-hand equivalents.
 
 ## Using `caret`
 
@@ -103,13 +110,32 @@ your browser instead of the terminal prompt. There you:
 > You don't have to wait to be intercepted: `/caret:plan <what you want done>` asks the
 > agent for a plan and routes it straight to the review UI. In OpenCode it runs on the
 > `plan` agent, so switch to `build` to implement once you approve. A skill of your own
-> can do the same with the plan-review tool `caret` gives both agents — `review_plan` in
-> Claude Code (from the plugin's MCP server) and `caret_review_plan` in OpenCode. The tool
-> is for plans only; see
+> can do the same with the plan-review tool `caret` gives each agent — `review_plan` in
+> Claude Code (from the plugin's MCP server) and `caret_review_plan` in OpenCode and pi.
+> The tool is for plans only; see
 > [`doc/ARCHITECTURE.md`](doc/ARCHITECTURE.md#calling-the-review-tool-from-your-own-skill).
 > In OpenCode v2, `/caret` or `<leader>p` (`ctrl+x p` by default) opens the plan waiting
 > in the session; rebind the key as `caret.open` under OpenCode's `keybinds`.
 
+### Using `caret` in pi
+
+pi has no plan mode of its own, so `caret` brings a small one:
+
+1. `/caret:plan <what you want done>` turns on planning mode. The agent researches, writes
+   its plan into pi's plans folder (`~/.pi/agent/plans` by default), and sends it to
+   `caret`. Until you approve, `caret` blocks the agent's `edit` and `write` tools outside
+   that folder; shell commands are only discouraged. While planning, `/caret:plan` with no
+   task turns planning off. Outside planning, a bare `/caret:plan` plans what you asked
+   for earlier in the session.
+2. While a review waits, a notice sits above the editor and the footer reads
+   `^ plan waiting`. `/caret` or `ctrl+alt+o` opens the plan in your browser. In
+   Terminal.app or iTerm2, set Option to act as Meta (Esc+) for the shortcut to reach pi.
+3. Approve, and the agent implements. Request changes, and it revises and resubmits. Esc
+   in pi cancels a waiting review, and the agent is told not to implement the plan.
+
+`/caret:demo` presents a demo plan, and `/caret:doctor` runs `caret doctor` and shows its
+report in the session (see [Diagnostics](#diagnostics)).
+
 ## Configuration
 
 `caret` runs with sensible defaults and needs no configuration. To tune it — the daemon
@@ -130,7 +156,8 @@ to the reference page that answers your question.
 Two more live at the repo root:
 
 - [CONTRIBUTING.md](CONTRIBUTING.md) — develop `caret` locally: setup, the `mise`
-  workflow, and where tests live.
+  workflow, and where tests live. PRs run the full eight-check gate in CI;
+  `mise run preflight` is the fast local one.
 - [AGENTS.md](AGENTS.md) — for coding agents: routes a change to the rules-of-the-road
   that govern it.
 

package/bin/caret-launcher

@@ -2,9 +2,9 @@
 #
 # The stable launcher a launchd plist or systemd unit names (EXC-1160). Those
 # units must name an absolute executable path, but caret's runtime lives at a
-# versioned path that changes on every upgrade — and both Claude Code and
-# OpenCode replace their copy on their own schedule, without running
-# `caret install`. So the unit names this file, which caret owns at
+# versioned path that changes on every upgrade — and Claude Code, OpenCode,
+# and pi (`pi update`) each replace their copy on their own schedule, without
+# running `caret install`. So the unit names this file, which caret owns at
 # $XDG_STATE_HOME/caret/bin/caret, and resolution happens here at exec time.
 #
 # Bash rather than TypeScript for the same reason bin/caret is: it has to locate
@@ -33,6 +33,9 @@ claude_roots="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/caret/caret"
 opencode_cache="${XDG_CACHE_HOME:-$HOME/.cache}/opencode"
 opencode_v1_roots="$opencode_cache/packages/@macintacos"
 opencode_v2_roots="$opencode_cache/npm/@macintacos"
+# pi's default agent dir only: the supervisor never records PI_CODING_AGENT_DIR.
+# Keep in sync with launcherCandidateDirs (src/commands/install/launcher.ts).
+pi_root="$HOME/.pi/agent/npm/node_modules/@macintacos/caret"
 # Keep in sync with ownedRootsDir() (src/config/paths.ts).
 owned_roots="$state/roots"
 
@@ -107,13 +110,14 @@ live_generation() {
   if [ -n "$newest" ]; then printf '%s' "$1/$newest"; fi
 }
 
-# Every dir either agent's cache or caret's own copies offer, runnable caret or
-# not — the difference between a broken install (terminal) and an empty cache
-# (eviction). OpenCode's cache dir is named exactly `caret` or `caret@<spec>`: v1's
-# holds a two-line npm project with the root one level down; v2's holds numbered
-# generations, of which only the live one is offered. `*` skips dot-prefixed dirs,
-# so a half-copied owned root is never a candidate. Keep in sync with
-# launcherCandidateDirs (src/commands/install/launcher.ts) and opencodeRootPaths
+# Every dir an agent's cache, pi's npm folder, or caret's own copies offer,
+# runnable caret or not — the difference between a broken install (terminal)
+# and an empty cache (eviction). OpenCode's cache dir is named exactly `caret`
+# or `caret@<spec>`: v1's holds a two-line npm project with the root one level
+# down; v2's holds numbered generations, of which only the live one is offered.
+# `*` skips dot-prefixed dirs, so a half-copied owned root is never a
+# candidate. Keep in sync with launcherCandidateDirs
+# (src/commands/install/launcher.ts) and opencodeRootPaths
 # (src/adapters/opencode/paths.ts); both suites pin it through
 # test/core/commands/install/fixtures/launcher-caches.txt.
 candidate_dirs() {
@@ -129,6 +133,7 @@ candidate_dirs() {
     dir="$live/node_modules/@macintacos/caret"
     if [ -n "$live" ] && [ -d "$dir" ]; then printf '%s\n' "$dir"; fi
   done
+  if [ -d "$pi_root" ]; then printf '%s\n' "$pi_root"; fi
   for dir in "$owned_roots"/*; do
     if [ -d "$dir" ]; then printf '%s\n' "$dir"; fi
   done

package/{opencode → bridge}/review-bridge.ts

@@ -1,16 +1,121 @@
 // The bridge from an agent's plan-review tool to `caret review`, shared by the OpenCode
-// plugin and `caret mcp`: build caret's review envelope, spawn the review, and turn the
-// flat decision it prints into the tool's result text. It sits in opencode/ because that
-// directory ships as unbundled source the plugin can reach only by relative import, and
-// it imports node builtins only, so bundling it into the CLI pulls in no plugin SDK. It
-// also holds PLAN_TITLE_INSTRUCTION, since this is the one module the plugin, `caret mcp`
-// and `caret steer` can all import.
+// plugin, `caret mcp` and pi's extension: resolve the plan and the caret binary, build
+// caret's review envelope, warm the daemon, spawn the review, and turn the flat decision
+// it prints into the tool's result text; it also holds the detached opener both TUIs use
+// for `band-link --open`. It ships as unbundled source the OpenCode plugin and pi's
+// extension reach by relative import, and the CLI bundles it, so it imports node builtins
+// only: nothing from src/, and no plugin SDK. It also holds PLAN_TITLE_INSTRUCTION, since
+// this is the one module the hosts, `caret mcp` and `caret steer` can all import.
 
 import { spawn } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { constants } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
+/** `failsafe` is set only on a deny caret made itself because the review could not run,
+ * never on a reviewer's. */
 export type CaretDecision =
   | { behavior: "allow"; feedback?: string; acceptMode?: string }
-  | { behavior: "deny"; feedback: string };
+  | { behavior: "deny"; feedback: string; failsafe?: true };
+
+/** The plan-review tool the agent calls. */
+export const REVIEW_TOOL = "caret_review_plan";
+
+// The review tool's model-facing text, shared so the hosts' registrations stay
+// word-for-word identical (plugin-v2.test.ts and test/pi/tool.test.ts pin it per host).
+export const REVIEW_TOOL_DESCRIPTION =
+  "Submit the current plan to caret for human review in a local browser UI. For plans only: caret presents what it receives as a plan, so do not use it for other documents or questions. Pass exactly one of `path` (preferred: a markdown file you write once and revise with edits) or `plan` (the plan inline). Blocks until the user approves or requests changes. On a change request, follow the result's instructions and call this tool again. Do not implement the plan until a call returns an approval.";
+
+export const PLAN_ARG_DESCRIPTION =
+  "The complete plan, as markdown, to present for human review. The inline alternative to `path`.";
+
+/** The caret binary a host spawns. The `overrideVar` env override wins; else
+ * `../bin/caret` beside the calling module's `importMetaUrl`. */
+export function resolveCaretBin(opts: {
+  env: Record<string, string | undefined>;
+  importMetaUrl: string;
+  overrideVar: string;
+}): string {
+  const override = opts.env[opts.overrideVar]?.trim();
+  if (override) return override;
+  return fileURLToPath(new URL("../bin/caret", opts.importMetaUrl));
+}
+
+/** `err`'s message, or `err` stringified when it is not an Error. A twin of
+ * `errorMessage` in src/lib/types.ts, which this module cannot import. */
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Semver triple `[major, minor, patch]`, or null when `v` is not `X.Y.Z` (an
+ * optional leading `v` is stripped; trailing prerelease/build metadata ignored). */
+export function parseVersionTriple(v: string): [number, number, number] | null {
+  const m = v
+    .trim()
+    .replace(/^v/, "")
+    .match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** True when `latest` is a strictly higher semver than `current`. Inline (no semver
+ * dep) so the deployed plugin stays self-contained; an unparseable version on
+ * either side compares false, so the check never nags on something it can't read. */
+export function isNewer(latest: string, current: string): boolean {
+  const a = parseVersionTriple(latest);
+  const b = parseVersionTriple(current);
+  if (!a || !b) return false;
+  const [a0, a1, a2] = a;
+  const [b0, b1, b2] = b;
+  if (a0 !== b0) return a0 > b0;
+  if (a1 !== b1) return a1 > b1;
+  return a2 > b2;
+}
+
+type PlanSource = { plan: string; planFilePath?: string };
+
+/** The plan the review tool submits, from exactly one of its `plan` / `path` args (an
+ * empty string counts as absent). A `path` resolves against the session directory and
+ * must be a readable `.md` file — mirroring the core's `isPlanFile`
+ * (src/plan/canonical-file.ts), repeated here because this module cannot import src/.
+ * `readFile` returns the text, or undefined when absPath is not a readable regular
+ * file. */
+export function resolvePlanSource(
+  args: { plan?: string; path?: string },
+  directory: string,
+  readFile: (absPath: string) => string | undefined,
+): PlanSource | { error: string } {
+  const plan = args.plan || undefined;
+  const path = args.path || undefined;
+  const notExactlyOne = {
+    error: `caret: ${REVIEW_TOOL} takes exactly one of \`plan\` or \`path\`. Pass the plan file as \`path\`, or the plan inline as \`plan\`.`,
+  };
+  if (path === undefined) return plan === undefined ? notExactlyOne : { plan };
+  if (plan !== undefined) return notExactlyOne;
+  const planFilePath = resolve(directory, path);
+  if (!planFilePath.endsWith(".md")) {
+    return {
+      error: `caret: ${REVIEW_TOOL} needs a markdown (.md) file as \`path\`, not ${planFilePath}. Write the plan to a .md file, or pass it inline as \`plan\`.`,
+    };
+  }
+  const text = readFile(planFilePath);
+  if (text === undefined) {
+    return {
+      error: `caret: ${REVIEW_TOOL} could not read ${planFilePath} as a regular file. Write the plan there first, or pass it inline as \`plan\`.`,
+    };
+  }
+  return { plan: text, planFilePath };
+}
+
+/** The file's text, or undefined when `absPath` is not a readable regular file; never
+ * throws. */
+export function readRegularFile(absPath: string): string | undefined {
+  try {
+    return statSync(absPath).isFile() ? readFileSync(absPath, "utf-8") : undefined;
+  } catch {
+    return undefined;
+  }
+}
 
 /** Asks the model to open its plan on a `#` heading, which deriveTitle
  * (src/review/threading.ts) prefers as the review title — keep the two in sync. Sent by
@@ -54,6 +159,7 @@ export function parseDecision(stdout: string): CaretDecision {
       behavior?: unknown;
       feedback?: unknown;
       acceptMode?: unknown;
+      failsafe?: unknown;
     };
     if (parsed.behavior === "allow") {
       // Reviewer notes (EXC-791) ride the allow; surface them to the agent below.
@@ -69,6 +175,7 @@ export function parseDecision(stdout: string): CaretDecision {
       return {
         behavior: "deny",
         feedback: typeof parsed.feedback === "string" ? parsed.feedback : "Plan changes requested.",
+        ...(parsed.failsafe === true && { failsafe: true }),
       };
     }
     return failsafeDeny("caret: unrecognized review decision — denying to fail safe.");
@@ -78,7 +185,7 @@ export function parseDecision(stdout: string): CaretDecision {
 }
 
 function failsafeDeny(feedback: string): CaretDecision {
-  return { behavior: "deny", feedback };
+  return { behavior: "deny", feedback, failsafe: true };
 }
 
 /** Tool result returned to the agent on approval. Optional reviewer notes
@@ -166,7 +273,8 @@ export function parseReviewUrl(stderr: string): string | undefined {
  * the child's stderr chunks as they arrive, so the caller can surface the review URL
  * the core prints there while the review is still pending. An aborted `signal` must
  * terminate the child and settle (reject) promptly: `caret mcp` refuses a new call until
- * the aborted one settles. */
+ * the aborted one settles. A child killed by a signal exits 128 + the signal number, as
+ * in a shell, so it never reads as success. */
 export type SpawnRunner = (
   command: string[],
   env: Record<string, string | undefined>,
@@ -223,8 +331,7 @@ export async function runReviewViaCaret(
     );
     return parseDecision(stdout);
   } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return failsafeDeny(`caret: review failed to run (${message}) — denying to fail safe.`);
+    return failsafeDeny(`caret: review failed to run (${errorMessage(e)}) — denying to fail safe.`);
   }
 }
 
@@ -248,10 +355,44 @@ export const nodeSpawnRunner: SpawnRunner = (command, env, stdin, onStderr, sign
     });
     child.stderr.on("data", (chunk) => onStderr?.(chunk.toString()));
     child.on("error", reject);
-    child.on("close", (code) => resolve({ stdout, exitCode: code ?? 0 }));
+    child.on("close", (code, killedBy) =>
+      resolve({ stdout, exitCode: code ?? 128 + (killedBy ? constants.signals[killedBy] : 0) }),
+    );
     // A child killed before reading stdin EPIPEs the write; unhandled, that crashes the
     // host. The 'error'/'close' handlers above already settle.
     child.stdin.on("error", () => {});
     child.stdin.write(stdin);
     child.stdin.end();
   });
+
+/** Spawns `bin args` detached and unwaited; `onError` hears a child that fails to start
+ * or exits non-zero. */
+export type DetachedSpawn = (bin: string, args: string[], onError: (err: Error) => void) => void;
+
+/** A DetachedSpawn over node's `spawn` whose children get `env` laid over the inherited
+ * environment. */
+export const detachedSpawnWith =
+  (env?: Record<string, string>): DetachedSpawn =>
+  (bin, args, onError) => {
+    // spawn reports ENOENT asynchronously; unhandled, that 'error' takes the host down.
+    const child = spawn(bin, args, {
+      stdio: "ignore",
+      detached: true,
+      env: env && { ...process.env, ...env },
+    });
+    child.on("error", onError);
+    // band-link exits 0 on its own failures, so non-zero means caret never ran.
+    child.on("exit", (code) => {
+      if (code) onError(new Error(`exited with status ${code}`));
+    });
+    child.unref();
+  };
+
+export const nodeDetachedSpawn = detachedSpawnWith();
+
+/** Warms the caret daemon: `caret prewarm`, detached and best-effort, so it never holds
+ * up the turn. CARET_AGENT rides along because this spawn is what stands the daemon up
+ * and the daemon picks its adapter from that env. */
+export function warmCaret(bin: string, agent: string): void {
+  detachedSpawnWith({ CARET_AGENT: agent })(bin, ["prewarm"], () => {});
+}

package/commands/doctor.md

@@ -44,7 +44,11 @@ one. What each id means:
 | `daemon-lock` | the lock names a dead pid, or a port caret is not configured to bind | the check's remedy verbatim |
 | `agent-install` | the agent the check names does not have caret enabled | `caret install` |
 | `log-errors` | a live log wrote an NDJSON error record in the last 24h; the detail names which log and when it last erred | step 4 |
+| `opencode-host` | an `opencode` on PATH is below its major's floor (1.3.4 for v1, 2.0.29 for v2), or caret sits in a key or config file that OpenCode doesn't load | the check's remedy verbatim |
 | `opencode-caret-version` | OpenCode would load a caret behind the published one | the check's remedy verbatim |
+| `pi-host` | `pi` can't run, is older than 1.5.0, or is the pre-rename `@mariozechner/pi-coding-agent` | the check's remedy verbatim |
+| `pi-caret-entry` | pi lists caret more than once, filters out its extension, or lists it without its package installed | the check's remedy verbatim |
+| `pi-caret-version` | pi would load a caret behind the published one | the check's remedy verbatim |
 
 An `unknown` check is not a failure: it names its own `reason` — no network, an unreadable
 config, or a report section that never collected, which also shows as an `error` line