@macintacos/caret 1.0.2 → 1.1.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "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,6 +35,8 @@ After installing:
 1. **Restart the agent.** OpenCode installs the plugin package on its next start.
 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
+   `caret` before the agent implements it.
 
 ### Running `caret` yourself
 
@@ -58,8 +60,12 @@ bunx --no-cache @macintacos/caret@latest install --refresh    # update
 bunx --no-cache @macintacos/caret@latest install --uninstall  # remove
 ```
 
+`--refresh` restarts the caret service on the newest caret installed, never older than the
+one you ran; caret keeps a copy of it under `~/.local/state/caret/roots/`.
+
 `caret`'s UI is designed to check for updates, at most once a day. When a newer `caret` is
-out, the review UI says so once: a toast on load, a mark on the settings button, and a
+out, the review UI says so once: a toast on load that opens **What's new** (the skipped
+release notes or trunk commits), a mark on the settings button, and a
 **Settings → Updates** pane naming the version and the exact command to take it.
 
 Turn the check off from that same pane, or by hand in
@@ -87,10 +93,12 @@ your browser instead of the terminal prompt. There you:
   and re-present.
 
 > [!TIP]
-> You don't have to wait to be intercepted: `caret` gives both agents a plan-review tool
-> they can call directly — `review_plan` in Claude Code (from the plugin's MCP server) and
-> `caret_review_plan` in OpenCode — so a skill of your own can route its plan through the
-> same review UI. The tool is for plans only; see
+> 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
 > [`doc/ARCHITECTURE.md`](doc/ARCHITECTURE.md#calling-the-review-tool-from-your-own-skill).
 
 ## Configuration
@@ -114,10 +122,12 @@ Two more live at the repo root:
 
 ## Diagnostics
 
-- `/caret:discovery` prints a one-shot, read-only diagnostics snapshot of your install —
-  always redacted, and it never contains plan, prompt, or feedback bodies, nor any log
-  contents.
-- `/caret:debug` reviews the current session's plans and recent errors.
+- `/caret:doctor` runs `caret doctor`: a one-shot, read-only check of your install —
+  what's wrong, how to fix it, and the state it read that from. Always redacted, and it
+  never contains plan, prompt, or feedback bodies, nor any log message, error or stack
+  text.
+- `caret doctor --bundle` archives the raw logs and review records when a maintainer needs
+  them. That archive is **not** redacted, so caret asks before writing it.
 
 ## License
 

package/bin/caret

@@ -2,7 +2,7 @@
 #
 # caret plugin entrypoint shim (EXC-643). This is the ONE file Claude Code's
 # hooks invoke — `${CLAUDE_PLUGIN_ROOT}/bin/caret <subcommand>` (see
-# hooks/hooks.json and commands/discovery.md). It is committed and shipped in
+# hooks/hooks.json and commands/doctor.md). It is committed and shipped in
 # every install; it resolves the actual caret runtime from whatever the install
 # method placed beside it:
 #

package/bin/caret-launcher

@@ -19,6 +19,9 @@
 #   service      the launchd label WITHOUT `.plist` on macOS; the full unit name
 #                WITH `.service` on Linux. Only macOS appends a suffix below.
 #
+# $XDG_STATE_HOME/caret/roots/<version>/ holds caret install's own copies, scanned
+# beside the agents' caches.
+#
 # Each record must end with a newline: `read -r` reports EOF on a file without
 # one, and the read is what decides the record exists.
 
@@ -28,6 +31,8 @@ state="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
 records="$state/launcher"
 claude_roots="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/caret/caret"
 opencode_roots="${XDG_CACHE_HOME:-$HOME/.cache}/opencode/packages/@macintacos"
+# Keep in sync with ownedRootsDir() (src/config/paths.ts).
+owned_roots="$state/roots"
 
 # The units name no log destination, so nothing opens this before caret does:
 # openDaemonStderr's 0700/0600 guarantee (src/daemon/lifecycle.ts) happens here for a
@@ -60,50 +65,70 @@ read_record() {
   [ -f "$1" ] && read -r value <"$1" && [ -n "$value" ] && printf '%s' "$value"
 }
 
-# Highest of the `<version><TAB><path>` lines on stdin. A numeric field sort
-# rather than `sort -V`, which BSD sort does not carry everywhere. Ceiling: on an
-# equal numeric prefix the whole-line tiebreak puts a prerelease ABOVE the stable
-# release, so 0.15.0-rc.1 would beat 0.15.0. caret publishes no prereleases.
+# Highest of the `<version><TAB><rest>` lines on stdin, printing <rest>. A numeric
+# field sort rather than `sort -V`, which BSD sort does not carry everywhere. On an
+# equal numeric prefix sort compares the whole line, and two things ride on that:
+# candidates() puts its rank right after the version, so an agent's root (1) beats an
+# owned copy (0) — keep the sort unstable (no -s); and a prerelease sorts ABOVE its
+# release (0.15.0-rc.1 beats 0.15.0), a ceiling since caret publishes no prereleases.
+# Keep in sync with pickLauncherRoot (src/commands/install/launcher.ts).
 highest() { sort -t. -k1,1n -k2,2n -k3,3n | tail -1 | cut -f2-; }
 
-# A candidate is a caret when it ships an executable bin/caret — the one file
-# every install method carries, tested the way it is used, since a non-executable
-# one would exec-fail at 126 and the supervisor would respawn into it forever.
+# bin/caret-native embeds its UI at compile time; the bundle serves ui/dist, so a
+# half-installed one would answer every UI request with ENOENT. A non-executable
+# bin/caret would exec-fail at 126 and the supervisor would respawn into it forever.
+# Keep in sync with isRunnableRoot (src/daemon/lifecycle.ts).
+root_runnable() {
+  [ -x "$1/bin/caret" ] || return 1
+  [ -x "$1/bin/caret-native" ] || [ -f "$1/ui/dist/index.html" ]
+}
+
 # Version comes from package.json, never the directory name: OpenCode names its
 # dir after the verbatim `plugin` specifier. The key is anchored so a minified
 # manifest yields nothing rather than a later key's value — a miss falls into the
 # branch that names the directory, a wrong version picks the wrong caret.
 candidate_version() {
-  [ -x "$1/bin/caret" ] || return 1
+  root_runnable "$1" || return 1
   sed -n 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1/package.json" 2>/dev/null | head -1
 }
 
-# Every dir either cache offers, runnable caret or not — the difference between
-# a broken install (terminal) and an empty cache (eviction). The OpenCode entry
-# is a two-line npm project, not a caret root; the root is one level down.
+# 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). The OpenCode entry is a two-line npm project, not a caret root; the
+# root is one level down. `*` skips dot-prefixed dirs, so a half-copied owned root
+# is never a candidate. Keep in sync with launcherCandidateDirs
+# (src/commands/install/launcher.ts).
 candidate_dirs() {
   local dir
-  for dir in "$claude_roots"/* "$opencode_roots"/caret*/node_modules/@macintacos/caret; do
+  for dir in "$claude_roots"/* "$opencode_roots"/caret*/node_modules/@macintacos/caret \
+    "$owned_roots"/*; do
     if [ -d "$dir" ]; then printf '%s\n' "$dir"; fi
   done
 }
 
+# `<version><TAB><rank><TAB><dir>`: rank 0 for caret's own copy, 1 for an agent's.
 candidates() {
-  local dir version
+  local dir version rank
   candidate_dirs | while read -r dir; do
     version="$(candidate_version "$dir" || true)"
-    if [ -n "$version" ]; then printf '%s\t%s\n' "$version" "$dir"; fi
+    rank=1
+    case "$dir" in "$owned_roots"/*) rank=0 ;; esac
+    if [ -n "$version" ]; then printf '%s\t%s\t%s\n' "$version" "$rank" "$dir"; fi
   done
 }
 
 resolve_root() {
   local pin
   pin="$(read_record "$records/pinned-root" || true)"
-  if [ -n "$pin" ] && [ -x "$pin/bin/caret" ]; then
+  if [ -n "$pin" ] && root_runnable "$pin"; then
     printf '%s' "$pin"
     return 0
   fi
-  candidates | highest
+  # The rank sorts an agent's root above an owned copy of the same version: a hook
+  # reuses a supervised daemon only when its build matches. highest() leaves
+  # candidates()' rank in front of the dir. Keep in sync with pickLauncherRoot
+  # (src/commands/install/launcher.ts).
+  candidates | highest | cut -f2-
 }
 
 # The newest mise-managed bun, for a machine whose mise shims are not on the
@@ -153,8 +178,8 @@ stop_agent() {
 # tears its service down and deletes itself. Returns non-zero without touching
 # anything when there is no `service` record — nothing here installed a
 # supervisor, so this launcher cannot know what still names it, and deleting
-# itself would leave whatever does respawning on ENOENT. Deleting only bin/ and
-# the records leaves review state for a reinstall.
+# itself would leave whatever does respawning on ENOENT. Deleting bin/, the
+# records and caret's own roots leaves review state for a reinstall.
 evict() {
   local service unit
   service="$(read_record "$records/service" || true)"
@@ -166,17 +191,17 @@ evict() {
     systemctl --user disable --now "$service" || true
     unit="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/$service"
   fi
-  printf 'caret-launcher: no caret installed anywhere; removing %s and %s.\n' \
-    "$unit" "$state/bin" >&2
+  printf 'caret-launcher: no caret installed anywhere; removing %s and %s/{bin,launcher,roots}.\n' \
+    "$unit" "$state" >&2
   rm -f "$unit"
-  rm -rf "${state:?}/bin" "${state:?}/launcher"
+  rm -rf "${state:?}/bin" "${state:?}/launcher" "${state:?}/roots"
   exit 0
 }
 
 # Only under a supervisor: a hand-run launcher keeps its diagnostics on the terminal.
 if [ "${CARET_SUPERVISED:-}" = 1 ]; then open_daemon_log; fi
 
-# Only a total miss re-probes. A populated version dir with no runnable bin/caret
+# Only a total miss re-probes. A populated version dir with no runnable caret
 # is far more likely a bad install than an extraction caught mid-flight, and that
 # path is recoverable with `caret install`; an empty cache is the one whose branch
 # deletes things, so it is the one worth waiting on.
@@ -190,7 +215,7 @@ done
 if [ -z "$root" ]; then
   found="$(candidate_dirs)"
   if [ -z "$found" ]; then evict || true; fi
-  printf 'caret-launcher: no runnable bin/caret under any of:\n%s\n' \
+  printf 'caret-launcher: no runnable caret (an executable bin/caret and a UI build) under any of:\n%s\n' \
     "${found:-(no install directories at all)}" >&2
   printf 'caret-launcher: run: caret install — to restore the service.\n' >&2
   stop_agent

package/commands/doctor.md

@@ -0,0 +1,140 @@
+---
+description: Diagnose this caret install — run caret doctor, relay each failing check's remedy, and present the report ready to share
+---
+
+caret's `doctor` subcommand renders a verdict over a one-shot, read-only snapshot of the
+local install: a `checks:` block naming what is wrong and how to fix it, then the state it
+read that from — running caret processes, daemon identity, lock/port state, effective
+settings, review counts, the agent adapter's install-state probe (plugin version, enabled
+state, and whether a manual hook sits in the agent's user settings), log sizes and error
+counts, recent failures grouped by review with their codes, install/runtime info, and
+system basics. The report is **always redacted** (home paths become `~`, usernames in
+foreign home paths are censored) and never contains plan, prompt, or feedback bodies, nor
+any log message, error or stack text — it exists to be shared.
+
+## 1. Run it
+
+First ask the user (via `AskUserQuestion`) which format they want:
+
+- **JSON** — for feeding to tooling.
+- **Human-readable** — for scanning in the conversation.
+
+Then run the matching invocation:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/bin/caret" doctor --json   # JSON
+"${CLAUDE_PLUGIN_ROOT}/bin/caret" doctor          # human-readable
+```
+
+The exit code is the verdict: `0` every check passed, `1` at least one failed, `2` no
+report — doctor could not produce one, or a `--bundle` run had no terminal to ask consent
+at and stopped before collecting anything. On `2`, present the exit code and stderr
+instead — and if the binary itself is missing (a source checkout that has never been
+built), say so and point at `mise run build` (or `mise run build --install`).
+
+## 2. Relay each failing check
+
+A failing check already carries the remedy that closes it; relay it rather than inventing
+one. What each id means:
+
+| id | what failed | relay |
+| --- | --- | --- |
+| `daemon-reachable` | a caret service is recorded but its supervisor is not keeping it alive (not loaded, turned off, or parked) or the daemon did not answer; or the effective port answers as something other than caret | the check's remedy verbatim, then offer to read any log it names |
+| `daemon-version` | the running daemon is older than npm's latest | the check's remedy verbatim |
+| `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-caret-version` | OpenCode 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 `<name> error: …`
+(`"error": "…"` under `--json`) and leaves the check with no detail. A doctor run offline
+reaching one is the normal case; present it as-is rather than treating it as a failure of
+this command. A daemon that is simply not running is not one of these — it reports
+`reachable false` and *passes*, because an on-demand daemon idle-exits by design.
+
+## 3. Present the report
+
+End your output with the command's stdout **verbatim** in a fenced code block —
+` ```json ` for the JSON format, plain ` ``` ` for the human-readable one — so the user
+can copy it out in one piece. Add nothing inside the block and do not summarize away
+sections; the report is already redacted and complete.
+
+## 4. Debug a failing `log-errors`
+
+When `log-errors` failed and the `/systematic-debugging` skill is available, invoke it to
+drive root-cause investigation from the logs the check named. Otherwise read the last
+error records yourself and reason from the failing step, code, msg, cause, and stack.
+
+Read the report's `failures` first. Each group is one review's error records from both
+logs with their codes (a session's, when the failure came before a review id existed), so
+a hook-side record sits beside any daemon-side record from that review's own requests. A
+daemon-wide failure (a crash, a bind failure, a failed update check) carries no id and
+lands in `ungrouped`: read it alongside the group and correlate the two by `time`. Pull a
+group's full records from both logs (`.sessionId` for a session group):
+
+```bash
+dir="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
+grep -h '^{' "$dir/logs/caret.log" "$dir/logs/daemon.log" | jq -c 'select(.reviewId == "<id>")'
+```
+
+For records outside any group or the report's window, fall back to the last error records
+of each log:
+
+```bash
+grep '^{' "$dir/logs/caret.log" | jq -s '[.[] | select(.level >= 50)] | .[-5:]'
+grep '^{' "$dir/logs/daemon.log" | jq -s '[.[] | select(.level >= 50)] | .[-5:]'
+tail -n 40 "$dir/logs/daemon-stderr.log"
+```
+
+`log-errors` counts only NDJSON error records, so a crash that reached `daemon-stderr.log`
+alone leaves it passing — tail that file even when the check is green. It fails only on
+records from the last 24h, so a log that has settled passes while still reporting when it
+last erred; work from that time rather than from the count. If a failure predates the
+current live file, `gunzip -c` the segment you need from `logs/archive/` and rerun the
+recipe against the result.
+
+## 5. Review this session's plans
+
+The report counts reviews in aggregate; it does not say what happened in *this* session.
+When the user wants that timeline, reconstruct it from the records — identify the session
+by the most recently updated review whose `cwd` matches, then list every review in it,
+oldest first:
+
+```bash
+dir="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
+sid=$(jq -rs --arg cwd "$PWD" '[.[] | select(.cwd == $cwd)] | sort_by(.updatedAt) | last | .sessionId // empty' "$dir"/reviews/*.json)
+jq -s --arg sid "$sid" '[.[] | select(.sessionId == $sid)] | sort_by(.createdAt) | .[] | {id, title, status, versions: (.versions | length), decidedAt: .decision.decidedAt, feedback: .decision.feedback}' "$dir"/reviews/*.json
+```
+
+That field whitelist is deliberate: `versions[].plan` and `generalCommentDraft` hold full
+plan and draft bodies — never select or echo them.
+
+If `sid` comes back empty, no review matches the working directory. Say so, then fall back
+to the most recently updated session across all reviews and re-run the listing with it:
+
+```bash
+sid=$(jq -rs 'sort_by(.updatedAt) | last | .sessionId // empty' "$dir"/reviews/*.json)
+```
+
+If `$dir/reviews` is missing or empty the glob won't match and these commands error (shell
+or jq, depending on the shell) — that is "no reviews recorded", not a failure.
+
+Present the result grouped by status, each review with its id, title, and version count
+(the number of plan revisions):
+
+- **pending** — awaiting a decision in the browser.
+- **rejected** — changes requested; awaiting a revised plan. Include a short excerpt of
+  the decision `feedback`.
+- **approved** — plan accepted; terminal success.
+- **expired** — abandoned by its hook (timeout) or superseded by a resubmitted plan;
+  terminal, never reviewed.
+
+## 6. Sharing the raw logs
+
+If the report is not enough and the user wants to hand the raw material to a maintainer,
+`caret doctor --bundle` writes a zip of the live logs and review records to caret's state
+dir. Tell them plainly before suggesting it: that archive is **not** redacted — it holds
+their logs and full plan bodies — so it is written only after they confirm, and it should
+move over a channel they trust. caret asks at a terminal and your run has none, so carry
+their answer with `--yes` — never before they have given it.

package/commands/plan.md

@@ -0,0 +1,25 @@
+---
+description: Plan a change and route the plan through caret's review UI before implementing it
+argument-hint: [what you want done]
+---
+
+Plan this, then implement it once caret approves the plan:
+
+$ARGUMENTS
+
+If that is empty, plan whatever the user asked for earlier in this session.
+
+Call `EnterPlanMode` first: `ExitPlanMode` is refused outside plan mode. Research what the
+change needs — read the relevant code, trace the real flow — then write the plan to the
+file your plan-mode instructions name. Call `ExitPlanMode` with that same text as its
+`plan` argument — caret reviews the argument, so a call without it reaches the review UI
+empty.
+
+This triggers caret's `PermissionRequest`/`ExitPlanMode` hook, which opens the plan in a
+local browser UI for inline review. When the user approves or requests changes there, the
+decision flows back to you:
+
+- **Approved** → implement the plan.
+- **Changes requested** → the feedback arrives as the denial reason. Re-read the plan file
+  (caret rewrites it in its canonical shape, so the feedback's line numbers match it),
+  revise it, and call `ExitPlanMode` again with the revised text as its `plan` argument.