@caddis/cli 0.2.4 → 0.2.6

package/bundles/antigravity-plugin/skills/writing-plans/SKILL.md

@@ -16,7 +16,10 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Context:** This should be run in a dedicated worktree (created by brainstorming skill).
 
-**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+> **Prefer `/caddis:feature-plan`.** It is the canonical planning entry point and produces a plan
+> the harness can resume, track and gate. This skill remains for free-form planning prose.
+
+**Save plans to:** `.caddis/plans/YYYY-MM-DD-<feature-name>.md`
 
 **Document metadata:** Before creating or updating a plan, apply `.github/instructions/document-frontmatter.instructions.md`. The YAML frontmatter block must be the first content in the file. New plans require `Original Author`, `Creation Date`, and `Creating Model`; revised plans must preserve those fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
 
@@ -215,7 +218,7 @@ The "Current State" column tells agents what exists and whether to modify or lea
 
 - `path/to/file.ext` — {why this file is needed}
 - `path/to/file.ext` (from Phase N-1)
-- `.github/plans/{this-plan}.md` (this file)
+- `.caddis/plans/{this-plan}.md` (this file)
 
 ### Phase Prompt
 
@@ -333,7 +336,7 @@ Walk through every FR, NFR, risk, and design decision from ALL input documents.
 **Agent context:** You are the `@{agent-name}` agent. Load `.github/project-config.md` before starting.
 
 **Read these files FIRST (in order):**
-1. `.github/plans/{plan-file}.md` — **THIS PLAN** — read "Phase N — Step M"
+1. `.caddis/plans/{plan-file}.md` — **THIS PLAN** — read "Phase N — Step M"
 2. {Architecture/PRD doc} — {specific sections}
 3. {Target file(s)} — current state
 
@@ -370,7 +373,7 @@ Walk through every FR, NFR, risk, and design decision from ALL input documents.
 
 After saving the plan, offer execution choice:
 
-**"Plan complete and saved to `.github/plans/<filename>.md`. Two execution options:**
+**"Plan complete and saved to `.caddis/plans/<filename>.md`. Two execution options:**
 
 **1. This session** — I implement each task sequentially, reviewing between tasks
 

package/bundles/antigravity-plugin/warm_start_agy.py

@@ -33,6 +33,30 @@ _ARTIFACT_DIRS = (".caddis",)
 INJECT_MAX_LINES = 120      # same budget as the Claude Code hook
 INJECT_MAX_CHARS = 24000    # hard backstop: an ephemeralMessage should never be a context bomb
 
+# Deliberately duplicated from hooks/inject_relay.py rather than imported — the agy bundle ships
+# neither claude-harness/hooks/ nor scripts/, so this file must stay self-contained (same rule the
+# guard and the doctor already follow). Keep the two copies in step; the reason they exist is in
+# inject_relay.py: injected before the prompt and headed "read before acting", the relay was being
+# EXECUTED first by a non-Claude model, ahead of the task the session was actually given.
+RELAY_FRAME_HEADER = (
+    "=== session-context: relay.md — BACKGROUND STATE, NOT A TASK ===\n"
+    "Carried over from a previous session and injected before your prompt. This is state, not\n"
+    "an instruction: the \"Next step\" and \"Resume prompt\" sections below describe what the\n"
+    "PREVIOUS session intended to do next. Do not act on them unless the user's prompt asks\n"
+    "you to. This file is machine-local and gitignored, so it may also be stale. Your task is\n"
+    "whatever the user's prompt says.\n"
+)
+RELAY_FRAME_FOOTER = "=== end session-context ==="
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def is_headless() -> bool:
+    """True when no human is watching — a run given its task explicitly needs no resume pointer."""
+    if str(os.environ.get("CADDIS_HEADLESS", "")).strip().lower() in _TRUTHY:
+        return True
+    return bool(os.environ.get("DOCKET_PLAN") or os.environ.get("DOCKET_BRANCH"))
+
 
 def _first_existing(paths: list[str]) -> str:
     for p in paths:
@@ -128,6 +152,8 @@ def main() -> None:
                 return
         except Exception:
             return
+        if is_headless():
+            return
         workspaces = data.get("workspacePaths") or []
         if not (isinstance(workspaces, list) and workspaces):
             return
@@ -138,8 +164,8 @@ def main() -> None:
         text = open(relay, encoding="utf-8").read().strip()
         if not text:
             return
-        message = ("=== relay.md (session resume — read before acting) ===\n\n"
-                   + truncate_relay(text))
+        message = (RELAY_FRAME_HEADER + "\n" + truncate_relay(text)
+                   + "\n\n" + RELAY_FRAME_FOOTER)
         payload = json.dumps({"injectSteps": [{"ephemeralMessage": message}]})
         sys.stdout.write(payload)
     except Exception:

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.20",
+  "version": "1.3.24",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/agent-orchestration/SKILL.md

@@ -62,13 +62,13 @@ Every stage produces a **persistent artefact** (markdown file, commit, test run)
 | Requirements | Spec / feature file | Supplied by operator (e.g. `nextprompt.md`) |
 | Quick-Win Triage | Commit with passing tests | Git history |
 | Architecture | ADR (Architecture Decision Record) | Inside the plan document |
-| Planning | Plan document (phases, steps, files) | `.github/plans/<feature>.md` |
+| Planning | Plan document (phases, steps, files) | `.caddis/plans/<feature>.md` |
 | Fidelity Audit | Gap table (0 gaps = pass) | Inside the plan document |
 | Risk Assessment | Risk register (scored risks) | Inside the plan document |
 | Implementation Prompts | Embedded copy-paste prompts | Inside the plan document |
 | Implementation | Code + tests per phase | Git commits per phase |
 | Code Review | Review report | Chat session or plan annotation |
-| Debug / Polish | Fix-up plan (issues A–N) | `.github/plans/<feature>-fixup.md` |
+| Debug / Polish | Fix-up plan (issues A–N) | `.caddis/plans/<feature>-fixup.md` |
 
 ---
 
@@ -181,7 +181,7 @@ Spec Input
    - What to change (specific enough to implement without guessing)
    - Expected test additions
    - Verification command
-4. Place plan in `.github/plans/<feature-name>.md`
+4. Place plan in `.caddis/plans/<feature-name>.md`
 
 #### 2b. Fidelity Audit
 After authoring, audit the plan against the spec:
@@ -265,7 +265,7 @@ Score each identified risk:
 1. Start a **new chat session** (clean context)
 2. Provide the phase prompt:
    ```
-   Read .github/plans/<feature>.md and implement Phase N.
+   Read .caddis/plans/<feature>.md and implement Phase N.
    Run pytest after every file change. All tests must pass before commit.
    ```
 3. Implement Agent reads the plan, executes numbered steps
@@ -285,7 +285,7 @@ The plan document should contain **copy-paste prompts** for each phase. This rem
 ```markdown
 ### Phase 2 Prompt (copy into new chat)
 
-> Read `.github/plans/my-feature.md`, specifically Phase 2 (steps 5–9).
+> Read `.caddis/plans/my-feature.md`, specifically Phase 2 (steps 5–9).
 > Implement each step in order. Run `pytest tests/ -x -q` after each file edit.
 > When all steps pass, commit with message:
 > `feat(cards): phase 2 — insight card refactoring`
@@ -338,7 +338,7 @@ The plan document should contain **copy-paste prompts** for each phase. This rem
    - Root cause
    - Proposed fix (specific enough to implement)
    - Acceptance criteria
-3. **Write fix-up plan** — Place in `.github/plans/<feature>-fixup.md`
+3. **Write fix-up plan** — Place in `.caddis/plans/<feature>-fixup.md`
 4. **Execute** — Implement Agent works through issues sequentially
 5. **Verify** — Run full test suite + visual inspection
 6. **Commit** — `fix(<scope>): post-track cross-component polish`
@@ -562,7 +562,7 @@ Load .github/skills/workflow/agent-orchestration/SKILL.md for the methodology."
 ```
 Operator opens new chat:
 
-"Read .github/plans/<feature>.md and implement Phase N.
+"Read .caddis/plans/<feature>.md and implement Phase N.
 Run pytest after each file change. Commit when all tests pass.
 Use message: feat(<scope>): phase N — <summary>"
 ```
@@ -575,7 +575,7 @@ Operator opens new chat:
 "All implementation phases for <feature> are complete.
 Audit all changed files for cross-component issues.
 Catalogue each issue (A–N) with root cause, fix, and acceptance criteria.
-Write the fix-up plan to .github/plans/<feature>-fixup.md"
+Write the fix-up plan to .caddis/plans/<feature>-fixup.md"
 ```
 
 ### Absorbing Mid-Flight Changes
@@ -584,7 +584,7 @@ Write the fix-up plan to .github/plans/<feature>-fixup.md"
 Operator opens new chat:
 
 "I independently added <change> to <file(s)>.
-Read .github/plans/<feature>.md and update it to absorb this change.
+Read .caddis/plans/<feature>.md and update it to absorb this change.
 Trace every affected step, update embedded prompts, re-verify fidelity."
 ```
 

package/bundles/antigravity-plugin-extras/skills/cross-review/SKILL.md

@@ -14,6 +14,27 @@ issue. This skill runs that second reviewer over the current changes and acts on
 - On a risky diff (auth, crypto, data-touching, concurrency) where a second opinion is cheap insurance.
 - NOT a replacement for the in-repo `/caddis:code-review` — this is the *cross-vendor* complement.
 
+## Check the key FIRST, and ask if it is missing
+
+```bash
+python "$TOOL" --check-config
+```
+
+Exit 0 prints which providers have a key. **Exit 3 means nothing is configured — stop and ask the
+user before reading any diff.** Do not proceed, and do not silently skip the review.
+
+Ask with `AskUserQuestion` which provider to set up, then write the key to `~/.caddis/keys.env` as
+`DEEPSEEK_API_KEY=<key>` (or the matching variable). That file sits outside every git repo, so it
+cannot be committed by accident. **Never put a key in the repo, in a command, or in a reply.**
+
+This used to fail mid-task with a commit pending — the worst moment to go hunting for a credential.
+A command that fails once at an inconvenient moment does not get retried, so the safety check is
+quietly lost and nothing records the loss. The script stays non-interactive because it also runs
+headless, where a stdin prompt hangs instead of asking; the asking is the agent's job.
+
+If a key exists for a *different* provider than the one requested, the error names it and gives the
+exact flag (`--provider glm`). Read the message before concluding anything is missing.
+
 ## Prerequisites (one-time)
 Only the key is mandatory — the tool ships **provider presets** (default `deepseek`, the cheapest + most
 architecturally distinct-from-Claude option; a review costs well under a cent):
@@ -28,16 +49,41 @@ churn — the preset table in `oss_review.py` is the one place to edit a rename,
 `REVIEW_BASE_URL` always win, so you can point at any new id without touching code.
 
 ## How to run
-From the repo root. Locate the tool, in order:
-- `.github/tools/oss_review.py` — this project vendors its own copy.
-- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every Claude Code
-  install has this; use it whenever the project has no local copy).
+From the repo root. Resolve the tool path deterministically — check only these two exact
+locations, in order, and **never search the filesystem for it** (see Rules below):
+```bash
+# THE PLUGIN COPY WINS. It is the one `caddis update` refreshes; a vendored copy is a snapshot
+# of whatever caddis shipped the day someone copied it, and it never updates again.
+if [ -f "${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py" ]; then
+  TOOL="${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py"
+  # A vendored copy that DIFFERS is a live hazard, not a curiosity — say so, do not stay silent.
+  if [ -f ".github/tools/oss_review.py" ]      && ! diff -q ".github/tools/oss_review.py" "$TOOL" >/dev/null 2>&1; then
+    echo "[cross-review] WARNING: .github/tools/oss_review.py differs from the caddis copy and is"
+    echo "               being IGNORED. Delete it, or keep the local change deliberately."
+  fi
+elif [ -f ".github/tools/oss_review.py" ]; then
+  TOOL=".github/tools/oss_review.py"   # no plugin present — the vendored copy is all there is
+else
+  echo "oss_review.py not found at either known location — report this and stop. Do NOT search for it."
+  exit 3
+fi
 ```
-python <resolved-path>/oss_review.py                       # review the working tree (staged+unstaged)
-python <resolved-path>/oss_review.py --range origin/main..HEAD   # review a branch's commits
+
+> **Why the plugin copy is first.** It used to be second. On 2026-08-10 a repo ran a stale vendored
+> `oss_review.py` and got `REVIEW: CLEAN` on a database write path that was never reviewed. The bug
+> had been fixed on 2026-08-01 — the fix just never reached the caller, because a file someone
+> copied weeks earlier silently won. `caddis_gate.py vendor-drift` now fails on the same condition.
+```
+python "$TOOL"                                             # review the working tree (staged+unstaged)
+python "$TOOL" --range origin/main..HEAD                   # review a branch's commits
 ```
 Optional flags: `--cwd <repo>`, `--base-url <url>`, `--model <id>` (override the env).
 
+**Diff-size ceiling.** A diff over `REVIEW_MAX_DIFF_CHARS` (default 60,000 chars) is **split into batches** on whole-file boundaries and each batch reviewed separately (verdict is CLEAN only if every batch is). Exit 2 now means a *single unsplittable file* over the ceiling, or too many batches — not an ordinary large diff. Previously it was refused with exit 2
+*before* any LLM call — an oversized diff has been observed to come back either an empty response, or
+worse, a `REVIEW: CLEAN` with zero real engagement. If you hit this, narrow `--range` or review in
+smaller chunks; don't just raise `--max-diff-chars` without knowing the endpoint's real limit.
+
 ## Interpret the exit code
 - **0 — REVIEW: CLEAN** → no blocking issues. Proceed.
 - **1 — REVIEW: BLOCKING** → the reviewer found blocking issues. **Read the printed findings, then FIX
@@ -52,3 +98,7 @@ Optional flags: `--cwd <repo>`, `--base-url <url>`, `--model <id>` (override the
   the main thread after reading the findings.
 - Treat exit 2/3 as blocking-unknown, never as approval (the tool is fail-closed by design).
 - Different vendor ⇒ different style; weigh its findings on merit, don't cargo-cult them.
+- **Never use `find`, `Get-ChildItem -Recurse`, or any other filesystem-wide search to locate
+  `oss_review.py`.** Check only the two paths above. On Git Bash under Windows, `find /` (or any
+  search rooted at `/`) walks every mounted drive, not just the repo — it can hang or take minutes.
+  If neither path exists, stop and report it; don't go hunting for the file.

package/bundles/antigravity-plugin-extras/skills/requesting-code-review/SKILL.md

@@ -58,7 +58,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 [Dispatch superpowers:code-reviewer subagent]
   WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  PLAN_OR_REQUIREMENTS: Task 2 from .caddis/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
   DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types

package/bundles/antigravity-plugin-extras/skills/schema-migration/SKILL.md

@@ -24,7 +24,7 @@ Systematically migrate an application from a legacy database schema to a new sch
 1. **Read-Only** — Never execute DDL or DML (`CREATE`, `ALTER`, `INSERT`, `UPDATE`, `DELETE`) against the database. All analysis is SELECT-only.
 2. **No SQL Aliases** — Proposed queries must use direct `Table.Column` notation. Aliases obscure the mapping and make future changes harder to trace.
 3. **No Assumptions** — Every column mapping must be verified against the actual schema DDL. If a mapping is ambiguous or a source column has no clear target, flag it as a **GAP** rather than guessing.
-4. **Scratchpad Protocol** — If context becomes large, save intermediate findings to `.github/plans/temp_migration_scratchpad.md` to preserve state across reasoning steps.
+4. **Scratchpad Protocol** — If context becomes large, save intermediate findings to `.caddis/plans/temp_migration_scratchpad.md` to preserve state across reasoning steps.
 
 ---
 
@@ -255,7 +255,7 @@ Produce a single, comprehensive document suitable for use as an **Implementation
 ```
 
 ### Output Location
