codiedev 0.9.80 → 0.10.0-beta.10

package/README.md

@@ -5,14 +5,20 @@ Connect Claude Code, Codex, Cursor, or OpenCode to Codiedev for team session cap
 ## Usage
 
 ```bash
-npx codiedev connect
+npm install -g codiedev@latest
+codiedev connect
+codiedev doctor
 ```
 
+If global npm installs are blocked, use `npx codiedev@latest connect` and
+`npx codiedev@latest doctor` instead. The agent instructions include the same
+fallback for other commands.
+
 The CLI will prompt you for an API token (get one at https://codiedev.com/portal/integrations/claude-code), then install a capture hook into whichever agent CLIs are present on your machine:
 
 - **Claude Code** — `SessionEnd` hook in `~/.claude/settings.json`
 - **Codex** — `Stop` hook in `~/.codex/hooks.json`
-- **Cursor** — native session, backup, and capture hooks in `~/.cursor/hooks.json`
+- **Cursor** — native session, subagent/tool observation, backup, and capture hooks in `~/.cursor/hooks.json`
 - **OpenCode / Codie** — plugin in `~/.config/opencode/plugins/codiedev.js`
 
 Installed clients are wired automatically. The OpenCode adapter is staged even
@@ -51,9 +57,10 @@ Codex doesn't currently expose a `SessionEnd` event, so the hook runs on `Stop`
 
 ## Cursor note
 
-Cursor uses its native hook events for session start/end and stop-time backup.
-Cursor's `beforeSubmitPrompt` currently cannot inject dynamic context, so task-
-specific discovery remains unavailable there. Cursor sessions keep their source
+Cursor uses its native hook events for session start/end, tool and subagent
+observation, and stop-time backup. Cursor's `beforeSubmitPrompt` cannot inject
+dynamic context today, so task-specific discovery is not claimed.
+Cursor sessions keep their source
 label and real transcript statistics through the shared capture pipeline.
 
 ## OpenCode note

package/dist/backup/cache.js

@@ -49,7 +49,7 @@ function loadCache(readFileSync = fs.readFileSync) {
         return JSON.parse(readFileSync(CACHE_PATH, "utf8"));
     }
     catch {
-        return {}; // missing or corrupt → empty
+        return {};
     }
 }
 function saveCache(cache, deps = fs) {
@@ -58,12 +58,8 @@ function saveCache(cache, deps = fs) {
         deps.writeFileSync(CACHE_PATH, JSON.stringify(cache), { mode: 0o600 });
     }
     catch {
-        // best-effort — a failed cache write just means a redundant push next turn,
-        // which the server idempotently no-ops.
     }
 }
