@caddis/cli 0.3.0 → 0.4.1

package/bundles/antigravity-plugin/warm_start_agy.py

@@ -150,6 +150,63 @@ def _hook_note(feature, exc, root=None):
     except Exception:
         pass
 
+
+
+def _injected_marker(root, conversation):
+    """Path of the per-conversation "relay already injected" marker, or None."""
+    try:
+        safe = "".join(c for c in str(conversation) if c.isalnum() or c in "-_")[:64]
+        if not safe:
+            return None
+        return os.path.join(str(root), ".caddis", ".relay-injected", safe)
+    except Exception:
+        return None
+
+
+def _already_injected(root, conversation):
+    """True when this conversation has had its relay injected before. Fail-open: on any
+    error return False, because a duplicate relay is a smaller harm than none at all."""
+    try:
+        marker = _injected_marker(root, conversation)
+        return bool(marker) and os.path.isfile(marker)
+    except Exception:
+        return False
+
+
+def _mark_injected(root, conversation):
+    """Record that this conversation received its relay. Never raises.
+
+    A failure here means the next truncation may re-inject — the pre-2026-08-22 behaviour,
+    which is exactly the fail-open direction we want.
+    """
+    try:
+        marker = _injected_marker(root, conversation)
+        if not marker:
+            return
+        os.makedirs(os.path.dirname(marker), exist_ok=True)
+        with open(marker, "w", encoding="utf-8") as fh:
+            fh.write("")
+    except Exception as _exc:
+        _hook_note("agy relay injection marker", _exc, root)
+
+def _workspace_roots(data):
+    """Every workspace root in the payload, as a list. Empty when the payload has none.
+
+    agy sends `workspacePaths` as a LIST. All three caddis agy hooks used to read
+    `workspacePaths[0]` and treat it as "the workspace" — silently, with no signal that a
+    choice had been made. In a single-root workspace that is correct and the behaviour here
+    is unchanged. In a MULTI-root workspace it is a coin toss: the hook acts on the first
+    root regardless of which one the session is actually working in.
+
+    Nothing on this machine is multi-root today, so this has never fired. It is a live trap
+    for exactly the multi-repo workspaces the leakage investigation was about, which is why
+    each caller below now handles the list rather than assuming its first element.
+    """
+    roots = data.get("workspacePaths") if isinstance(data, dict) else None
+    if not isinstance(roots, list):
+        return []
+    return [str(r) for r in roots if isinstance(r, (str, bytes)) and str(r).strip()]
+
 def main() -> None:
     try:
         _reconfig = getattr(sys.stdout, "reconfigure", None)
@@ -173,17 +230,47 @@ def main() -> None:
             return
         if is_headless():
             return
-        workspaces = data.get("workspacePaths") or []
-        if not (isinstance(workspaces, list) and workspaces):
+        roots = _workspace_roots(data)
+        if not roots:
             return
-        root = str(workspaces[0])
-        relay = resolve_relay(root)
-        if not relay:
-            return
-        text = open(relay, encoding="utf-8").read().strip()
-        if not text:
+
+        # DOUBLE-INJECTION GUARD (2026-08-22). The gate above is `invocationNum == 0`, and
+        # agy RESTARTS invocation numbering after a CHECKPOINT truncation. A long session
+        # therefore hits invocation 0 a second time mid-conversation and injected the relay
+        # again — observed at steps 53 and 56 of one transcript, after a truncation at 50.
+        # A relay injected mid-task is worse than noise: it carries a "next step" from a
+        # PREVIOUS session, and that has been seen executed in place of the real prompt.
+        #
+        # Conversation ids are unique per session, so a marker file per id is enough. Stale
+        # markers are harmless — they only ever suppress a re-injection into a conversation
+        # that already received one.
+        conversation = str(data.get("conversationId") or "").strip()
+
+        blocks = []
+        for root in roots:
+            relay = resolve_relay(root)
+            if not relay:
+                continue
+            try:
+                text = open(relay, encoding="utf-8").read().strip()
+            except Exception as _exc:
+                _hook_note("agy relay read", _exc, root)
+                continue
+            if not text:
+                continue
+            if conversation and _already_injected(root, conversation):
+                continue
+            # Label the block ONLY when there is more than one root. A single-root session
+            # must produce byte-identical output to before this change.
+            if len(roots) > 1:
+                blocks.append("relay for " + os.path.basename(root.rstrip("/\\")) + ":")
+            blocks.append(truncate_relay(text))
+            if conversation:
+                _mark_injected(root, conversation)
+
+        if not blocks:
             return
-        message = (RELAY_FRAME_HEADER + "\n" + truncate_relay(text)
+        message = (RELAY_FRAME_HEADER + "\n" + "\n\n".join(blocks)
                    + "\n\n" + RELAY_FRAME_FOOTER)
         payload = json.dumps({"injectSteps": [{"ephemeralMessage": message}]})
         sys.stdout.write(payload)

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

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.25",
+  "version": "1.3.27",
   "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/_registry.md

@@ -51,6 +51,7 @@
 | Changelog Generator | `changelog-generator/` | Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation. |
 | Deploy Local | `deploy-local/` | End-to-end local deployment loop for Gitea-hosted projects. Use when the user wants to commit on dev, push to remote, monitor the golden CI/build/deploy workflow, validate prod on the configured prod host, and fix lint/test/pipeline failures until deployment is healthy. |
 | Monorepo | `monorepo/` | Monorepo management with Turborepo and pnpm workspaces. Use for Turborepo setup, turbo.json task dependencies, remote caching, pnpm workspace protocol, shared packages (ui-library, config, types), affected-only CI/CD builds, or monorepo structure (apps/ vs packages/). Covers pitfalls like circular deps, version drift, and hoisting issues. |
+| Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
 | Update Readme | `update-readme/` | Detect feature commits and update README sections (Features, API, Usage) with accurate repo-aware changes, then stage only README for a docs commit. Use when users add features/routes/components and want README maintained automatically. |
 
 ### Docs

package/bundles/antigravity-plugin-extras/skills/safe-cleanup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```
+
+## Reference implementation
+
+The estate this skill came from keeps working tools at `.caddis/tools/`:
+
+- `venv-audit.py` - imports every dependency each `pyproject.toml` declares
+- `rebuild-venv.ps1` - renames aside, rebuilds, restarts services, refuses on links or live processes
+- `README-venv-safety.md` - the incident record
+
+Adapt rather than copy: the rules matter more than the scripts.

package/bundles/codex/.codex/config.toml.example

@@ -0,0 +1,36 @@
+# Codex CLI configuration example
+# Copy to ~/.codex/config.toml  (user-level, all projects)
+#       or <project>/.codex/config.toml  (project-level; project must be trusted)
+#
+# Add a server interactively: codex mcp add <name> -- <command> [args...]
+# Verify loaded servers:      codex mcp list
+
+# ── Model (adjust to your OpenAI tier) ───────────────────────────────────────
+# model = "codex-mini-latest"
+
+# ── Skills ────────────────────────────────────────────────────────────────────
+# Project skills:  <project>/.codex/skills/<category>/<name>/SKILL.md
+# User skills:     ~/.codex/skills/<name>/SKILL.md  (no category subdir)
+# (Paths probed from codex 0.137 — see docs/analysis/codex-cli-contract.md.
+#  .agents/ is codex's PLUGINS root, not a skills root.)
+#
+# Disable a skill without deleting it:
+# [[skills.config]]
+# path = ".codex/skills/devops/windows-deployment"
+# enabled = false
+
+# ── junai MCP (pipeline state + project context) ─────────────────────────────
+# OFF by default. The junai MCP server tracks pipeline stage and project state
+# across sessions. Enable when the server is available locally.
+#
+# Prerequisites:
+#   pip install junai-mcp   (or: uv tool install junai-mcp)
+#   codex mcp add junai -- python -m junai_mcp --project-root .
+#
+# Or add the block below manually and run `codex mcp list` to confirm:
+#
+# [[mcp_servers]]
+# name = "junai"
+# command = "python"
+# args = ["-m", "junai_mcp", "--project-root", "."]
+# env = {}

package/bundles/codex/.codex/skills/coding/api-design/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: api-design
+description: REST and GraphQL API design patterns. Use when designing new API endpoints, defining resource schemas, planning versioning strategies, or reviewing API contracts. Covers naming conventions, pagination, filtering, error responses, and OpenAPI documentation.
+---
+
+# API Design Skill
+
+Design APIs that are consistent, discoverable, and hard to misuse. Conventions over configuration.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Designing new API endpoints or a full API surface
+- "What should this endpoint look like?"
+- Planning API versioning or migration
+- Reviewing API contracts for consistency
+- Building an API spec or OpenAPI document
+
+## 2. REST Resource Naming
+
+### URL Convention
+
+```
+# Resources are nouns, plural, lowercase, kebab-case
+GET    /api/v1/customers                  # List
+GET    /api/v1/customers/{id}             # Get one
+POST   /api/v1/customers                  # Create
+PUT    /api/v1/customers/{id}             # Full update
+PATCH  /api/v1/customers/{id}             # Partial update
+DELETE /api/v1/customers/{id}             # Delete
+
+# Nested resources for strong ownership
+GET    /api/v1/customers/{id}/orders      # Customer's orders
+POST   /api/v1/customers/{id}/orders      # Create order for customer
+
+# Actions (when CRUD doesn't fit) — verb suffix
+POST   /api/v1/orders/{id}/cancel         # Action on resource
+POST   /api/v1/reports/generate           # Trigger async operation
+```
+
+### Naming Rules
+
+| Rule | Good | Bad |
+|------|------|-----|
+| Plural nouns | `/customers` | `/customer`, `/getCustomers` |
+| Kebab-case | `/order-items` | `/orderItems`, `/order_items` |
+| No verbs in path | `/customers` (POST = create) | `/createCustomer` |
+| Consistent nesting depth | Max 2 levels: `/customers/{id}/orders` | `/customers/{id}/orders/{id}/items/{id}/details` |
+| No trailing slash | `/customers` | `/customers/` |
+
+## 3. Request & Response Envelope
+
+### Success Response
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "request_id": "req_abc123",
+    "timestamp": "2025-01-15T10:30:00Z"
+  }
+}
+```
+
+### List Response (with pagination)
+
+```json
+{
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "per_page": 25,
+    "total": 142,
+    "total_pages": 6
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Invalid email format" },
+      { "field": "age", "message": "Must be at least 18" }
+    ]
+  }
+}
+```
+
+## 4. HTTP Status Codes
+
+Use the right code. Clients depend on these for control flow.
+
+| Code | When to Use |
+|------|-------------|
+| `200 OK` | Successful GET, PUT, PATCH |
+| `201 Created` | Successful POST that creates a resource |
+| `204 No Content` | Successful DELETE |
+| `400 Bad Request` | Malformed request body or parameters |
+| `401 Unauthorized` | Missing or invalid authentication |
+| `403 Forbidden` | Authenticated but not authorized |
+| `404 Not Found` | Resource doesn't exist |
+| `409 Conflict` | Duplicate resource, version conflict |
+| `422 Unprocessable Entity` | Valid syntax but semantic validation failed |
+| `429 Too Many Requests` | Rate limit exceeded (include `Retry-After` header) |
+| `500 Internal Server Error` | Unhandled server error |
+
+## 5. Pagination
+
+### Offset-based (simple, good for most cases)
+
+```
+GET /api/v1/customers?page=2&per_page=25
+```
+
+### Cursor-based (better for real-time data, large datasets)
+
+```
+GET /api/v1/events?cursor=eyJpZCI6MTAwfQ&limit=25
+```
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| Offset | Simple, supports jumping to page N | Skips/duplicates on mutations, slow at high offsets |
+| Cursor | Consistent with mutations, performant | No "jump to page 5", harder to implement |
+
+**Rule:** Use offset for admin/dashboard UIs. Use cursor for feeds, events, and public APIs.
+
+## 6. Filtering, Sorting, and Search
+
+```
+# Filtering — field-level with operators
+GET /api/v1/orders?status=open&created_after=2025-01-01
+
+# Sorting — field with direction prefix
+GET /api/v1/orders?sort=-created_at        # descending
+GET /api/v1/orders?sort=status,created_at   # multi-field
+
+# Search — dedicated parameter
+GET /api/v1/customers?q=acme+corp
+
+# Field selection — sparse fieldsets
+GET /api/v1/customers?fields=id,name,email
+```
+
+## 7. Versioning
+
+### URL Path versioning (recommended)
+
+```
+/api/v1/customers
+/api/v2/customers
+```
+
+### Version lifecycle
+
+| Phase | Duration | Behaviour |
+|-------|----------|-----------|
+| **Current** | Indefinite | Actively maintained |
+| **Deprecated** | 6-12 months | Returns `Deprecation` header, still works |
+| **Sunset** | After deprecation | Returns `410 Gone` |
+
+```python
+# FastAPI deprecation header
+@app.get("/api/v1/old-endpoint", deprecated=True)
+async def old_endpoint(response: Response):
+    response.headers["Deprecation"] = "true"
+    response.headers["Sunset"] = "2026-06-01"
+    response.headers["Link"] = '</api/v2/new-endpoint>; rel="successor-version"'
+    return {"data": ...}
+```
+
+## 8. Authentication & Security
+
+- Use `Authorization: Bearer <token>` for API auth
+- Never put tokens in URL query parameters (they appear in logs)
+- Return `401` for missing/invalid auth, `403` for insufficient permissions
+- Include `X-Request-Id` header for tracing
+- Rate limit all public endpoints
+
+## 9. FastAPI Implementation Pattern
+
+```python
+from fastapi import APIRouter, Depends, Query, HTTPException, status
+from pydantic import BaseModel, Field
+
+router = APIRouter(prefix="/api/v1/customers", tags=["customers"])
+
+class CustomerCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=200)
+    email: str = Field(..., pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
+
+class CustomerResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+
+class PaginatedResponse(BaseModel):
+    data: list[CustomerResponse]
+    pagination: dict
+
+@router.get("", response_model=PaginatedResponse)
+async def list_customers(
+    page: int = Query(1, ge=1),
+    per_page: int = Query(25, ge=1, le=100),
+):
+    ...
+
+@router.post("", response_model=CustomerResponse, status_code=status.HTTP_201_CREATED)
+async def create_customer(body: CustomerCreate):
+    ...
+
+@router.get("/{customer_id}", response_model=CustomerResponse)
+async def get_customer(customer_id: str):
+    customer = await repo.find(customer_id)
+    if not customer:
+        raise HTTPException(status_code=404, detail="Customer not found")
+    return customer
+```
+
+## 10. API Design Checklist
+
+Before shipping an API endpoint:
+
+- [ ] Resource names are plural nouns in kebab-case
+- [ ] Correct HTTP methods (GET reads, POST creates, etc.)
+- [ ] Correct status codes (201 for create, 204 for delete)
+- [ ] Request body validated with Pydantic/Zod
+- [ ] Error responses use consistent envelope with error code
+- [ ] Pagination implemented for list endpoints
+- [ ] Authentication required (unless intentionally public)
+- [ ] Rate limiting configured
+- [ ] OpenAPI spec generated and reviewed
+- [ ] No sensitive data in URLs or logs
+
+## 11. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Verbs in URLs | `/getUser`, `/deleteOrder` | Use HTTP methods + nouns |
+| Inconsistent pluralisation | `/user` vs `/orders` | Always plural |
+| Returning 200 for errors | Client can't distinguish success/failure | Use proper status codes |
+| Nested resources > 2 levels | Hard to discover, fragile URLs | Flatten with query params |
+| No pagination on lists | Unbounded response size, OOM | Always paginate |
+| Exposing internal IDs/schemas | Coupling clients to implementation | Use public-facing schemas |