compound-agent 1.7.6 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,50 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- **Replace node-llama-cpp with Transformers.js**: Swap EmbeddingGemma-300M (node-llama-cpp, 431MB RSS) for nomic-embed-text-v1.5 (@huggingface/transformers, 23MB RSS) — 95% memory reduction (E5b).
+- **Remove all node-llama-cpp residue**: Update setup templates, doctor diagnostics, comments, and vitest config to reference Transformers.js and onnxruntime-node instead of node-llama-cpp (E5c).
+- **Gemini adapter is now opt-in**: `installGeminiAdapter()` no longer runs automatically during setup. Users enable it explicitly via `npx ca setup gemini` (sets `gemini: true` in `compound-agent.json`). Use `npx ca setup gemini --disable` / `cleanGeminiCompoundFiles()` for clean removal.
+- **Stale cleanup refactored**: Removed hardcoded deprecation lists from upgrade logic, replaced with `cleanStaleArtifacts()` pattern that declaratively defines what to remove.
+
+### Added
+
+- **Research-specialist shipped agent**: New general-purpose research subagent (`research-specialist.md`) shipped via `npx ca init`. Has full tool access (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch) so it can conduct deep PhD-level research, write survey papers, run experiments, and validate claims with code. Referenced by the `get-a-phd` workflow for parallel research execution.
+- **`model-info.ts` module**: Extracted embedding model metadata (name, repo, dimensions, file) into a standalone module with zero native imports, decoupling the import graph so that CLI entry points no longer transitively load `node-llama-cpp` or `better-sqlite3` at parse time.
+- **Architect decomposition spec**: Added specification for embedding memory pressure remediation (`embedding-memory-pressure-remediation.md`).
+- **Hypothesis validation protocol**: Added to spec-dev skill — specs can now define falsifiable hypotheses with validation criteria.
+- **`cleanStaleArtifacts` and `cleanStaleGeminiArtifacts`**: New setup utilities that remove deprecated files and directories during upgrades instead of relying on hardcoded deprecation lists.
+- **LinkedIn architecture diagrams**: Integrated visual architecture diagrams into README (`docs/assets/`).
+- **Independent reviews**: Added Opus and Sonnet independent review documents for embedding memory pressure analysis.
+- **Embedding memory pressure investigation**: Added root-cause analysis, measurement data, and proposal documents in `docs/research/`.
+
+### Fixed
+
+- **Embedding memory pressure remediation**: Lazy-load native modules (@huggingface/transformers (onnxruntime-node), better-sqlite3) behind dynamic `import()`, reducing CLI cold-start RSS. Singleton embedding model uses explicit `dispose()`. Added RSS measurement script and integration tests for memory lifecycle.
+- **Review phase resilience**: Fixed jq stdin pipe handling, added auth health checks, and improved error isolation in loop review templates.
+- **Quality-filter-before-storage test ordering**: Resolved flaky test ordering in compound skill tests.
+- **Merged worktree review findings**: Addressed Opus/Sonnet review findings for worktree merges (loop-review-templates, stale-cleanup tests).
+- **Knowledge index integration tests**: Fixed test configuration for embedding integration tests in vitest workspace.
+
+
+## [1.8.0] - 2026-03-15
+
+### Added
+
+- **`ca improve` command**: Generates a bash script that autonomously improves the codebase using `improve/*.md` program files. Each program defines what to improve, how to find work, and how to validate changes. Options: `--topics` (filter specific topics), `--max-iters` (iterations per topic, default 5), `--time-budget` (total seconds, 0=unlimited), `--model`, `--force`, `--dry-run`. Includes `ca improve init` subcommand to scaffold an example program file.
+- **`ca watch` command**: Tails and pretty-prints live trace JSONL from infinity loop and improvement loop sessions. Supports `--epic <id>` to watch a specific epic, `--improve` to watch improvement loop traces, and `--no-follow` to print existing trace and exit. Formats tool calls, thinking blocks, token usage, and result markers into a compact, color-coded stream.
+
+### Fixed
+
+- **`git clean` scoping in improvement loop**: Bare `git clean -fd` on rollback was removing all untracked files including the script's own log directory, causing crashes. All three rollback paths now use `git clean -fd -e "$LOG_DIR/"` to exclude agent logs.
+- **Embedded dirty-worktree guard fallthrough**: In embedded mode (when improvement loop runs inside `ca loop --improve`), setting `IMPROVE_RESULT=1` on a dirty worktree did not prevent the loop body from executing. Restructured to use `if/else` so the loop body only runs inside the `else` branch.
+- **`ca watch --improve` ignoring `.latest` symlink**: The `--improve` code path had inline logic that only did reverse filename sort, bypassing the `.latest` symlink that the improvement loop maintains. Refactored `findLatestTraceFile()` with a `prefix` parameter to unify both code paths.
+- **`--topics` flag ignored in `get_topics()`**: The `TOPIC_FILTER` variable from the CLI `--topics` flag was not used in the generated bash `get_topics()` function, causing all topics to run regardless of filtering.
+- **Update-check hardening**: Switched to a lightweight npm registry endpoint, added CI environment guards, and corrected the update command shown to users.
+
 ## [1.7.6] - 2026-03-12
 
 ### Added