-// Pure: given the prior cache, a repo key, and this turn's candidates, return
-// the subset whose hash changed plus the cache to persist.
 function applyCache(prev, repoKey, candidates) {
     const next = { ...prev };
     const changed = [];

package/dist/backup/match.js

@@ -1,8 +1,4 @@
 "use strict";
-// Pure path matcher for the auto-backup hook. Decides whether a repo-relative
-// path is an "artifact" worth backing up. Deny rules win over allow rules.
-// `getContent` is lazy: only called when a path-level allow needs the
-// skill-frontmatter exclusion (skills are pushed deliberately, not auto-backed).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasSkillFrontmatter = hasSkillFrontmatter;
 exports.isArtifactPath = isArtifactPath;
@@ -15,7 +11,6 @@ function basename(p) {
     const i = p.lastIndexOf("/");
     return i === -1 ? p : p.slice(i + 1);
 }
-// A leading `---` block containing both `name:` and `description:` → skill.
 function hasSkillFrontmatter(md) {
     const m = md.match(/^?---\s*\n([\s\S]*?)\n---/);
     if (!m)
@@ -62,7 +57,6 @@ function isArtifactPath(rel, getContent) {
             return false;
     }
     catch {
-        // unreadable → treat as non-skill; the push will fail harmlessly later
     }
     return true;
 }

package/dist/backup/run.js

@@ -40,7 +40,6 @@ exports.runBackup = runBackup;
 exports.runBackupUpload = runBackupUpload;
 const match_1 = require("./match");
 const cache_1 = require("./cache");
-// Pure: merge two path lists into one, deduped, preserving first-seen order.
 function unionPaths(a, b) {
     const seen = new Set();
     const out = [];
@@ -56,8 +55,6 @@ function unionPaths(a, b) {
         }
     return out;
 }
-// Pure: from this turn's git-status paths, keep artifact files whose content
-// hash changed since the cache. Returns the changed candidates + next cache.
 function selectBackupFiles(input) {
     const candidates = [];
     for (const rel of input.statusPaths) {
@@ -70,7 +67,7 @@ function selectBackupFiles(input) {
             c = getContent();
         }
         catch {
-            continue; // deleted/unreadable → skip
+            continue;
         }
         if (c === undefined || c === null)
             continue;
@@ -99,11 +96,7 @@ function gitRoot(cwd) {
 }
 function gitStatusPaths(root) {
     try {
-        // --untracked-files=all is REQUIRED: the default collapses untracked files
-        // into their top-level directory (a new docs/superpowers/plans/x.md shows as
-        // just "docs/"), which would make the hook miss brand-new artifact files.
         const out = (0, child_process_1.execFileSync)("git", ["-C", root, "status", "--porcelain", "-z", "--untracked-files=all"], { encoding: "utf8" });
-        // -z: NUL-separated, each entry "XY <path>"; rename entries have two paths.
         return out
             .split("\0")
             .filter(Boolean)
@@ -114,8 +107,6 @@ function gitStatusPaths(root) {
         return [];
     }
 }
-// All git-tracked files (committed, regardless of dirty state). `git ls-files`
-// emits bare NUL-separated paths — no "XY " status prefix — so we don't slice.
 function gitTrackedPaths(root) {
     try {
         const out = (0, child_process_1.execFileSync)("git", ["-C", root, "ls-files", "-z"], {
@@ -127,16 +118,10 @@ function gitTrackedPaths(root) {
         return [];
     }
 }
-// The hook's candidate set: dirty/untracked files ∪ all tracked files. Feeding
-// tracked files in is what lets a COMMITTED artifact (clean status) still get
-// backed up — the hash cache in selectBackupFiles dedups so already-backed-up
-// files don't re-upload. selectBackupFiles rejects non-artifact paths cheaply
-// (by regex, no content read), so the full tracked list is fine to pass.
 function gitCandidatePaths(root) {
     return unionPaths(gitStatusPaths(root), gitTrackedPaths(root));
 }
 const sha256 = (s) => crypto.createHash("sha256").update(s, "utf8").digest("hex");
-// Stop/sessionEnd hook entry. Best-effort, never throws.
 function runBackup(cwd, hookScriptPath) {
     try {
         if (process.env.CODIEDEV_NO_AUTOBACKUP)
@@ -150,8 +135,6 @@ function runBackup(cwd, hookScriptPath) {
         if (!root)
             return;
         const repoKey = (0, utils_1.getGitRemoteUrl)(root) ?? root;
-        // Dirty files ∪ tracked files — so committed-but-unbacked artifacts are
-        // caught too, not just unsaved drafts. Hash cache dedups the rest.
         const statusPaths = gitCandidatePaths(root);
         if (statusPaths.length === 0)
             return;
@@ -164,12 +147,6 @@ function runBackup(cwd, hookScriptPath) {
         });
         if (changed.length === 0)
             return;
-        // The detached child owns the cache: it writes each file's hash ONLY after a
-        // successful push, so a genuine push failure (network/500) leaves the hash
-        // uncached and the file retries next turn. (Persisting here optimistically
-        // would suppress that retry, since the server no-op only covers successes.)
-        // Job carries root + repoKey + files; the child re-reads config from disk
-        // via readConfig() (same machine), avoiding any config-shape guessing.
         const job = {
             root,
             repoKey,
@@ -184,18 +161,13 @@ function runBackup(cwd, hookScriptPath) {
         child.unref();
     }
     catch {
-        // best-effort
     }
 }
 const DEFAULT_BACKUP_UPLOAD_DEPS = { readConfig: utils_1.readConfig, loadCache: cache_2.loadCache, saveCache: cache_2.saveCache };
-// Detached child: push each queued file privately, caching its hash ONLY on a
-// successful push (so a failed push retries next turn), then delete the job
-// file. Deps are injectable so the cache write is testable without touching the
-// global ~/.codiedev cache.
 async function runBackupUpload(jobFile, deps = DEFAULT_BACKUP_UPLOAD_DEPS) {
     try {
         const job = JSON.parse(fs.readFileSync(jobFile, "utf8"));
-        const config = deps.readConfig(); // same machine — read full config from disk
+        const config = deps.readConfig();
         if (!config)
             return;
         if ((0, captureExclusions_1.isCaptureIgnored)(job.root, config.captureIgnoredPaths))
@@ -210,25 +182,21 @@ async function runBackupUpload(jobFile, deps = DEFAULT_BACKUP_UPLOAD_DEPS) {
                     visibility: "private",
                     contentHash: f.hash,
                 });
-                // Only now that the push landed do we record the hash — a prior failure
-                // leaves it uncached so the next turn retries it.
                 cache[(0, cache_2.cacheKey)(job.repoKey, f.rel)] = f.hash;
                 dirty = true;
             }
             catch {
-                // one file failing must not abort the rest, and its hash stays uncached
             }
         }
         if (dirty)
             deps.saveCache(cache);
     }
     catch {
-        // best-effort
     }
     finally {
         try {
             fs.unlinkSync(jobFile);
         }
-        catch { /* gone */ }
+        catch { }
     }
 }

package/dist/captureExclusions.js

@@ -47,12 +47,6 @@ const DEFAULT_NORMALIZE_DEPS = {
     homedir: () => os.homedir(),
     realpathSync: (value) => fs.realpathSync.native(value),
 };
-/**
- * Convert a user-entered path into the canonical absolute form persisted in
- * ~/.codiedev/config.json. Existing symlinks resolve to their real target so a
- * session cannot bypass an exclusion by entering the same folder through a
- * different alias. Non-existent paths still normalize deterministically.
- */
 function normalizeCapturePath(input, deps = {}) {
     const d = { ...DEFAULT_NORMALIZE_DEPS, ...deps };
     const trimmed = input.trim();
@@ -94,7 +88,6 @@ function findMatchingCaptureExclusion(candidate, ignoredPaths) {
 function isCaptureIgnored(candidate, ignoredPaths) {
     return findMatchingCaptureExclusion(candidate, ignoredPaths) !== null;
 }
-/** Every local root associated with a hook event, deduped in stable order. */
 function captureScopePaths(input, fallback = process.cwd()) {
     const values = [input.cwd, ...(input.workspace_roots ?? [])]
         .filter((value) => typeof value === "string" && value.length > 0);
@@ -103,11 +96,6 @@ function captureScopePaths(input, fallback = process.cwd()) {
 function shouldIgnoreCaptureInput(config, input, fallback) {
     return isCaptureIgnored(captureScopePaths(input, fallback), config?.captureIgnoredPaths);
 }
-/**
- * Final egress decision for queued transcript uploads. Jobs written by older
- * CLI versions have no scope metadata; once any exclusion exists, dropping
- * those legacy jobs is safer than guessing that they are public.
- */
 function shouldSkipCaptureUploadJob(job, config) {
     const ignoredPaths = config?.captureIgnoredPaths ?? [];
     if (ignoredPaths.length === 0)

package/dist/captureLog.js

@@ -36,47 +36,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CAPTURE_LOG_PATH = exports.CAPTURE_LOG_MAX_BYTES = void 0;
 exports.appendCaptureLog = appendCaptureLog;
 exports.readCaptureLogTail = readCaptureLogTail;
-// Rotating capture diagnostic log at <codiedevStateDir()>/capture.log
-// (~/.codiedev by default; ~/.codiedev-desktop under CODIEDEV_CONFIG_DIR).
-//
-// Every stage of the capture pipeline (capture-finish child, upload child,
-// stderr from detached children) writes one line here so users — and
-// `codiedev doctor` — can see exactly why a capture succeeded or failed
-// without having to file a support ticket or grep /tmp. The log is
-// best-effort throughout: appendCaptureLog NEVER throws into the hook path.
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-// Imported from configDir (not utils) — utils.ts imports this module, so
-// importing utils.ts here would create a circular import.
 const configDir_1 = require("./configDir");
-// Rotate the log when it exceeds this size (keeps the newest ~half). 256 KB
-// holds thousands of entries; a user would have to see hundreds of errors
-// before hitting this limit, so it's a generous safety valve.
 exports.CAPTURE_LOG_MAX_BYTES = 256 * 1024;
 exports.CAPTURE_LOG_PATH = path.join((0, configDir_1.codiedevStateDir)(), "capture.log");
-// Append one structured line to the capture log. Rotates the file when it
-// grows past CAPTURE_LOG_MAX_BYTES by truncating it to the newest half (keeps
-// the most recent diagnostics). Best-effort: NEVER throws into the hook path —
-// a diagnostic log must not break the thing it's diagnosing.
 function appendCaptureLog(entry, deps = fs, filePath = exports.CAPTURE_LOG_PATH, now = Date.now) {
     try {
         const dir = path.dirname(filePath);
         if (!deps.existsSync(dir))
             deps.mkdirSync(dir, { recursive: true });
         if (deps.existsSync(filePath) && deps.statSync(filePath).size >= exports.CAPTURE_LOG_MAX_BYTES) {
-            // Rotation: keep the newest half. Slice from the middle to a line
-            // boundary so we never persist a torn (partial) first line.
             const content = deps.readFileSync(filePath, "utf8");
             const half = content.slice(Math.floor(content.length / 2));
             const firstNewline = half.indexOf("\n");
-            // If no newline is found in the second half, drop it all and start
-            // fresh — better than keeping a torn line.
             const fromLine = firstNewline === -1 ? "" : half.slice(firstNewline + 1);
             deps.writeFileSync(filePath, fromLine);
         }
-        // Sanitize before composing: error messages can carry newlines (e.g. a
-        // proxy's HTML error body in err.message) which would tear the one-line
-        // format that doctor's parser depends on.
         const outcome = entry.outcome.replace(/\s+/g, " ").trim();
         const detail = entry.detail?.replace(/\s+/g, " ").trim();
         const line = `${new Date(now()).toISOString()} ${entry.stage} session=${entry.sessionId ?? "-"} ${outcome}` +
@@ -85,12 +61,8 @@ function appendCaptureLog(entry, deps = fs, filePath = exports.CAPTURE_LOG_PATH,
         deps.appendFileSync(filePath, line);
     }
     catch {
-        // diagnostics must never break capture
     }
 }
-// Read the last N lines from the capture log. Returns [] when the file is
-// missing or unreadable — callers (e.g. `codiedev doctor`) treat that as
-// "nothing captured yet" rather than an error.
 function readCaptureLogTail(n, deps = fs, filePath = exports.CAPTURE_LOG_PATH) {
     try {
         if (!deps.existsSync(filePath))

package/dist/captureReadiness.js

@@ -1,11 +1,4 @@
 "use strict";
-// Capture-readiness assessment for `codiedev doctor`. Answers: "from where I'm
-// standing right now, would a session actually capture?" — the blind spot that
-// let lean-container / submodule / no-remote setups silently produce zero
-// sessions while doctor's setup checks stayed green.
-//
-// Pure + fully injectable so it unit-tests without a real git repo. The default
-// production wiring (in doctor.ts) plugs in execSync + the real git helpers.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assessCaptureReadiness = assessCaptureReadiness;
 exports.assessWorkspaceRepos = assessWorkspaceRepos;
@@ -79,9 +72,6 @@ function formatRelativeAge(ms) {
         return `${h}h`;
     return `${Math.floor(h / 24)}d`;
 }
-// Turns the "last session captured" breadcrumb into a doctor line. This is the
-// payoff check: it lets a user confirm their most recent session actually
-// landed without opening the portal.
 function summarizeLastCapture(record, nowMs) {
     if (!record) {
         return {
@@ -98,44 +88,18 @@ function summarizeLastCapture(record, nowMs) {
     }
     return { status: "pass", detail: `last session captured ${age} ago` };
 }
-// ─── Capture-activity summarizer ──────────────────────────────────────────────
-// Turns the tail of ~/.codiedev/capture.log + a count of pending upload jobs
-// into a single doctor CheckResult-compatible {status, detail} object.
-//
-// Pure (no fs/os imports) — all data is injected by the caller (doctor.ts).
 const LOG_PATH_SUFFIX = "— details: ~/.codiedev/capture.log";
-// Parse regex: a valid structured line has exactly this shape.
-// stage is one of the four known stages; outcome is a bare token.
 const STRUCTURED_LINE_RE = /^(\S+) (capture-finish|upload|upload-deferred|stderr) session=(\S+) (\S+)(?: (.*))?$/;
-/** Append the shared log-path suffix to any detail string. */
 function withSuffix(detail) {
     return `${detail} ${LOG_PATH_SUFFIX}`;
 }
-// TLS-trust failure phrases/codes. These are what Node's TLS stack emits when
-// a middlebox (corporate proxy / VPN doing SSL inspection) re-signs HTTPS with
-// an internal CA. Node uses its OWN bundled Mozilla trust store — NOT the OS
-// store — so installing the corporate cert system-wide fixes curl/git but not
-// the CLI; only NODE_EXTRA_CA_CERTS (or an IT bypass) does.
-// "certificate has expired" is deliberately absent: that's a server-side cert
-// problem, not interception, and the hint would mislead.
 const TLS_INTERCEPTION_RE = /self.signed certificate|unable to verify the first certificate|unable to get local issuer certificate|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|UNABLE_TO_GET_ISSUER_CERT_LOCALLY|DEPTH_ZERO_SELF_SIGNED_CERT|CERT_UNTRUSTED/i;
-/**
- * When `text` (an error message, code, or capture.log detail) indicates a
- * TLS-trust failure from SSL inspection, return the remediation hint;
- * otherwise null.
- */
 function tlsInterceptionHint(text, host) {
     if (!TLS_INTERCEPTION_RE.test(text))
         return null;
     return (`your network is intercepting TLS (corporate proxy/VPN). Node ignores the OS cert store — ` +
         `set NODE_EXTRA_CA_CERTS to your corporate root CA file, or ask IT to bypass SSL inspection for ${host}`);
 }
-/**
- * Flatten a thrown fetch/network error to "<message> (<code>)". undici's
- * fetch wraps the real failure in TypeError("fetch failed") with the cause
- * chained on `.cause` — walk to the deepest cause so doctor reports the
- * actual TLS/socket error instead of "fetch failed".
- */
 function describeFetchError(err) {
     if (err === null || err === undefined)
         return "unknown error";
@@ -148,10 +112,6 @@ function describeFetchError(err) {
     const message = deepest.message || String(deepest);
     return deepest.code ? `${message} (${deepest.code})` : message;
 }
-/**
- * Derive remediation text and status from the last failing upload-ish line.
- * Inspects the `detail` field of the log line for http= and msg= tokens.
- */
 function failDetail(rawLine, outcome, lineDetail, backendHost) {
     const d = lineDetail ?? "";
     const truncated = rawLine.slice(0, 140);
@@ -182,10 +142,7 @@ function summarizeCaptureActivity(tailLines, pendingJobCount, backendHost) {
             continue;
         parsed.push({ ts: m[1], stage: m[2], session: m[3], outcome: m[4], detail: m[5], raw });
     }
-    // We care only about upload-ish lines (upload + upload-deferred).
-    // capture-finish and stderr lines are noise for this check.
     const uploadLines = parsed.filter((p) => p.stage === "upload" || p.stage === "upload-deferred");
-    // Rule 1: last upload-ish outcome is ERROR or gave-up → fail.
     if (uploadLines.length > 0) {
         const last = uploadLines[uploadLines.length - 1];
         if (last.outcome === "ERROR" || last.outcome === "gave-up") {
@@ -195,8 +152,6 @@ function summarizeCaptureActivity(tailLines, pendingJobCount, backendHost) {
             };
         }
     }
-    // Rule 2: pending jobs queued (last upload wasn't a hard failure, but
-    // retries are still in-flight).
     if (pendingJobCount > 0) {
         const noun = pendingJobCount === 1 ? "job" : "jobs";
         return {
@@ -204,15 +159,12 @@ function summarizeCaptureActivity(tailLines, pendingJobCount, backendHost) {
             detail: withSuffix(`${pendingJobCount} pending upload ${noun} queued for retry`),
         };
     }
-    // Rule 3: no upload-ish lines at all — log is empty, garbage-only, or
-    // only capture-finish lines.
     if (uploadLines.length === 0) {
         return {
             status: "warn",
             detail: withSuffix("no capture uploads recorded yet on this machine — run a session and exit, then re-run `codiedev doctor`"),
         };
     }
-    // Rule 4a: last upload-ish outcome is ok → pass.
     const last = uploadLines[uploadLines.length - 1];
     const hasOk = uploadLines.some((p) => p.outcome === "ok");
     if (last.outcome === "ok") {
@@ -221,9 +173,6 @@ function summarizeCaptureActivity(tailLines, pendingJobCount, backendHost) {
             detail: withSuffix(`last upload ok (${last.ts})`),
         };
     }
-    // Rule 4b: last is "deferred" — a throttled/scheduled defer was queued.
-    // If an ok exists somewhere in the tail → pass (next upload deferred is fine).
-    // If no ok exists → warn.
     if (last.outcome === "deferred") {
         if (hasOk) {
             return {
@@ -236,7 +185,6 @@ function summarizeCaptureActivity(tailLines, pendingJobCount, backendHost) {
             detail: withSuffix("deferred uploads were superseded but no completed upload found in the recent log"),
         };
     }
-    // Rule 4c: last is "superseded".
     if (hasOk) {
         return {
             status: "pass",
@@ -248,12 +196,7 @@ function summarizeCaptureActivity(tailLines, pendingJobCount, backendHost) {
         detail: withSuffix("deferred uploads were superseded but no completed upload found in the recent log"),
     };
 }
-// Server-confirmed "did my last session land?". Prefers portal truth over the
-// local 2xx breadcrumb; the highest-value branch is "uploaded locally but the
-// portal has no record" — the exact silent failure devs hit (2xx to nothing,
-// wrong identity, backend drop).
 function summarizeServerCapture(server, local, nowMs) {
-    // Endpoint unavailable / old backend → fall back to the local breadcrumb.
     if (server === null)
         return summarizeLastCapture(local, nowMs);
     if (server.found && server.latest) {
@@ -266,7 +209,6 @@ function summarizeServerCapture(server, local, nowMs) {
         }
         return { status: "pass", detail: `confirmed in the portal — last session captured ${age} ago` };
     }
-    // Server reachable but has no session for this user.
     if (local) {
         const age = formatRelativeAge(nowMs - local.recordedAt);
         return {

package/dist/captureSignals.js

@@ -15,7 +15,6 @@ const skillKey = (value) => typeof value === "string"
         .trim()
         .toLowerCase()
     : "";
-/** Compact diagnostic inputs only: never persist prompts, commands or tool output. */
 function parseCaptureSignals(content, source) {
     const timestamps = new Set();
     const invocationCounts = new Map();
@@ -24,8 +23,6 @@ function parseCaptureSignals(content, source) {
     let parsedRecords = 0, truncated = false;
     let premiumRequests, nanoAiu;
     let cursorSubagents;
-    // The skill content a harness loads after an invocation follows it in the
-    // transcript; a marker there names the artifact the invocation ran.
     const artifacts = new Map();
     let lastInvoked = null;
     const marker = (text) => {
@@ -91,10 +88,7 @@ function parseCaptureSignals(content, source) {
                 /^[a-z0-9][a-z0-9_.:-]{0,39}$/i.test(value))
                 entrypoints.add(value.toLowerCase());
         };
-        // Claude Code: "cli" at the terminal, "sdk-cli" for `claude -p` / SDK.
         entrypoint(e.entrypoint);
-        // Codex: session_meta.source is "cli", "vscode", "exec" (`codex exec`),
-        // "mcp", or an object for sub-agents. Namespaced so values never collide.
         if (e.type === "session_meta" && e.payload) {
             const src = e.payload.source;
             entrypoint(typeof src === "string"
@@ -106,12 +100,8 @@ function parseCaptureSignals(content, source) {
         if (e.type === "cursor.subagent_summary" && Number.isSafeInteger(e.count) && e.count > 0) {
             cursorSubagents = { count: e.count, truncated: e.truncated === true };
         }
-        // GitHub Copilot (normalized): one skill.invoked event per skill run,
-        // whether the user or the agent invoked it.
         if (e.type === "copilot.skill_invoked")
             addSkill(invocations, e.skill);
-        // pi (normalized): a `/skill:name` expansion or the agent reading a
-        // listed skill's SKILL.md, which is how pi runs skills.
         if (e.type === "pi.skill_invoked")
             addSkill(invocations, e.skill);
         if (e.type === "copilot.usage_summary") {
@@ -186,7 +176,6 @@ function parseCaptureSignals(content, source) {
         truncated,
     };
 }
-/** Add a launch value the hook detected (harnesses that do not record one). */
 function withLaunch(signals, launch) {
     if (!launch || !/^[a-z0-9][a-z0-9_.:-]{0,39}$/.test(launch))
         return signals;

package/dist/cli.js

@@ -1,18 +1,5 @@
 #!/usr/bin/env node
 "use strict";
-/**
- * Codiedev CLI dispatcher.
- *
- * Subcommands:
- *   codiedev connect                   — link agent CLIs to your org
- *   codiedev push <file>               — author/update a spec/review/decision/etc.
- *   codiedev pull <key>                — fetch an artifact by filename key
- *   codiedev ping <user> "<msg>"       — send a message (optionally --with <key>)
- *   codiedev inbox                     — list pings (use --unread to filter)
- *   codiedev read <ping-id>            — mark read + show full message
- *   codiedev note "<text>"             — capture a thought
- *   codiedev help                      — show this help
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 const connect_1 = require("./connect");
 const cliSession_1 = require("./cliSession");
@@ -33,11 +20,10 @@ const send_1 = require("./commands/send");
 const capture_1 = require("./commands/capture");
 const pack_1 = require("./commands/pack");
 const traces_1 = require("./commands/traces");
+const agents_1 = require("./commands/agents");
 const evals_1 = require("./commands/evals");
-// --- starter packs phase 2 ---
 const hookGate_1 = require("./packs/hookGate");
 const sync_1 = require("./packs/sync");
-// --- end starter packs ---
 const version_1 = require("./version");
 const HELP = `
 Codiedev CLI
@@ -51,7 +37,7 @@ Connect:
                                          Claude Code / Codex / Cursor /
                                          GitHub Copilot / pi to your org
   codiedev logout                        Sign this machine out
-  codiedev doctor                        Verify your setup after connecting
+  codiedev doctor                        Verify setup and capture
 
 Harness:
   codie                                  Launch the governed Codie harness.
@@ -98,6 +84,9 @@ Starter packs:
   codiedev pack status                   Installed packs, up to date or not
 
 Traces (agents on the gateway):
+  codiedev agents init | deploy | run | runs | show | secrets | webhook
+                                         Deploy agents and run them in fresh sandboxes
+                                         (codiedev agents help)
   codiedev traces agents                 Agents you maintain, with saved test cases
   codiedev traces cases <agent> [--dataset name [--version n]] [--model id]
                                          Pull an agent's test cases (or one dataset)
@@ -172,6 +161,7 @@ status sync never weakens it.
 const COMMAND_HELP = {
     pack: pack_1.PACK_HELP,
     traces: traces_1.TRACES_HELP,
+    agents: agents_1.AGENTS_HELP,
     evals: evals_1.EVALS_HELP,
     connect: `
 codiedev connect — link your agent CLI to Codiedev
@@ -183,10 +173,10 @@ codiedev connect — link your agent CLI to Codiedev
     - ~/.claude/CLAUDE.md instructions   (teaches Claude the commands)
     - ~/.codex/hooks.json hook           (same, for Codex)
     - ~/.codex/AGENTS.md instructions    (same, for Codex)
-    - ~/.cursor/hooks.json hooks         (session, prompt, security, capture)
+    - ~/.cursor/hooks.json hooks         (session, backup, capture)
     - ~/.cursor/rules/codiedev.mdc       (teaches Cursor the commands)
     - ~/.copilot/hooks/codiedev.json     (GitHub Copilot: VS Code + CLI capture)
-    - ~/.pi/agent/extensions/codiedev.ts (pi: session, prompt, security, capture)
+    - ~/.pi/agent/extensions/codiedev.ts (pi: session, prompt, capture)
     - ~/.pi/agent/AGENTS.md              (teaches pi the commands)
 
   Re-run anytime to swap accounts or refresh the instruction block.
@@ -440,8 +430,6 @@ Run 'codiedev help <command>' for each, or see the quick list:
   https://codiedev.com/portal/integrations/claude-code and run
   'codiedev connect --token'.
 `.trim();
-// Retired commands: say so instead of "Unknown command", since agent
-// instructions written by older installs may still reference them.
 const REMOVED_COMMANDS = {
     promote: "Share an auto-saved spec with 'Promote to team' in the portal's My artifacts list.",
     "reverse-ticket": "Use 'codiedev create-ticket' to draft Jira tickets.",
@@ -454,20 +442,15 @@ function removedCommand(command) {
 }
 async function main() {
     const [, , command, ...rest] = process.argv;
-    // --- starter packs: hook-gate runs inside agent hooks; stdout/stderr and
-    // the exit code belong to the wrapped command, so nothing else may run. ---
     if (command === "hook-gate") {
         (0, hookGate_1.runHookGateCli)(rest);
         return;
     }
-    // Daily "pack has updates" nudge from the cached status (local read only).
-    // stderr, so piped/--json output stays clean.
     if (command && !["pack", "packs", "help", "docs", "version", "--version", "-v", "--help", "-h"].includes(command) && !rest.includes("--json")) {
         const nag = (0, sync_1.packNagLine)();
         if (nag)
             console.error(`\n${nag}\n`);
     }
-    // --- end starter packs ---
     if (!command || command === "--help" || command === "-h") {
         console.log(HELP);
         return;
@@ -490,7 +473,6 @@ async function main() {
         console.log(DOCS);
         return;
     }
-    // Support `codiedev <command> --help` too.
     if (rest.includes("--help") || rest.includes("-h")) {
         if (COMMAND_HELP[command]) {
             console.log(COMMAND_HELP[command]);
@@ -501,8 +483,6 @@ async function main() {
         console.log(`codiedev v${version_1.CLI_VERSION}`);
         return;
     }
-    // Browser sign-in: refresh the access token (under the shared lock) before
-    // the command reads config. No-op for pasted API tokens.
     if (command !== "connect" && command !== "logout") {
         const fresh = await (0, cliSession_1.ensureFreshToken)({ configPath: utils_1.CONFIG_PATH }).catch(() => null);
         if (fresh?.status === "signed_out") {
@@ -515,9 +495,6 @@ async function main() {
                 await (0, connect_1.runConnect)(rest);
                 return;
             case "session-refresh": {
-                // Internal: the Codie engine's per-request hook asks for a fresh
-                // token when the current one has under 30 minutes left. Refreshes
-                // under the shared lock; prints nothing.
                 await (0, cliSession_1.ensureFreshToken)({ configPath: utils_1.CONFIG_PATH }, 60 * 60_000).catch(() => null);
                 return;
             }
@@ -558,7 +535,6 @@ async function main() {
                 return;
             case "inbox":
             case "check":
-                // Support `codiedev check inbox` as an alias.
                 if (command === "check" && rest[0] === "inbox") {
                     await (0, inbox_1.runInbox)(rest.slice(1));
                 }
@@ -592,6 +568,9 @@ async function main() {
             case "traces":
                 await (0, traces_1.runTraces)(rest);
                 return;
+            case "agents":
+                await (0, agents_1.runAgents)(rest);
+                return;
             case "evals":
                 await (0, evals_1.runEvals)(rest);
                 return;
@@ -611,7 +590,6 @@ async function main() {
                 await (0, pack_1.runPack)(rest);
                 return;
             case "capture":
-                // Back-compat alias for the earlier `codiedev capture <sub>` form.
                 await (0, capture_1.runCaptureCommand)(rest);
                 return;
             default: