@caddis/cli 0.4.50 → 0.4.52

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.136",
+  "version": "1.3.138",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/caddis_routing.py

@@ -14,6 +14,10 @@ from typing import Callable, Mapping
 import oss_model
 
 
+# agy is Flash-only on some machines and is good only at small, exact, mechanical cards (112 of 114 passed
+# in the 2026-10-08 UI-upgrade run) and CI watching. Give design-fidelity, cross-file refactor and judgment
+# work to codex or claude. See .caddis/kb/agy-headless-implementer-limits.md. A separate `design` role is an
+# owner decision: it changes the routing line every session prints.
 DEFAULT_ROUTING: dict[str, list[str]] = {
     "critical": ["opus"],
     "light": ["sonnet"],

package/bundles/antigravity-plugin/scripts/setup_project_ai.py

@@ -689,7 +689,49 @@ if [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
     echo "[gate] interpreter: $PY"
     py_gate ruff check .
     if py_sources_exist; then py_gate mypy .; else echo "[skip] mypy: no Python sources"; fi
-    py_gate pytest -q
+    # pytest is OPT-IN here (CADDIS_GATE_PYTEST=1). Found 2026-10-10: the full suite took 25-31 min in this
+    # hook on a box whose system disk was slow, while CI ran the same suite in 5 min - and a merge needs green
+    # CI anyway. A local gate five times slower than the check it stands in for trains people to --no-verify it.
+    # When it does run: CADDIS_GATE_TMP moves TMPDIR/TEMP/TMP (tests write to tmp_path; Python reads TMPDIR
+    # first, so set all three), CADDIS_GATE_PYTEST_ARGS adds arguments (for example "-n 4" with pytest-xdist;
+    # use a number, not "auto"), and a machine-wide lock (CADDIS_GATE_LOCK, mkdir-based, waits up to
+    # CADDIS_GATE_LOCK_WAIT seconds, a stale one is taken over after 60 min) lets only ONE pytest gate run at a time, so several repos pushing together cannot
+    # pile their suites on the same disk and CI runners.
+    if [ "${CADDIS_GATE_PYTEST:-0}" = "1" ]; then
+      if [ -n "${CADDIS_GATE_TMP:-}" ]; then
+        mkdir -p "$CADDIS_GATE_TMP" 2>/dev/null || true
+        export TMPDIR="$CADDIS_GATE_TMP" TEMP="$CADDIS_GATE_TMP" TMP="$CADDIS_GATE_TMP"
+      fi
+      LOCK="${CADDIS_GATE_LOCK:-${TMPDIR:-${TEMP:-/tmp}}/caddis-pytest-gate.lock}"
+      mkdir -p "$(dirname "$LOCK")" 2>/dev/null || true
+      lock_wait="${CADDIS_GATE_LOCK_WAIT:-1800}"
+      waited=0
+      got_lock=0
+      while :; do
+        if mkdir "$LOCK" 2>/dev/null; then got_lock=1; break; fi
+        # A stale lock is removed, then this round still sleeps and counts: if the removal fails (a lock owned
+        # by another user), the loop ends at lock_wait instead of spinning forever.
+        if [ -n "$(find "$LOCK" -maxdepth 0 -mmin +60 2>/dev/null)" ]; then
+          rmdir "$LOCK" 2>/dev/null || true
+        fi
+        if [ "$waited" -ge "$lock_wait" ]; then break; fi
+        if [ "$waited" -eq 0 ]; then echo "[gate] pytest: waiting for another repo's pytest gate ($LOCK)"; fi
+        sleep 1
+        waited=$((waited + 1))
+      done
+      if [ "$got_lock" -eq 1 ]; then
+        trap 'rmdir "$LOCK" 2>/dev/null || true' EXIT INT TERM
+        # shellcheck disable=SC2086  # CADDIS_GATE_PYTEST_ARGS is meant to word-split
+        py_gate pytest -q ${CADDIS_GATE_PYTEST_ARGS:-}
+        rmdir "$LOCK" 2>/dev/null || true
+        trap - EXIT INT TERM
+      else
+        echo "[gate] pytest: another pytest gate holds $LOCK for over ${lock_wait}s - cannot run, so the gate fails" >&2
+        fail=1
+      fi
+    else
+      echo "[skip] pytest: runs in CI (set CADDIS_GATE_PYTEST=1 to run it here)"
+    fi
   fi
 fi
 if [ -f "package.json" ] && command -v npm >/dev/null 2>&1; then

package/bundles/antigravity-plugin/session_end_agy.py

@@ -19,6 +19,7 @@ agy Stop stdin (camelCase protojson):
 """
 import json
 import os
+import subprocess
 import sys
 from datetime import datetime, timezone
 
@@ -27,6 +28,30 @@ def _artifact_root(root: str) -> str:
     return os.path.join(str(root), ".caddis")
 
 
+def _repo_root(path: str):
+    """The git top-level folder that holds `path`, or None when `path` is not inside a repository.
+
+    agy can run with its working folder in a SUB-folder of the repo (a monorepo app). The artifact
+    folder belongs at the repo root, where the project's ignore rule (`/.caddis/`) covers it. Creating
+    it in the sub-folder left untracked files that every lane had to delete before staging
+    (UI-upgrade run, 2026-10-08).
+    """
+    try:
+        done = subprocess.run(
+            ["git", "-C", str(path), "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=5,
+        )
+        top = done.stdout.strip()
+        return os.path.normpath(top) if done.returncode == 0 and top else None
+    except Exception:
+        return None
+
+
+def _user_artifact_root() -> str:
+    """Where usage goes when the workspace is in no repository: the user's own folder, never the cwd."""
+    return _artifact_root(os.path.expanduser("~"))
+
+
 
 def _hook_note(feature, exc, root=None):
     """Record a swallowed failure in the caddis hook ledger. Never raises, never prints.
@@ -82,13 +107,22 @@ def main() -> None:
         return
     try:
         roots = _workspace_roots(data) or [os.getcwd()]
+        # A workspace folder may sit inside a repo: the artifact dir is the REPO ROOT's, not the sub-folder's.
+        resolved = [(_repo_root(r) or str(r)) for r in roots]
         # Write the record to every root that ALREADY has a .caddis dir, rather than to
         # whichever root happened to be first. A multi-root session's usage belongs to each
         # repo that participates in it, and creating .caddis in a repo that never opted in
         # would be caddis littering someone else's tree.
-        targets = [_artifact_root(r) for r in roots if os.path.isdir(_artifact_root(r))]
+        targets = []
+        for root in resolved:
+            art = _artifact_root(root)
+            if os.path.isdir(art) and art not in targets:
+                targets.append(art)
         if not targets:
-            targets = [_artifact_root(roots[0])]  # single-root default: unchanged behaviour
+            # Nothing has opted in. In a repo, the first root's repo root is the default. Outside any
+            # repo there is no project to attach usage to, so it goes to the user's folder, not the cwd.
+            first_repo = _repo_root(roots[0])
+            targets = [_artifact_root(first_repo) if first_repo else _user_artifact_root()]
         record = {
             "ts": datetime.now(timezone.utc).isoformat(),
             "event": "session_end",

package/bundles/antigravity-plugin/skills/flow-studio/SKILL.md

@@ -70,7 +70,9 @@ In either route, derive node and link IDs from immutable business keys. Preserve
 8. **Short titles**: titles fit one line at column width. Long descriptions belong in subtitles or member lists.
 9. **Fixed node dimensions**: node kinds use fixed box sizes so font rendering does not shift layout.
 10. **Reduced motion**: removes all animations while preserving static borders and status glows.
-11. **Thin links, dotted canvas**: links are hairlines (about 0.8 px, with a 6 px arrowhead) and the canvas background is faint dots, not a grid. Both come from tokens (`--edge-w`, `--dot`, ...), so an app can change them with one CSS line; see `references/design-language.md`.
+11. **The lane is the owner**: a lane is the app, team or system that owns its row. Never add a column that repeats the owner (an "Apps" or "Owner" column); it adds a block between the real stages and the pages and says nothing new.
+12. **Draw a shared node once**: when several rows use the same database, job or table, draw one node, centre it on the rows it serves, and link it to each node downstream. A chip (`kind: "chip"` with `ref`) is only for a node that lives in another lane, never a copy inside the same lane.
+13. **Thin links, dotted canvas**: links are hairlines (about 0.8 px, with a 6 px arrowhead) and the canvas background is faint dots, not a grid. Both come from tokens (`--edge-w`, `--dot`, ...), so an app can change them with one CSS line; see `references/design-language.md`.
 
 ## Model summary
 

package/bundles/antigravity-plugin/skills/flow-studio/references/patterns.md

@@ -21,7 +21,7 @@ You can start from these base states and adjust words to match your domain:
 
 - **Example file:** `examples/lineage.json`
 - **Scenario:** Trace data assets from ingestion sources through storage, pipelines, transformations, to consuming dashboards and applications.
-- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, App, Dashboard.
+- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, Dashboard. Do not add an App or Owner column: the lane is the app (ux-rules 11).
 - **Typical lanes:** Customer Portal, Order Service, Data Warehouse, Reporting Platform. A lane without documentation uses `gap: true`.
 - **Node count guideline:** 15 to 30 nodes.
 - **Recommended inspector relations:**

package/bundles/antigravity-plugin/skills/flow-studio/references/ux-rules.md

@@ -1,8 +1,8 @@
 # UX and design rules
 
-The 10 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
+The 12 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
 
-## The 10 rules
+## The 12 rules
 
 ### 1. One screen
 - **Rule statement:** The full flow fits on one screen without requiring panning in the initial default view.
@@ -66,6 +66,20 @@ The 10 rules ensure flow-studio pages remain readable, informative, accessible,
 
 ---
 
+### 11. The lane is the owner
+- **Rule statement:** A lane names the app, team or system that owns its row. No column repeats the owner.
+- **Rationale:** An "Apps" column between the real stages and the pages adds a block that says nothing new. In the estate lineage it sat between the reporting tables and the pages, and the owner asked why it was there (2026-10-09).
+- **Pre-flight checklist question:** Does any column hold one node per lane that only repeats the lane title?
+- **Common mistake & fix:** Adding an "App" column because the pattern list showed one. *Fix:* Remove the column. Link the stage that feeds a page straight to the page; a page that reads no table stands alone.
+
+### 12. Draw a shared node once
+- **Rule statement:** A database, job or table that several rows share is one node, centred on the rows it serves, with a link to each node downstream. A chip is only for a node that lives in another lane.
+- **Rationale:** Copying a shared node into every row hides that it is shared and makes the reader compare copies. In the app lineage page, a database repeated in every source row looked like several databases (2026-10-09).
+- **Pre-flight checklist question:** Does any node id appear as a chip inside the lane that already holds the real node?
+- **Common mistake & fix:** One row per source, each with its own copy of the host, database and job. *Fix:* Draw each distinct node once, place it at the mean position of its rows, move it down if it would touch its neighbour, and de-duplicate links by their two ends.
+
+---
+
 ## Pre-flight checklist for agents
 
 Before presenting a generated flow page, verify:
@@ -77,6 +91,8 @@ Before presenting a generated flow page, verify:
 6. **Accessible names:** Does every button, input, tab, and control have an `aria-label` or visible text?
 7. **Keyboard navigation:** Can a user Tab through controls and press Escape to close the inspector?
 8. **Responsive breakdown:** Does the layout degrade cleanly down to 820x900?
+9. **No owner column:** Does any column only repeat the lane's owner? Remove it (rule 11).
+10. **Shared nodes once:** Is every shared database, job or table drawn once, not copied per row (rule 12)?
 
 ---
 
@@ -88,4 +104,6 @@ Before presenting a generated flow page, verify:
 - **Text spill:** Node labels exceed card width. *Fix:* Use short titles (under 24 characters) and set `subtitle` for auxiliary metadata.
 - **Permanent side panel:** The inspector remains open on load. *Fix:* The inspector must start closed and open only on selection.
 - **Flat visual hierarchy:** Every card looks identical. *Fix:* Vary card kinds (`card`, `group`, `gateway`, `chip`) and state tones (`ok`, `warn`, `crit`, `accent`).
+- **Owner column:** A column of one node per lane that repeats the lane title. *Fix:* Remove it; the lane is the owner.
+- **Copies of a shared node:** The same database or job drawn in every row. *Fix:* Draw it once and link it to each node downstream.
 - **Unlabelled controls:** Icon buttons without text lack screen reader descriptions. *Fix:* Provide descriptive `aria-label` attributes on all buttons.

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

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.41",
+  "version": "1.3.42",
   "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

@@ -649,3 +649,41 @@ The methodology in this document was extracted from a real multi-agent UI-polish
 | Debug | 7 issues catalogued (A–G) | Fix-up plan created |
 
 This end-to-end cycle took **~10 sessions** with full artefact trail and zero rework of fundamental design decisions.
+
+
+---
+
+## agy as an implementer: what was measured (2026-10-08)
+
+A 17-hour run with 14 lanes used agy (Antigravity) as the main implementer. Details: `.caddis/kb/agy-headless-implementer-limits.md` in the caddis source repo. Read the rule first, then the evidence.
+
+**Rule:** send agy only small, exact, mechanical cards, test fixes and CI watching. Send design-fidelity work, cross-file refactors and judgment to Codex or Claude. Give Opus only short contract-sized tasks.
+
+**Why (measured):**
+- On that machine only the Flash models worked. `gemini-3.1-pro-high` failed with "not supported in the selected location".
+- Small exact cards: 112 of 114 passed. A card to port an app shell from screenshots ran 40 minutes and changed one icon file.
+- In `--print` mode agy started the full test suite as a background task and waited for a notification that never came (35 to 40 minutes lost, twice).
+- On narrow gates it invented statuses, counts and names. 11 of 14 lanes needed up to 3 review rounds.
+
+### The agy card template
+
+Every card that goes to agy has these sections. A card without them is not ready.
+
+1. `## Goal`: one sentence, one component or one page.
+2. `## Files`: a bullet list of every file the card may touch. The gate rejects any change outside it.
+3. `## Tests first`: the failing tests to write before the code, and the one targeted command that runs them.
+4. `## Rules for agy` (copy this block as it is):
+   - Edit first. Run foreground commands only.
+   - Never start a background task. Never wait for a notification.
+   - Never run the full test suite. The orchestrator gate runs it.
+   - No invented data: no made-up statuses, counts, names or sign-offs. If a fact is missing, say so in the card result.
+   - No fake controls. Do not remove a feature to make a test pass.
+   - Codes go through the shared formatter.
+5. `## Done when`: the exact observable result, and "report what you changed and what you could not do".
+
+### Orchestrator rules from the same run
+
+- The gate runs the full suite, requires that a NEW commit exists, and stages only source folders.
+- Restore known-noisy files (CRLF snapshot rewrites, screenshots) before checking for changes.
+- Do not let Codex `-s workspace-write` run builds. Files it creates are owned by a sandbox user and can block worktree removal.
+- Do not run `caddis-push` or `caddis update` while any `agy.exe` runs. The release now refuses or skips in that case.

package/bundles/codex/.codex/skills/frontend/flow-studio/SKILL.md

@@ -70,7 +70,9 @@ In either route, derive node and link IDs from immutable business keys. Preserve
 8. **Short titles**: titles fit one line at column width. Long descriptions belong in subtitles or member lists.
 9. **Fixed node dimensions**: node kinds use fixed box sizes so font rendering does not shift layout.
 10. **Reduced motion**: removes all animations while preserving static borders and status glows.
-11. **Thin links, dotted canvas**: links are hairlines (about 0.8 px, with a 6 px arrowhead) and the canvas background is faint dots, not a grid. Both come from tokens (`--edge-w`, `--dot`, ...), so an app can change them with one CSS line; see `references/design-language.md`.
+11. **The lane is the owner**: a lane is the app, team or system that owns its row. Never add a column that repeats the owner (an "Apps" or "Owner" column); it adds a block between the real stages and the pages and says nothing new.
+12. **Draw a shared node once**: when several rows use the same database, job or table, draw one node, centre it on the rows it serves, and link it to each node downstream. A chip (`kind: "chip"` with `ref`) is only for a node that lives in another lane, never a copy inside the same lane.
+13. **Thin links, dotted canvas**: links are hairlines (about 0.8 px, with a 6 px arrowhead) and the canvas background is faint dots, not a grid. Both come from tokens (`--edge-w`, `--dot`, ...), so an app can change them with one CSS line; see `references/design-language.md`.
 
 ## Model summary
 

package/bundles/codex/.codex/skills/frontend/flow-studio/references/patterns.md

@@ -21,7 +21,7 @@ You can start from these base states and adjust words to match your domain:
 
 - **Example file:** `examples/lineage.json`
 - **Scenario:** Trace data assets from ingestion sources through storage, pipelines, transformations, to consuming dashboards and applications.
-- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, App, Dashboard.
+- **Typical columns:** Source, Host, Database, Pipeline, Tables, Refresher, Views, Dashboard. Do not add an App or Owner column: the lane is the app (ux-rules 11).
 - **Typical lanes:** Customer Portal, Order Service, Data Warehouse, Reporting Platform. A lane without documentation uses `gap: true`.
 - **Node count guideline:** 15 to 30 nodes.
 - **Recommended inspector relations:**

package/bundles/codex/.codex/skills/frontend/flow-studio/references/ux-rules.md

@@ -1,8 +1,8 @@
 # UX and design rules
 
-The 10 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
+The 12 rules ensure flow-studio pages remain readable, informative, accessible, and fast.
 
-## The 10 rules
+## The 12 rules
 
 ### 1. One screen
 - **Rule statement:** The full flow fits on one screen without requiring panning in the initial default view.
@@ -66,6 +66,20 @@ The 10 rules ensure flow-studio pages remain readable, informative, accessible,
 
 ---
 
+### 11. The lane is the owner
+- **Rule statement:** A lane names the app, team or system that owns its row. No column repeats the owner.
+- **Rationale:** An "Apps" column between the real stages and the pages adds a block that says nothing new. In the estate lineage it sat between the reporting tables and the pages, and the owner asked why it was there (2026-10-09).
+- **Pre-flight checklist question:** Does any column hold one node per lane that only repeats the lane title?
+- **Common mistake & fix:** Adding an "App" column because the pattern list showed one. *Fix:* Remove the column. Link the stage that feeds a page straight to the page; a page that reads no table stands alone.
+
+### 12. Draw a shared node once
+- **Rule statement:** A database, job or table that several rows share is one node, centred on the rows it serves, with a link to each node downstream. A chip is only for a node that lives in another lane.
+- **Rationale:** Copying a shared node into every row hides that it is shared and makes the reader compare copies. In the app lineage page, a database repeated in every source row looked like several databases (2026-10-09).
+- **Pre-flight checklist question:** Does any node id appear as a chip inside the lane that already holds the real node?
+- **Common mistake & fix:** One row per source, each with its own copy of the host, database and job. *Fix:* Draw each distinct node once, place it at the mean position of its rows, move it down if it would touch its neighbour, and de-duplicate links by their two ends.
+
+---
+
 ## Pre-flight checklist for agents
 
 Before presenting a generated flow page, verify:
@@ -77,6 +91,8 @@ Before presenting a generated flow page, verify:
 6. **Accessible names:** Does every button, input, tab, and control have an `aria-label` or visible text?
 7. **Keyboard navigation:** Can a user Tab through controls and press Escape to close the inspector?
 8. **Responsive breakdown:** Does the layout degrade cleanly down to 820x900?
+9. **No owner column:** Does any column only repeat the lane's owner? Remove it (rule 11).
+10. **Shared nodes once:** Is every shared database, job or table drawn once, not copied per row (rule 12)?
 
 ---
 
@@ -88,4 +104,6 @@ Before presenting a generated flow page, verify:
 - **Text spill:** Node labels exceed card width. *Fix:* Use short titles (under 24 characters) and set `subtitle` for auxiliary metadata.
 - **Permanent side panel:** The inspector remains open on load. *Fix:* The inspector must start closed and open only on selection.
 - **Flat visual hierarchy:** Every card looks identical. *Fix:* Vary card kinds (`card`, `group`, `gateway`, `chip`) and state tones (`ok`, `warn`, `crit`, `accent`).
+- **Owner column:** A column of one node per lane that repeats the lane title. *Fix:* Remove it; the lane is the owner.
+- **Copies of a shared node:** The same database or job drawn in every row. *Fix:* Draw it once and link it to each node downstream.
 - **Unlabelled controls:** Icon buttons without text lack screen reader descriptions. *Fix:* Provide descriptive `aria-label` attributes on all buttons.

package/bundles/manifest.json

@@ -1,8 +1,8 @@
 {
-  "poolVersion": "1.3.136",
+  "poolVersion": "1.3.138",
   "bundles": {
-    "antigravity-plugin": "1.3.136",
-    "antigravity-plugin-extras": "1.3.41",
+    "antigravity-plugin": "1.3.138",
+    "antigravity-plugin-extras": "1.3.42",
     "codex": "unknown"
   }
 }

package/dist/cli.js

@@ -5761,15 +5761,77 @@ var claudeAdapter = {
 // src/agents/agy.ts
 init_exec();
 init_which();
-init_pkg();
 import { readFileSync as readFileSync2, existsSync as existsSync2, mkdtempSync, cpSync, rmSync } from "fs";
 import os from "os";
 import path2 from "path";
+
+// src/util/agyProcs.ts
+init_exec();
+function parseTasklistCsv(stdout) {
+  const pids = [];
+  for (const line2 of stdout.split(/\r?\n/)) {
+    const match = /^"agy\.exe","(\d+)"/i.exec(line2.trim());
+    if (match) pids.push(Number(match[1]));
+  }
+  return pids;
+}
+function parsePgrep(stdout) {
+  return stdout.split(/\r?\n/).map((line2) => line2.trim()).filter((line2) => /^\d+$/.test(line2)).map(Number);
+}
+async function listAgyPids() {
+  if (process.platform === "win32") {
+    const result2 = await run("tasklist", ["/FI", "IMAGENAME eq agy.exe", "/FO", "CSV", "/NH"], { timeout: 2e4 });
+    return result2.ok ? parseTasklistCsv(result2.stdout) : [];
+  }
+  const result = await run("pgrep", ["-x", "agy"], { timeout: 1e4 });
+  return result.ok ? parsePgrep(result.stdout) : [];
+}
+
+// src/agents/agy.ts
+init_pkg();
 var BIN2 = "agy";
 var BUNDLE = "antigravity-plugin";
 var PLUGIN2 = "caddis";
 var EXTRAS_BUNDLE = "antigravity-plugin-extras";
 var EXTRAS_PLUGIN = "caddis-extras";
+var REQUIRED_PLUGIN_FILES = ["plugin.json", "hooks.json", "guard_agy.py"];
+var ALLOW_RUNNING_ENV = "CADDIS_AGY_ALLOW_RUNNING";
+function pluginDirFor(home = os.homedir(), plugin = PLUGIN2) {
+  return path2.join(home, ".gemini", "config", "plugins", plugin);
+}
+function missingPluginFiles(home = os.homedir()) {
+  const dir = pluginDirFor(home);
+  return REQUIRED_PLUGIN_FILES.filter((file) => !existsSync2(path2.join(dir, file)));
+}
+function backupInstalledPlugin(home) {
+  const dir = pluginDirFor(home);
+  if (!existsSync2(dir)) return null;
+  const holder = mkdtempSync(path2.join(os.tmpdir(), "caddis-agy-backup-"));
+  const copy = path2.join(holder, PLUGIN2);
+  cpSync(dir, copy, { recursive: true });
+  let keep = false;
+  return {
+    location: copy,
+    // Returns null when the old plugin is back, else the reason it could not be put back.
+    restore: () => {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+        cpSync(copy, dir, { recursive: true });
+        return null;
+      } catch (error) {
+        keep = true;
+        return error instanceof Error ? error.message : String(error);
+      }
+    },
+    cleanup: () => {
+      if (keep) return;
+      try {
+        rmSync(holder, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  };
+}
 function pluginManifestPath(home = os.homedir(), plugin = PLUGIN2) {
   return path2.join(home, ".gemini", "config", "plugins", plugin, "plugin.json");
 }
@@ -5890,7 +5952,21 @@ async function drive2(_action, options) {
       message: "dry run \u2014 nothing executed"
     };
   }
+  if (process.env[ALLOW_RUNNING_ENV] !== "1") {
+    const running = await listAgyPids();
+    if (running.length > 0) {
+      return {
+        ok: false,
+        skipped: false,
+        steps: [],
+        message: `agy is running (PID ${running.join(", ")}). Installing now can empty the caddis plugin under it, and agy then refuses every edit. Stop agy and run this again, or set ${ALLOW_RUNNING_ENV}=1 if you know no agy holds the plugin folder.`
+      };
+    }
+  }
+  const home = options.home ?? os.homedir();
+  const backup = backupInstalledPlugin(home);
   const cleanups = [];
+  if (backup) cleanups.push(backup.cleanup);
   try {
     const steps3 = [];
     for (const step of planned) {
@@ -5899,6 +5975,23 @@ async function drive2(_action, options) {
       cleanups.push(staged.cleanup);
       const execArgs = [...step.args.slice(0, -1), staged.installPath];
       const result = await run(step.cmd, execArgs);
+      if (step.bundleDir === bundle) {
+        const missing = missingPluginFiles(home);
+        if (missing.length > 0) {
+          let outcome = "there was nothing to restore";
+          if (backup) {
+            const failure = backup.restore();
+            outcome = failure === null ? "the previous plugin was restored" : `the restore FAILED (${failure}); the old plugin is kept at ${backup.location}`;
+          }
+          steps3.push({ command, ok: false, code: result.code, output: `missing after the install: ${missing.join(", ")}` });
+          return {
+            ok: false,
+            skipped: false,
+            steps: steps3,
+            message: `the caddis plugin is incomplete after the install (missing ${missing.join(", ")}); ` + outcome
+          };
+        }
+      }
       steps3.push({
         command,
         ok: result.ok,

package/package.json

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