@@ -249,7 +293,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Eliminate double model initialization**: `ca search` now uses `isModelAvailable()` (fs.existsSync, zero cost) instead of `isModelUsable()` which loaded the 278MB native model just to probe availability, then loaded it again for actual embedding
 - **Bulk-read cached embeddings**: `getCachedEmbeddingsBulk()` replaces N individual `getCachedEmbedding()` SQLite queries with a single bulk read
 - **Eliminate redundant JSONL parsing**: `searchVector()` and `findSimilarLessons()` now use `readAllFromSqlite()` after `syncIfNeeded()` instead of re-parsing the JSONL file
-- **Float32Array consistency**: Lesson embedding path now keeps `Float32Array` from node-llama-cpp instead of converting via `Array.from()` (4x memory savings per vector)
+- **Float32Array consistency**: Lesson embedding path now keeps `Float32Array` from the embedding pipeline instead of converting via `Array.from()` (4x memory savings per vector)
 - **Pre-warm lesson embedding cache**: `ca init` now pre-computes embeddings for all lessons with missing or stale cache entries, eliminating cold-start latency on first search
 - **Graceful embedding fallback**: `ca search` falls back to keyword-only search on runtime embedding failures instead of crashing
 

package/README.md

@@ -6,6 +6,10 @@
 [![license](https://img.shields.io/npm/l/compound-agent)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/)
 
+<p align="center">
+  <img src="docs/assets/diagram-4.png" alt="Compound-agent ecosystem overview: Architect phase decomposes work via Socratic dialogue into a dependency graph. ca loop chains tasks with cross-model review, retry, and fresh sessions. Scenario evaluation validates changes with iterative refinement. All backed by persistent memory (lessons + knowledge across all sessions) and verification gates (tests, lint, type checks on every task)." width="700">
+</p>
+
 AI coding agents forget everything between sessions. Each session starts with whatever context was prepared for it — nothing more. Because agents carry no persistent state, that state must live in the codebase itself, and any agent that reads the same well-structured context should be able to pick up where another left off. Compound Agent implements this: it captures mistakes once, retrieves them precisely when relevant, and can hand entire systems to an autonomous loop that processes epic by epic with no human intervention.
 
 ## What gets installed
@@ -24,43 +28,22 @@ This is not a memory plugin bolted onto a text editor. It is the environment you
 
 ## How it works
 
-```mermaid
-flowchart TD
-    A["/compound:architect\nDecompose large system\ninto epics via DDD"] -->|produces epics| L
+Two memory systems persist across sessions:
 
-    subgraph L["Compound Loop — one cycle per epic"]
-        direction LR
-        S[SPEC-DEV] --> P[PLAN]
-        P --> W[WORK]
-        W --> R[REVIEW]
-        R --> C[COMPOUND]
-    end
+<p align="center">
+  <img src="docs/assets/diagram-1.png" alt="A task session between two memory systems: Lessons (JSONL + SQLite with semantic + keyword search) are retrieved before and captured after each task. Knowledge (project docs chunked and embedded) is queried on demand." width="700">
+</p>
 
-    C -->|writes lessons| M[(MEMORY\nJSONL + SQLite\n+ embeddings)]
-    M -->|injects context| P
+- **Lessons** — mistakes, corrections, and patterns stored as git-tracked JSONL, indexed in SQLite FTS5 with local embeddings for hybrid search. Retrieved at the start of each task, captured at the end.
+- **Knowledge** — project documentation chunked and embedded for semantic retrieval. Any phase can query it on demand.
 
-    style M fill:#f9f,stroke:#333
-    style A fill:#e8f4fd,stroke:#4a9ede
-```
+Each task runs through five phases, with review findings looping back to rework. Each phase runs as its own slash command so instructions are re-injected fresh (surviving context compaction):
 
-Each cycle through the loop makes the next one smarter. The architect step is optional — use it for systems too large for a single feature cycle.
+<p align="center">
+  <img src="docs/assets/diagram-2.png" alt="Inside a task: five phases (Spec, Plan, Work, Review, Compound) connected in sequence with a feedback loop from Review back to Work. Each phase runs as its own slash command with fresh instructions. Lessons are retrieved at start and captured at end. Knowledge is queryable from any phase." width="700">
+</p>
 
-```mermaid
-block-beta
-    columns 1
-    block:L3["Workflows  ·  Feedback Loops"]
-        A["15 slash commands"] B["24 specialized agents"] C["Autonomous loop"]
-    end
-    block:L2["Semantic Memory  ·  Codebase Memory"]
-        D["Vector search"] E["Hybrid retrieval"] F["Cross-session persistence"]
-    end
-    block:L1["Beads Foundation  ·  Navigable Structure"]
-        G["Issue tracking"] H["Git-backed sync"] I["Dependency graphs"]
-    end
-
-    L3 --> L2
-    L2 --> L1
-```
+Each cycle through the loop makes the next one smarter. The architect step is optional — use it for systems too large for a single feature cycle.
 
 ## Three principles
 
@@ -154,6 +137,10 @@ ca loop --reviewers claude-sonnet --review-every 3
 
 ## The infinity loop
 
+<p align="center">
+  <img src="docs/assets/diagram-3.png" alt="ca loop chains tasks in dependency order: Task 1 through Task 4, each running a full cycle in a fresh session. Cross-model review (R) gates between tasks. Failed tasks retry automatically. Tasks can escalate to human-required. Generated bash script with deterministic orchestration." width="700">
+</p>
+
 `ca loop` generates a bash script that processes your beads epics sequentially, running the full cook-it cycle on each one. No human intervention required between epics.
 
 ```bash
@@ -174,6 +161,35 @@ The loop respects beads dependency graphs — it only processes epics whose depe
 
 **Current maturity**: the loop works and has been used to ship real projects, including compound-agent itself. Two things still required human involvement: specifications had to be written before the loop started, and a human applied fixes after the first review pass surfaced real problems (missing error handling, a migration gap, insufficient test coverage). Fully unattended long-duration runs across many epics are the current area of hardening.
 
+## The improvement loop
+
+`ca improve` generates a bash script that iterates over `improve/*.md` program files, spawning Claude Code sessions to make focused improvements. Each program file defines what to improve, how to find work, and how to validate changes.
+
+```bash
+# Scaffold an example program file
+ca improve init
+# Creates improve/example.md with a linting template
+
+# Generate the improvement script
+ca improve
+
+# Filter to specific topics
+ca improve --topics lint tests --max-iters 3
+
+# Preview without generating
+ca improve --dry-run
+
+# Run the generated script
+./improvement-loop.sh
+
+# Preview without executing Claude sessions
+IMPROVE_DRY_RUN=1 ./improvement-loop.sh
+```
+
+Each iteration makes one focused improvement, commits it, and moves on. If an iteration finds nothing to improve or fails validation, it reverts cleanly and moves to the next topic. The loop tracks consecutive no-improvement results and stops early to avoid diminishing returns.
+
+Monitor progress with `ca watch --improve` to see live trace output from improvement sessions.
+
 ## Automatic hooks
 
 Once installed, seven Claude Code hooks fire without any commands:
@@ -213,18 +229,15 @@ Three human approval gates separate the phases. Each output epic is sized for on
 # Install as dev dependency
 pnpm add -D compound-agent
 
-# One-shot setup (creates dirs, hooks, downloads model)
+# One-shot setup (creates dirs, hooks, templates)
 npx ca setup
-
-# Skip the ~278MB model download (do it later)
-npx ca setup --skip-model
 ```
 
 ### Requirements
 
 - Node.js >= 20
 - ~278MB disk space for the embedding model (one-time download, shared across projects)
-- ~150MB RAM during embedding operations
+- ~23MB RAM during embedding operations (nomic-embed-text-v1.5 via Transformers.js)
 
 ### pnpm Users
 
@@ -235,7 +248,7 @@ If you prefer to configure manually, add to your `package.json`:
 ```json
 {
   "pnpm": {
-    "onlyBuiltDependencies": ["better-sqlite3", "node-llama-cpp"]
+    "onlyBuiltDependencies": ["better-sqlite3", "onnxruntime-node"]
   }
 }
 ```
@@ -303,6 +316,17 @@ The CLI binary is `ca` (alias: `compound-agent`).
 | `ca loop --max-review-cycles <n>` | Max review/fix iterations (default: 3) |
 | `ca loop --review-blocking` | Fail loop if review not approved after max cycles |
 | `ca loop --review-model <model>` | Model for implementer fix sessions (default: claude-opus-4-6) |
+| `ca improve` | Generate improvement loop script from `improve/*.md` programs |
+| `ca improve --topics <names...>` | Run only specific topics |
+| `ca improve --max-iters <n>` | Max iterations per topic (default: 5) |
+| `ca improve --time-budget <seconds>` | Total time budget, 0=unlimited (default: 0) |
+| `ca improve --dry-run` | Validate and print plan without generating |
+| `ca improve --force` | Overwrite existing script |
+| `ca improve init` | Scaffold an example `improve/*.md` program file |
+| `ca watch` | Tail and pretty-print live trace from loop sessions |
+| `ca watch --epic <id>` | Watch a specific epic trace |
+| `ca watch --improve` | Watch improvement loop traces |
+| `ca watch --no-follow` | Print existing trace and exit (no live tail) |
 
 ### Knowledge
 
@@ -315,15 +339,14 @@ The CLI binary is `ca` (alias: `compound-agent`).
 
 | Command | Description |
 |---------|-------------|
-| `ca setup` | One-shot setup (hooks + git pre-commit + model) |
-| `ca setup --skip-model` | Setup without model download |
-| `ca setup --uninstall` | Remove all generated files |
-| `ca setup --update` | Regenerate files (preserves user customisations) |
-| `ca setup --status` | Show installation status |
-| `ca setup --dry-run` | Show what would change without changing |
+| `ca setup` | One-shot setup (hooks + templates) |
+| `ca setup --skip-hooks` | Setup without installing hooks |
+| `ca setup --json` | Output result as JSON |
+| `ca setup --repo-root <path>` | Specify repository root |
+| `ca setup claude` | Install Claude Code hooks only |
 | `ca setup claude --status` | Check Claude Code integration health |
 | `ca setup claude --uninstall` | Remove Claude hooks only |
-| `ca download-model` | Download the embedding model |
+| `ca init` | Initialize compound-agent in current repo |
 | `ca about` | Show version, animation, and recent changelog |
 | `ca doctor` | Verify external dependencies and project health |
 
@@ -354,7 +377,7 @@ confirmation_boost: confirmed=1.3, unconfirmed=1.0
 A: mem0 is a cloud memory layer for general AI agents. Compound Agent is local-first with git-tracked storage and local embeddings — no API keys or cloud services needed. It also goes beyond memory with structured workflows, multi-agent review, and issue tracking.
 
 **Q: Does this work offline?**
-A: Yes, completely. Embeddings run locally via node-llama-cpp. No network requests after the initial model download.
+A: Yes, completely. Embeddings run locally via @huggingface/transformers (Transformers.js). No network requests after the initial model download.
 
 **Q: How much disk space does it need?**
 A: ~278MB for the embedding model (one-time download, shared across projects) plus negligible space for lessons.
@@ -394,7 +417,7 @@ pnpm lint             # Type check + ESLint
 | Build | tsup |
 | Testing | Vitest + fast-check (property tests) |
 | Storage | better-sqlite3 + FTS5 |
-| Embeddings | node-llama-cpp + EmbeddingGemma-300M |
+| Embeddings | @huggingface/transformers + nomic-embed-text-v1.5 (Q8 ONNX) |
 | CLI | Commander.js |
 | Schema | Zod |
 | Issue Tracking | Beads (bd) |

package/bin/ca

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+// Thin wrapper that spawns the Go binary.
+// Uses Node.js only for locating the binary; all work is done by the Go process.
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Resolution order: env override → postinstall binary → local Go build
+const candidates = [
+  process.env.CA_BINARY_PATH,
+  resolve(__dirname, "ca-binary"),
+  resolve(__dirname, "..", "go", "dist", "ca"),
+].filter(Boolean);
+
+const binaryPath = candidates.find((p) => existsSync(p));
+
+if (!binaryPath) {
+  console.error("[compound-agent] Binary not found. Try reinstalling compound-agent or run: cd go && make build");
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  // execFileSync throws on non-zero exit codes; forward the exit code
+  process.exit(err.status || 1);
+}

package/package.json

@@ -1,28 +1,31 @@
 {
   "name": "compound-agent",
-  "version": "1.7.6",
-  "description": "Semantically-intelligent workflow plugin for Claude Code",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "version": "2.0.0",
+  "description": "Learning system for Claude Code — avoids repeating mistakes across sessions",
   "bin": {
-    "compound-agent": "./dist/cli.js",
-    "ca": "./dist/cli.js"
+    "ca": "./bin/ca",
+    "compound-agent": "./bin/ca"
   },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
+  "scripts": {
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "files": [
-    "dist",
-    "docs/research",
-    "scripts/postinstall.mjs",
+    "bin/",
+    "scripts/postinstall.cjs",
+    "README.md",
+    "LICENSE",
     "CHANGELOG.md",
     "llms.txt",
     "context7.json"
   ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Nathandela/compound-agent.git"
@@ -32,84 +35,22 @@
   },
   "homepage": "https://github.com/Nathandela/compound-agent#readme",
   "llms": "https://raw.githubusercontent.com/Nathandela/compound-agent/main/llms.txt",
-  "scripts": {
-    "postinstall": "node scripts/postinstall.mjs",
-    "prebuild": "tsx scripts/extract-changelog.ts",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "pnpm build && vitest run",
-    "test:fast": "vitest run --project unit --project embedding",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "pnpm build && vitest run --project integration",
-    "test:watch": "vitest",
-    "test:changed": "vitest run --changed HEAD~1",
-    "test:all": "pnpm build && pnpm download-model && vitest run",
-    "test:segment": "tsx src/test-utils/run-segment.ts",
-    "test:random": "tsx src/test-utils/run-random.ts",
-    "test:critical": "vitest run --project unit -- critical",
-    "lint": "tsc --noEmit && eslint . --max-warnings=0",
-    "download-model": "node ./dist/cli.js download-model",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "claude",
     "claude-code",
     "compound-agent",
-    "semantic-memory",
-    "memory",
-    "embeddings",
-    "vector-search",
     "ai",
     "agent",
     "llm",
-    "plugin",
     "cli",
     "developer-tools",
     "workflow",
     "tdd",
-    "sqlite",
     "knowledge-management"
   ],
   "author": "Nathan Delacrétaz",
   "license": "MIT",
-  "packageManager": "pnpm@10.28.2",
   "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@fast-check/vitest": "0.2.4",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^20.11.0",
-    "@typescript-eslint/rule-tester": "8.55.0",
-    "@vitest/coverage-v8": "2.1.9",
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-import-x": "4.16.1",
-    "eslint-plugin-vitest": "0.5.4",
-    "fast-check": "4.5.3",
-    "tsup": "^8.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.3.0",
-    "typescript-eslint": "8.55.0",
-    "vitest": "^2.0.0"
-  },
-  "dependencies": {
-    "better-sqlite3": "^11.0.0",
-    "chalk": "5.6.2",
-    "commander": "^12.0.0",
-    "node-llama-cpp": "^3.0.0",
-    "zod": "^3.22.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "better-sqlite3",
-      "node-llama-cpp",
-      "esbuild"
-    ],
-    "overrides": {
-      "tar": ">=7.5.7",
-      "axios": ">=1.13.5"
-    }
+    "node": ">=18"
   }
 }

package/scripts/postinstall.cjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+
+// Downloads platform-specific binaries (ca + ca-embed) from GitHub Releases.
+// Uses Node.js platform detection (NOT Go's runtime.GOARCH) to handle
+// Rosetta/emulation correctly on Apple Silicon.
+//
+// Exports getPlatformKey, verifyChecksum, shouldSkipDownload for testability.
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { createHash } = require("crypto");
+
+const PLATFORM_MAP = { darwin: "darwin", linux: "linux" };
+const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
+const REPO = "Nathandela/compound-agent";
+
+function getPlatformKey(platform, arch) {
+  const p = PLATFORM_MAP[platform];
+  const a = ARCH_MAP[arch];
+  if (!p || !a) {
+    throw new Error(
+      `Unsupported platform: ${platform}-${arch}. Supported: darwin-amd64, darwin-arm64, linux-amd64, linux-arm64`
+    );
+  }
+  return `${p}-${a}`;
+}
+
+function verifyChecksum(filePath, artifactName, checksumsPath) {
+  const checksums = fs.readFileSync(checksumsPath, "utf-8");
+  const lines = checksums.trim().split("\n");
+
+  let expectedHash = null;
+  for (const line of lines) {
+    // GoReleaser format: <sha256>  <filename>
+    const parts = line.trim().split(/\s+/);
+    if (parts.length >= 2 && parts[1] === artifactName) {
+      expectedHash = parts[0];
+      break;
+    }
+  }
+
+  if (!expectedHash) {
+    throw new Error(`${artifactName} not found in checksums.txt`);
+  }
+
+  const fileData = fs.readFileSync(filePath);
+  const actualHash = createHash("sha256").update(fileData).digest("hex");
+  return actualHash === expectedHash;
+}
+
+function shouldSkipDownload(binDir) {
+  const caPath = path.join(binDir, "ca-binary");
+  const embedPath = path.join(binDir, "ca-embed");
+
+  if (!fs.existsSync(caPath) || !fs.existsSync(embedPath)) {
+    return false;
+  }
+
+  try {
+    // P1-2 fix: use execFileSync (no shell) instead of execSync
+    execFileSync(caPath, ["version"], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const follow = (currentUrl, redirects) => {
+      if (redirects > 5) {
+        reject(new Error("Too many redirects"));
+        return;
+      }
+
+      // P0-2 fix: validate redirect URLs stay on HTTPS
+      if (!currentUrl.startsWith("https://")) {
+        reject(new Error(`Refusing non-HTTPS redirect: ${currentUrl}`));
+        return;
+      }
+
+      https
+        .get(currentUrl, { timeout: 60000 }, (res) => {
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            follow(res.headers.location, redirects + 1);
+            return;
+          }
+
+          if (res.statusCode !== 200) {
+            reject(new Error(`Download failed: HTTP ${res.statusCode} from ${currentUrl}`));
+            return;
+          }
+
+          const file = fs.createWriteStream(dest);
+          res.pipe(file);
+          file.on("finish", resolve);
+          file.on("error", (err) => {
+            fs.unlink(dest, () => {});
+            reject(err);
+          });
+          res.on("error", (err) => {
+            file.destroy();
+            fs.unlink(dest, () => {});
+            reject(err);
+          });
+        })
+        .on("timeout", () => {
+          reject(new Error(`Download timed out: ${currentUrl}`));
+        })
+        .on("error", reject);
+    };
+
+    follow(url, 0);
+  });
+}
+
+// P1-3 fix: download to .tmp name, rename after checksum verification
+async function downloadBinary(binDir, url, destName, label) {
+  const tmpPath = path.join(binDir, destName + ".tmp");
+
+  await downloadFile(url, tmpPath);
+
+  const stats = fs.statSync(tmpPath);
+  const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+  console.log(`[compound-agent] ${label}: ${sizeMB} MB`);
+}
+
+function cleanupBinaries(binDir) {
+  for (const name of ["ca-binary", "ca-binary.tmp", "ca-embed", "ca-embed.tmp", "checksums.txt"]) {
+    try { fs.unlinkSync(path.join(binDir, name)); } catch { /* ignore */ }
+  }
+}
+
+async function main() {
+  // Skip self-install (when running pnpm install inside compound-agent itself)
+  if (process.env.npm_package_name === "compound-agent") return;
+
+  const platformKey = getPlatformKey(
+    require("os").platform(),
+    require("os").arch()
+  );
+
+  const pkg = require("../package.json");
+  const version = pkg.version;
+
+  const binDir = path.resolve(__dirname, "../bin");
+
+  if (shouldSkipDownload(binDir)) {
+    console.log("[compound-agent] Binaries already installed, skipping download");
+    return;
+  }
+
+  console.log(`[compound-agent] Platform: ${platformKey}`);
+  console.log(`[compound-agent] Downloading: v${version}`);
+
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
+  const baseUrl = `https://github.com/${REPO}/releases/download/v${version}`;
+
+  try {
+    // Download checksums first
+    const checksumsPath = path.join(binDir, "checksums.txt");
+    await downloadFile(`${baseUrl}/checksums.txt`, checksumsPath);
+
+    // Download both binaries in parallel (to .tmp names)
+    const caArtifact = `ca-${platformKey}`;
+    const embedArtifact = `ca-embed-${platformKey}`;
+
+    await Promise.all([
+      downloadBinary(binDir, `${baseUrl}/${caArtifact}`, "ca-binary", "CLI binary"),
+      downloadBinary(binDir, `${baseUrl}/${embedArtifact}`, "ca-embed", "Embed daemon"),
+    ]);
+
+    // Verify checksums against .tmp files
+    const caOk = verifyChecksum(path.join(binDir, "ca-binary.tmp"), caArtifact, checksumsPath);
+    const embedOk = verifyChecksum(path.join(binDir, "ca-embed.tmp"), embedArtifact, checksumsPath);
+
+    if (!caOk || !embedOk) {
+      const failed = [];
+      if (!caOk) failed.push("ca");
+      if (!embedOk) failed.push("ca-embed");
+      // P1-4 fix: clean up bad binaries before throwing
+      cleanupBinaries(binDir);
+      throw new Error(`Checksum verification failed for: ${failed.join(", ")}`);
+    }
+
+    console.log("[compound-agent] Checksums verified");
+
+    // Checksums passed — rename .tmp to final names and set executable
+    fs.renameSync(path.join(binDir, "ca-binary.tmp"), path.join(binDir, "ca-binary"));
+    fs.chmodSync(path.join(binDir, "ca-binary"), 0o755);
+    fs.renameSync(path.join(binDir, "ca-embed.tmp"), path.join(binDir, "ca-embed"));
+    fs.chmodSync(path.join(binDir, "ca-embed"), 0o755);
+
+    // Functional verification (P1-2 fix: use execFileSync)
+    try {
+      execFileSync(path.join(binDir, "ca-binary"), ["version"], { stdio: "pipe" });
+      console.log("[compound-agent] Functional check passed");
+    } catch {
+      cleanupBinaries(binDir);
+      throw new Error("Binary downloaded but functional check failed (ca version exited non-zero)");
+    }
+  } catch (err) {
+    console.error(`[compound-agent] Installation failed: ${err.message}`);
+    console.error("[compound-agent] You can manually download binaries from:");
+    console.error(`[compound-agent]   https://github.com/${REPO}/releases/tag/v${version}`);
+    process.exit(1);
+  }
+}
+
+// Export for testing
+module.exports = { getPlatformKey, verifyChecksum, shouldSkipDownload };
+
+// Run main only when executed directly (not when required for testing)
+if (require.main === module) {
+  main();
+}

package/dist/cli.d.ts

@@ -1 +0,0 @@
-#!/usr/bin/env node