@macintacos/caret 1.1.0 → 1.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "1.1.0",
+  "version": "1.2.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

@@ -60,6 +60,9 @@ 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 that opens **What's new** (the skipped
 release notes or trunk commits), a mark on the settings button, and a
@@ -73,10 +76,12 @@ Turn the check off from that same pane, or by hand in
 check = false
 ```
 
-See [the OpenCode adapter](doc/ARCHITECTURE.md#the-opencode-adapter) for the by-hand
-equivalents, for pinning a version in OpenCode's `plugin` array, and for what each agent's
-install touches; [the Claude Code adapter](doc/ARCHITECTURE.md#the-claude-code-adapter)
-covers the hooks `caret` registers there.
+`caret` supports OpenCode v1 1.3.4 or later. 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;
+[the Claude Code adapter](doc/ARCHITECTURE.md#the-claude-code-adapter) covers the hooks
+`caret` registers there.
 
 ## Using `caret`
 
@@ -104,6 +109,8 @@ your browser instead of the terminal prompt. There you:
 port, the review timeout, the log level — it reads an optional `config.toml` and `CARET_*`
 environment variables. Every key, every variable, and their defaults are in
 [`doc/CONFIGURING.md`](doc/CONFIGURING.md).
+To open the review UI from another device, such as a phone or a laptop, see
+[Reaching caret from another device](doc/RUNNING.md#reaching-caret-from-another-device).
 
 ## Documentation
 

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.
 
@@ -27,7 +30,11 @@ set -euo pipefail
 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"
+opencode_cache="${XDG_CACHE_HOME:-$HOME/.cache}/opencode"
+opencode_v1_roots="$opencode_cache/packages/@macintacos"
+opencode_v2_roots="$opencode_cache/npm/@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 +67,96 @@ 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.
+# OpenCode v2's live install under spec dir $1: the numerically largest all-digit
+# child. Older generations persist beside it and are never loaded. Keep in sync with
+# liveGenerationDir (src/adapters/opencode/paths.ts).
+live_generation() {
+  local dir name newest=""
+  for dir in "$1"/*; do
+    name="${dir##*/}"
+    case "$name" in '' | *[!0-9]*) continue ;; esac
+    if [ -z "$newest" ] || [ "$name" -gt "$newest" ]; then newest="$name"; fi
+  done
+  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
+# (src/adapters/opencode/paths.ts); both suites pin it through
+# test/core/commands/install/fixtures/launcher-caches.txt.
 candidate_dirs() {
-  local dir
-  for dir in "$claude_roots"/* "$opencode_roots"/caret*/node_modules/@macintacos/caret; do
+  local dir spec live
+  for dir in "$claude_roots"/* \
+    "$opencode_v1_roots"/caret/node_modules/@macintacos/caret \
+    "$opencode_v1_roots"/caret@*/node_modules/@macintacos/caret; do
+    if [ -d "$dir" ]; then printf '%s\n' "$dir"; fi
+  done
+  for spec in "$opencode_v2_roots"/caret "$opencode_v2_roots"/caret@*; do
+    if [ ! -d "$spec" ]; then continue; fi
+    live="$(live_generation "$spec")"
+    dir="$live/node_modules/@macintacos/caret"
+    if [ -n "$live" ] && [ -d "$dir" ]; then printf '%s\n' "$dir"; fi
+  done
+  for dir in "$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 +206,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 +219,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 +243,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

@@ -39,7 +39,8 @@ one. What each id means:
 
 | id | what failed | relay |
 | --- | --- | --- |
-| `daemon-reachable` | a caret service is recorded but 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-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 |