-Place the final report at the path specified by the user (default: `.github/plans/backlog/migration_report.md`).
+Place the final report at the path specified by the user (default: `.caddis/agent-docs/migration_report.md` — it is an agent-produced report, not a backlog item).
 
 ---
 

package/bundles/antigravity-plugin-extras/skills/state-tracking/SKILL.md

@@ -23,7 +23,7 @@ State tracking uses two distinct documents with different write semantics:
 
 | Document | Write mode | Purpose |
 |----------|-----------|---------|
-| **Plan Tracker** (`.github/plans/tracker/<slug>-tracker.md`) | Overwrite each row | Per-phase completion record, linked to commits |
+| **Plan Tracker** (`.caddis/plans/tracker/<slug>-tracker.md`) | Overwrite each row | Per-phase completion record, linked to commits |
 | **CURRENT_STATE** (`.github/agent-docs/CURRENT_STATE.md`) | Overwrite head section | Single-view of right now: what phase, what's done, what's blocked |
 | **Session Log** (inline in CURRENT_STATE, append-only) | Append only | Chronological audit trail — never rewrite past entries |
 
@@ -42,8 +42,8 @@ Replace this section wholesale each time:
 ```markdown
 ## Current Status
 
-**Plan:** `.github/plans/<feature-slug>.md`
-**Tracker:** `.github/plans/tracker/<feature-slug>-tracker.md`
+**Plan:** `.caddis/plans/<feature-slug>.md`
+**Tracker:** `.caddis/plans/tracker/<feature-slug>-tracker.md`
 **Last updated:** YYYY-MM-DDTHH:MM:SSZ
 **Active agent:** @[Agent] (model: [Model])
 **Current phase:** Phase N — [Name]
@@ -116,7 +116,7 @@ The canonical template is at `.github/agent-docs/CURRENT_STATE.md`. Copy it for
 ## Integration with Golden-Plan
 
 When running a golden-plan:
-- The plan tracker (`.github/plans/tracker/<slug>-tracker.md`) is the commitment ledger.
+- The plan tracker (`.caddis/plans/tracker/<slug>-tracker.md`) is the commitment ledger.
 - CURRENT_STATE.md is the working scratch-pad for the current session.
 - After completing a phase, update BOTH the tracker row AND the CURRENT_STATE current-status section.
 - When all tracker rows are `Complete`, follow the Plan Completion Protocol in golden-plan: move the plan to `plans/done/`, set `status: done`.

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.54",
+  "poolVersion": "1.3.75",
   "bundles": {
-    "antigravity-plugin": "1.3.54",
-    "antigravity-plugin-extras": "1.3.20"
+    "antigravity-plugin": "1.3.75",
+    "antigravity-plugin-extras": "1.3.24"
   }
 }

package/dist/cli.js

@@ -4527,6 +4527,32 @@ var init_drive = __esm({
   }
 });
 
+// src/util/semver.ts
+function compareVersions(a, b3) {
+  const pa = parse(a);
+  const pb = parse(b3);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+function parse(v) {
+  if (!v || v === "unknown") return null;
+  const core = v.trim().replace(/^v/, "").split(/[-+]/)[0] ?? "";
+  const parts = core.split(".");
+  if (parts.length === 0 || parts.some((p2) => p2 === "" || !/^\d+$/.test(p2))) return null;
+  return parts.map((p2) => Number.parseInt(p2, 10));
+}
+var init_semver = __esm({
+  "src/util/semver.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/report.ts
 async function checkCliUpdate(currentVersion) {
   const result = await run("npm", ["view", "@caddis/cli", "version"], { timeout: 5e3 });
@@ -4541,7 +4567,10 @@ function classify(adapter, detection, status4, poolVersion) {
   if (!status4.installed) return "missing";
   if (!status4.version) return "unknown";
   if (poolVersion === "unknown") return "unknown";
-  return status4.version === poolVersion ? "current" : "stale";
+  const order = compareVersions(status4.version, poolVersion);
+  if (order === null) return status4.version === poolVersion ? "current" : "stale";
+  if (order === 0) return "current";
+  return order > 0 ? "ahead" : "stale";
 }
 async function gather(adapters, options = {}) {
   const manifest = bundleManifest();
@@ -4578,6 +4607,7 @@ function actionable(report, includeCurrent = false) {
   return report.agents.filter((entry) => {
     if (!entry.detection.present || !entry.adapter.supported) return false;
     if (includeCurrent) return true;
+    if (entry.drift === "ahead") return false;
     return entry.drift !== "current" || entry.extrasDrift === "stale" || entry.extrasDrift === "unknown";
   });
 }
@@ -4586,6 +4616,7 @@ var init_report = __esm({
     "use strict";
     init_exec();
     init_pkg();
+    init_semver();
   }
 });
 
@@ -4671,10 +4702,18 @@ async function update(options) {
   const targets = actionable(report, options.force === true);
   if (targets.length === 0) {
     const supportedPresent = report.agents.filter((e2) => e2.detection.present && e2.adapter.supported);
+    const ahead = report.agents.filter((e2) => e2.drift === "ahead");
     line("");
-    line(
-      supportedPresent.length === 0 ? `  ${color.yellow("No supported agent found.")} caddis v0.1 drives Claude Code and agy.` : `  ${color.green("Everything is already current.")} Use --force to re-drive anyway.`
-    );
+    if (supportedPresent.length === 0) {
+      line(`  ${color.yellow("No supported agent found.")} caddis v0.1 drives Claude Code and agy.`);
+    } else if (ahead.length > 0) {
+      line(
+        `  ${color.green("Nothing to do.")} ${ahead.length} agent(s) are NEWER than this package's bundled pool (${report.poolVersion}) \u2014 driving them would be a DOWNGRADE, so they were left alone.`
+      );
+      line(`  Update the CLI itself (${color.cyan("npm i -g @caddis/cli")}), or ${color.cyan("--force")} to roll back deliberately.`);
+    } else {
+      line(`  ${color.green("Everything is already current.")} Use --force to re-drive anyway.`);
+    }
     return 0;
   }
   line("");
@@ -4726,7 +4765,7 @@ function renderEnvironment(report, problems) {
   item("info", `platform ${process2.platform} ${process2.arch} (${os3.release()})`);
   if (report.cliUpdate) {
     item("warn", `@caddis/cli ${report.cliVersion} ${color.dim("\u2192")} ${color.bold(report.cliUpdate.latest)} available`);
-    detail("everything below is compared against the pool THIS install carries, which is now behind the published one");
+    detail('so EVERY "current" below may be wrong \u2014 it only means "matches the pool this install carries"');
     problems.push({
       kind: "problem",
       text: `@caddis/cli itself is behind: ${report.cliUpdate.current} installed, ${report.cliUpdate.latest} published`,
@@ -4805,6 +4844,7 @@ function renderSummary(report, findings) {
 function markFor(drift) {
   switch (drift) {
     case "current":
+    case "ahead":
       return "ok";
     case "stale":
     case "missing":
@@ -4820,6 +4860,8 @@ function describe(entry, poolVersion) {
   switch (entry.drift) {
     case "current":
       return `caddis ${entry.status.version} ${color.dim("(current)")}`;
+    case "ahead":
+      return `caddis ${color.green(entry.status.version ?? "?")} ${color.dim("\u2014 newer than this CLI bundles")} ${color.dim(`(${poolVersion}); left alone, update @caddis/cli to catch up`)}`;
     case "stale":
       return `caddis ${color.yellow(entry.status.version ?? "?")} ${color.dim("\u2192")} ${color.bold(poolVersion)} available`;
     case "unknown":
@@ -4978,7 +5020,15 @@ async function status3(options) {
   }
   line("");
   line(
-    `  ${color.bold("caddis")}  cli ${color.bold(report.cliVersion)}  \xB7  pool ${color.bold(report.poolVersion)}` + (report.extrasVersion ? `  \xB7  extras ${color.bold(report.extrasVersion)}` : "")
+    // The pool is named as the YARDSTICK, in the header, because that is what every verdict below
+    // is measured against and status cannot see the marketplace — it is deliberately network-free.
+    // A tool that cannot know something must not print a verdict that implies it does.
+    //
+    // Deliberately NOT a footer line. The first attempt added one, and it broke the existing
+    // "stays quiet when everything is current" test — correctly: a qualifier phrased like a warning
+    // fires on every healthy run, and a warning that always fires is the one nobody reads. doctor
+    // carries the strong version, because doctor is where the network check actually happens.
+    `  ${color.bold("caddis")}  cli ${color.bold(report.cliVersion)}  \xB7  pool ${color.bold(report.poolVersion)} ${color.dim('(what "current" is measured against)')}` + (report.extrasVersion ? `  \xB7  extras ${color.bold(report.extrasVersion)}` : "")
   );
   line("");
   line(renderTable(["AGENT", "DETECTED", "CADDIS", "EXTRAS", "STATE"], report.agents.map(toRow)));
@@ -4986,10 +5036,17 @@ async function status3(options) {
   const stale = report.agents.filter(
     (entry) => entry.drift === "stale" || entry.drift === "missing" || entry.extrasDrift === "stale"
   );
+  const ahead = report.agents.filter((entry) => entry.drift === "ahead");
   if (stale.length > 0) {
     line(`  ${color.yellow(`${stale.length} agent(s) behind`)} \u2014 run ${color.cyan("caddis update")} (or ${color.cyan("caddis doctor")} for detail)`);
     line("");
   }
+  if (ahead.length > 0) {
+    line(
+      `  ${ahead.length} agent(s) are NEWER than this CLI's bundled pool (${report.poolVersion}) \u2014 left alone. Update the CLI itself (${color.cyan("npm i -g @caddis/cli")}) to catch up.`
+    );
+    line("");
+  }
   return 0;
 }
 function toRow(entry) {
@@ -5010,6 +5067,8 @@ function stateLabel(drift, disabled) {
       return disabled ? color.yellow("current, disabled") : color.green("current");
     case "stale":
       return color.yellow("update available");
+    case "ahead":
+      return color.green("newer than CLI pool");
     case "unknown":
       return color.yellow("version unknown");
     case "missing":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",