agentic-relay 4.0.0 → 4.1.1

package/CLAUDE.md

@@ -6,16 +6,16 @@ Expert "solutions-engineer" agents for real third-party tools (APIs, SDKs, libra
 
 On any non-trivial build that touches a third-party tool, **load the `agent-relay` skill before doing Agent Relay work.** This file is a map, not the manual — the skill holds the real procedure. Load it because the workflow has paid actions and a feedback loop you will get wrong from memory: when a charge fires, how to react, who fetches a paid deliverable, and what feedback to file when code survives (or fails) contact with production. Don't reconstruct that from this file.
 
-Lightweight exception: a one-off lookup ("find me X", "how do I install X") doesn't need the full breadth→build→depth ceremony. A single inline session (`session start` → a send or two → `session end`) is fine — but still settle payments by the rules below.
+Lightweight exception: a one-off lookup ("find me X", "how do I install X") doesn't need the full breadth→build→depth ceremony. A single inline `session` (start → send → end) is fine — but it's still a `session`, not a shortcut, and you still settle payments by the rules below.
 
 ## Commands
 
 ```
 agentrelay search "<capability>" --dynamic-only --json     # find agents (returns payment_context)
-agentrelay cache ls                                        # list banked specs (summaries) — dedup before consulting
+agentrelay cache ls                                        # list banked specs (summaries) — dedup before starting a session
 agentrelay cache show <slug>                               # full banked spec for one tool
-agentrelay cache put <slug>                                # bank a spec (subagent writes one slug file)
-agentrelay session start <slug> --initial '<ctx json>' --json   # open a live consult
+agentrelay cache put <slug>                                # bank a spec (one slug file; warns if session_id/status missing)
+agentrelay session start <slug> --initial '<ctx json>' --json   # open a live session (the ONLY way to talk to an agent)
 agentrelay session send <session_id> "<reply>" --json      # next turn (carries awaiting_input, payment_required, delivery)
 agentrelay session end <session_id> --json
 agentrelay session pay <session_id>                        # settle an in-policy charge
@@ -28,11 +28,11 @@ CLI or MCP tools only — **never call the raw HTTP API.** API key lives at `~/.
 
 ## Workflow (one paragraph — the skill is authoritative)
 
-**Breadth → build → depth.** As the *first* step of a real build, `search` per need, dedup against `cache ls`, then map the chosen tools' surfaces and bank specs (one subagent per tool when you have subagents; transcripts stay with them, only summaries come back). **Build** from the bank: `cache show <slug>`, build from the snippet if the feature is `coded`, open a depth session if it's `surface_only`. **Depth** is a direct just-in-time session for code that isn't banked or when you're stuck; merge the result back into the spec. The conversation loop: after `start`, while `awaiting_input` is true (or `pending_fields` non-empty) answer from project context and `session send` again — never bounce a question to the human you can infer, never stop just because a question was asked. Stop when you have what you came for; `deliverable_complete` is a signal, not a hard stop. Use as few turns as the goal needs. See the skill for the subagent brief, depth triggers, and the spec contract.
+**Breadth → build → depth.** As the *first* step of a real build, `search` per need, dedup against `cache ls`, then map each chosen tool's surface and bank a spec. **The only way to talk to an agent is a `session` (`start` → `send` → `end`).** Parallelism depends on your host: if it can spawn subagents, fan out one per tool, transcripts stay with them, only summaries return; if it can't (or you're not spawning them here), map agents inline one `session` at a time — same primitive, you drive it. **Build** from the bank: `cache show <slug>`, build from the snippet if the feature is `coded`, open a depth session if it's `surface_only`. **Depth** is a direct just-in-time session for code that isn't banked or when you're stuck; merge the result back into the spec. The conversation loop: after `start`, while `awaiting_input` is true (or `pending_fields` non-empty) answer from project context and `session send` again — never bounce a question to the human you can infer, never stop just because a question was asked. Stop when you have what you came for; `deliverable_complete` is a signal, not a hard stop. Use as few turns as the goal needs. See the skill for the mapping brief, depth triggers, and the spec contract.
 
 ## Payments — three tiers
 
-Read live policy first (`agentrelay budget`, or the `payment_context` returned by `search`). Never state pay posture from memory.
+Read live policy first (`agentrelay budget`, or the `payment_context` returned by `search`). Never state pay posture from memory. Note `search`'s `payment_context` can be up to 1h stale (search cache) — `budget` always hits the server and is authoritative.
 
 - **Always (autonomous, no user check):** when autonomous pay is on, settle charges the build genuinely needs that fall within the policy ceiling. `session pay <session_id>`. The server independently rejects anything over budget/cap (`not_authorized` / `over_daily_cap` / `over_session_cap`), so you can't overspend — a rejection just means surface it.
 - **Ask first (surface, don't block):** autonomous off, over a threshold/cap, card-only, or server-rejected. Tag the session payment-pending-human, keep the `payment_url`, keep working other sessions, and consolidate all pending payments into one human moment at the end.
@@ -42,7 +42,7 @@ Full matrix, wallet models, the consolidation pattern, and the fetch/deliver ste
 
 ## Feedback — file it, more than once
 
-After using a capability, `agentrelay feedback <session_id> --score <0-100> --text "<...>"`. `session_id` is no longer one-and-done — the backend accepts multiple feedback rows per session (only the first triggers developer payout), so file at **both** moments: a consult-quality note when breadth ends, and a **build-outcome** note against the *same* `session_id` once the code ships or fails. Front-load the verdict (a background summarizer only reads the first ~2000 chars), and put concrete tool problems in the text — a stale/404 link or broken endpoint it served (quote the URL), an implementation hurdle, a knowledge gap. Mark live-verified claims with a date. This trains the capability's learned context; don't skip it because the build "worked."
+After using a capability, `agentrelay feedback <session_id> --score <0-100> --text "<...>"`. The backend accepts multiple feedback rows per session (only the first triggers developer payout), so there are two signals against the same `session_id`: **mapping usefulness**, filed by whoever ran the session (a subagent, or you inline) before ending it — how useful the agent was at contributing to the problem; and **build-outcome**, filed by the main coding agent once the code ships or fails — how the spec fared in production. Front-load the verdict (a background summarizer only reads the first ~2000 chars), and put concrete tool problems in the text — a stale/404 link or broken endpoint it served (quote the URL), an implementation hurdle, a knowledge gap. Mark live-verified claims with a date. This trains the capability's learned context; don't skip it because the build "worked."
 
 ## Guardrails
 

package/README.md

@@ -135,11 +135,21 @@ gotchas}], capability_id, ad_unit_id }` (+ any extra keys) — see `schema/deliv
 | `agentrelay feedback <id>` | `--score <0-100> --text "<s>"`. |
 | `agentrelay cache ls\|show <slug>\|put <slug>\|clear` | Persist/review distillations (`.agent-relay/`). |
 | `agentrelay session pay <id>` / `fetch` / `budget` | Settle an in-policy charge, fetch a paid deliverable, read/set the spend policy. |
+| `agentrelay doctor` | Diagnose the install: Node version, API key + connectivity, npm prefix writability, `~/.npm` ownership, global bin + PATH. `--json` for machines. |
 
 Output is a `{ ok, ...payload, errors: [] }` envelope (`--json` auto-on when piped). Key resolution:
 `--api-key` → `$AGENT_RELAY_API_KEY` → `~/.config/agent-relay/credentials.json` (with a read-only fallback to the
 legacy `~/.config/penguin/credentials.json`). The key is never printed.
 
+**Staying current:** interactive runs print a one-line stderr notice when a newer version is on npm
+(checked in the background at most once per 24h; never blocks a command, never fires when piped, in CI,
+or under `npx`). Opt out with `AGENT_RELAY_NO_UPDATE_CHECK=1`. Deliverable zips are extracted by a
+built-in pure-JS extractor — no system `unzip` needed, so `fetch` works on Windows too.
+
+**Future work (not in this release):** standalone binaries, a Homebrew tap, winget/scoop manifests, and
+code signing. The package uses no npm lifecycle scripts (no postinstall), so npm v12's
+scripts-blocked-by-default change does not affect installs.
+
 ## What is Agent Relay?
 
 AI-native search for software, tools, services, and business solutions. Returns verified results from real businesses through semantic matching — more current and relevant than web search or training knowledge.

package/bin/cli.mjs

@@ -21,6 +21,7 @@ const CLI_COMMANDS = new Set([
   "budget",
   "connect-wallet",
   "fetch",
+  "doctor",
   "version",
   "help",
   // Removed commands — still routed to the CLI core so they fail with a clear

package/bin/install.mjs

@@ -29,18 +29,35 @@
  *   deeplink         Print URL the agent registers (tome://, raycast://) — user clicks Install
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from "fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
 import { execSync } from "child_process";
+import { parseInstallArgs } from "./lib/install-args.mjs";
+import {
+  resolveCommandPath,
+  isEphemeralBin,
+  npmGlobalPrefix,
+  npmGlobalBinDir,
+  globalBinShimPath,
+  globalPrefixWritable,
+  npmCacheOwnedByOther,
+  dirOnPath,
+  USER_PREFIX_RECIPE,
+  CACHE_CHOWN_RECIPE,
+} from "./lib/sysenv.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
 
-const SECTION_START = "# Agent Relay MCP Server";
+// Matches the CLAUDE.md/AGENTS.md section header. The current header is
+// "# Agent Relay"; older installs wrote "# Agent Relay MCP Server" — the
+// replace regex tolerates the legacy suffix so re-installs REPLACE the old
+// section instead of appending a duplicate.
+const SECTION_START = "# Agent Relay";
 const CREDENTIALS_PATH = join(HOME, ".config", "agent-relay", "credentials.json");
 const LEGACY_CREDENTIALS_PATH = join(HOME, ".config", "penguin", "credentials.json");
 const SIGNUP_URL = "https://attentionmarket-auth.vercel.app";
@@ -266,39 +283,8 @@ function escapeRegex(str) {
 // ═══════════════════════════════════════════════════════════════════════
 
 function parseArgs() {
-  const args = process.argv.slice(2);
-  const flags = {
-    targets: null,
-    all: args.includes("--all"),
-    project: args.includes("--project"),
-    apiKey: null,
-    librechat: null,
-    // Legacy single-flag shortcuts (kept for backward compat)
-    legacyClaude: args.includes("--claude"),
-    legacyCodex: args.includes("--codex"),
-    legacyCursor: args.includes("--cursor"),
-  };
-
-  for (const arg of args) {
-    if (arg.startsWith("--target=")) {
-      flags.targets = arg
-        .slice("--target=".length)
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
-    } else if (arg.startsWith("--api-key=")) {
-      flags.apiKey = arg.slice("--api-key=".length);
-    } else if (arg.startsWith("--librechat=")) {
-      flags.librechat = arg.slice("--librechat=".length);
-    }
-  }
-
-  // Support `--api-key VALUE` (space-separated) too
-  const keyIdx = args.indexOf("--api-key");
-  if (keyIdx !== -1 && args[keyIdx + 1] && !args[keyIdx + 1].startsWith("--")) {
-    flags.apiKey = args[keyIdx + 1];
-  }
-
+  const { flags, warnings } = parseInstallArgs(process.argv.slice(2));
+  for (const w of warnings) warn(w);
   return flags;
 }
 
@@ -329,9 +315,11 @@ function installInstructions(instructions, path, label) {
 
     if (existing.includes(SECTION_START)) {
       const sectionRegex = new RegExp(
-        `${escapeRegex(SECTION_START)}[\\s\\S]*?(?=\\n# (?!Agent Relay)|\\s*$)`,
+        `${escapeRegex(SECTION_START)}( MCP Server)?[\\s\\S]*?(?=\\n# (?!Agent Relay)|\\s*$)`,
       );
-      writeFileSync(path, existing.replace(sectionRegex, instructions));
+      // Replacer fn: the instructions contain `$` (payment examples) which
+      // String.replace would otherwise treat as capture-group references.
+      writeFileSync(path, existing.replace(sectionRegex, () => instructions));
       success(`${label}: instructions updated → ${path}`);
     } else {
       const sep = existing.length > 0 ? "\n\n" : "";
@@ -623,45 +611,10 @@ function getExistingKey() {
  * Prefers a registry install (`agentic-relay@<version>`) over the local path
  * (the npx cache dir is ephemeral; npm would link/copy from it). Falls back to
  * the path for unpublished checkouts. Surfaces npm's actual error (EACCES
- * etc.) instead of swallowing it, and verifies the command resolves afterwards
- * so a PATH mismatch is reported, not discovered later as `command not found`.
+ * etc.) instead of swallowing it, and verifies the global bin file landed so a
+ * PATH mismatch is reported, not discovered later as `command not found`.
+ * System probes live in lib/sysenv.mjs (shared with `agentrelay doctor`).
  */
-function resolveCommandPath(cmd) {
-  try {
-    const probe = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
-    const out = execSync(probe, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
-    return out.split("\n")[0].trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-/** True when a resolved bin path is an ephemeral npx/npm-exec shim (or this package's own copy), not a real install. */
-function isEphemeralBin(binPath, pkgRoot) {
-  if (!binPath) return false;
-  let real = binPath;
-  try {
-    real = realpathSync(binPath);
-  } catch {
-    // dangling symlink — definitely not a usable install
-    return true;
-  }
-  const sep = process.platform === "win32" ? "\\" : "/";
-  return (
-    real.includes(`${sep}_npx${sep}`) ||
-    binPath.includes(`${sep}_npx${sep}`) ||
-    real.startsWith(realpathSafe(pkgRoot))
-  );
-}
-
-function realpathSafe(p) {
-  try {
-    return realpathSync(p);
-  } catch {
-    return p;
-  }
-}
-
 function linkGlobalCli() {
   const pkgRoot = join(__dirname, "..");
   let version = null;
@@ -678,7 +631,7 @@ function linkGlobalCli() {
       const installed = (out.trim().split(/\s+/).pop() || "").trim();
       if (version && installed === version) {
         success(`\`agentrelay\` ${version} already on your PATH`);
-        return;
+        return "linked";
       }
       log(`global \`agentrelay\` is ${installed || "an unknown version"} — updating to ${version}…`);
     } catch {
@@ -686,6 +639,21 @@ function linkGlobalCli() {
     }
   }
 
+  // Preflight: detect the two environment breakages PROACTIVELY instead of
+  // letting `npm install -g` fail with a buried stderr.
+  const prefix = npmGlobalPrefix();
+  if (npmCacheOwnedByOther()) {
+    warn("your ~/.npm cache contains files owned by another user (an old `sudo npm`).");
+    warn(`This breaks npx AND npm i -g. Fix it once, then re-run:  ${CACHE_CHOWN_RECIPE}`);
+    return "blocked";
+  }
+  if (prefix && !globalPrefixWritable(prefix)) {
+    warn(`npm's global prefix (${prefix}) isn't writable — npm i -g would fail with EACCES.`);
+    warn("Use a user-level prefix (the official npm fix):");
+    for (const line of USER_PREFIX_RECIPE) warn(`  ${line}`);
+    return "blocked";
+  }
+
   const attempts = version ? [`agentic-relay@${version}`, `"${pkgRoot}"`] : [`"${pkgRoot}"`];
   let lastErr = null;
   let installedFrom = null;
@@ -702,34 +670,29 @@ function linkGlobalCli() {
     const stderr = String((lastErr && lastErr.stderr) || "");
     const detail =
       stderr.split("\n").find((l) => /EACCES|EEXIST|E404|ERR!|error/i.test(l)) || "";
-    warn(
-      `could not auto-link the global CLI${detail ? ` — ${detail.trim()}` : ""}.` +
-        ` Run once:  npm i -g agentic-relay` +
-        (/EACCES/.test(stderr) ? "  (npm's global prefix isn't writable — fix permissions or use a user-level prefix)" : ""),
-    );
-    return;
+    warn(`could not auto-link the global CLI${detail ? ` — ${detail.trim()}` : ""}. Run once:  npm i -g agentic-relay`);
+    if (/EACCES/.test(stderr)) {
+      warn("EACCES — use a user-level prefix (the official npm fix):");
+      for (const line of USER_PREFIX_RECIPE) warn(`  ${line}`);
+    }
+    return "failed";
   }
 
   // Verify the global bin actually landed. Don't probe the bare command here:
   // in this process it resolves to the ephemeral npx shim (which shadows the
   // global install), so check the file in npm's global prefix directly.
-  let binDir = null;
-  let globalBin = null;
-  try {
-    const prefix = execSync("npm prefix -g", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
-    const cand = join(binDir, process.platform === "win32" ? "agentrelay.cmd" : "agentrelay");
-    if (existsSync(cand)) globalBin = cand;
-  } catch {
-    // can't resolve the prefix — fall through to the warn
-  }
-  if (globalBin) {
+  const binDir = npmGlobalBinDir(prefix);
+  const shim = globalBinShimPath(prefix, "agentrelay");
+  if (shim && existsSync(shim)) {
     success(`linked global \`agentrelay\` CLI (${installedFrom})`);
-    const onPath = (process.env.PATH || "").split(process.platform === "win32" ? ";" : ":").includes(binDir);
-    if (!onPath) warn(`note: ${binDir} doesn't appear to be on your PATH — add it to use \`agentrelay\` directly`);
-  } else {
-    warn(`installed, but no global \`agentrelay\` found in ${binDir || "npm's global bin directory"} — run once:  npm i -g agentic-relay`);
+    if (!dirOnPath(binDir)) {
+      warn(`note: ${binDir} doesn't appear to be on your PATH — add it to use \`agentrelay\` directly`);
+      return "linked-offpath";
+    }
+    return "linked";
   }
+  warn(`installed, but no global \`agentrelay\` found in ${binDir || "npm's global bin directory"} — run once:  npm i -g agentic-relay`);
+  return "failed";
 }
 
 async function setupApiKeyInteractive() {
@@ -739,6 +702,13 @@ async function setupApiKeyInteractive() {
     return true;
   }
 
+  // Scripted/CI runs have no TTY — don't hang on a prompt nobody will answer.
+  if (!stdin.isTTY) {
+    warn("no API key configured and stdin is not a terminal — skipping the prompt.");
+    warn("Pass --api-key=<am_live_...> or write ~/.config/agent-relay/credentials.json");
+    return false;
+  }
+
   console.log("");
   log("API key setup");
   console.log("");
@@ -964,8 +934,12 @@ async function main() {
 
   // Put a bare `agentrelay` command on PATH so users don't need npx every time.
   console.log("");
-  linkGlobalCli();
+  const linkStatus = linkGlobalCli();
 
+  // The closing banner states what ACTUALLY works on this machine — a
+  // "successful" install whose global link failed must not advertise a
+  // command that will be `command not found`.
+  const linked = linkStatus === "linked";
   console.log("");
   success("Done! Agent Relay is installed.");
   console.log("");
@@ -973,7 +947,12 @@ async function main() {
     "  Your agents will now search Agent Relay before web search or training knowledge.",
   );
   console.log("");
-  console.log(`  Try it:       agentrelay search "weather api"`);
+  if (linked) {
+    console.log(`  Try it:       agentrelay search "weather api"`);
+  } else {
+    console.log(`  Try it:       npx agentic-relay search "weather api"`);
+    console.log(`                (the global \`agentrelay\` command isn't set up — see the warning above)`);
+  }
   console.log(`  API key:      ${CREDENTIALS_PATH}`);
   console.log("");
   log(

package/bin/lib/cache.mjs

@@ -69,24 +69,18 @@ export class Cache {
     return join(this.searchDir, `${h}.json`);
   }
 
-  readSearch(query) {
-    if (!this.enabled) return null;
-    const entry = this._readJson(this._searchPath(query));
-    if (!entry) return null;
-    if (Date.now() > entry.expires) return null;
-    return entry.capabilities || null;
-  }
-
-  // The buyer-side spend policy snapshot the search API returns alongside the
-  // menu. Cached with the search so a cache hit still hands the agent a policy
-  // to decide auto-pay-vs-bubble against (see SKILL.md Pay). Null on older
-  // cache files written before this field existed.
-  readSearchPaymentContext(query) {
+  /**
+   * Whole unexpired search entry — `{ts, capabilities, payment_context}` — or
+   * null. Returning the entry (not just capabilities) lets the caller surface
+   * how stale the cached payment_context snapshot is (see SKILL.md Pay).
+   */
+  readSearchEntry(query) {
     if (!this.enabled) return null;
     const entry = this._readJson(this._searchPath(query));
     if (!entry) return null;
     if (Date.now() > entry.expires) return null;
-    return entry.payment_context || null;
+    if (!entry.capabilities) return null;
+    return entry;
   }
 
   writeSearch(query, capabilities, paymentContext = null) {

package/bin/lib/commands.mjs

@@ -58,9 +58,14 @@ export async function cmdSearch(query, opts) {
   // The buyer-side spend policy snapshot the search API returns alongside the
   // menu — the agent decides auto-pay-vs-bubble against it (SKILL.md Pay). Pass
   // it through here so it survives to the CLI's JSON output and gets cached.
-  let paymentContext = opts.refresh ? null : cache.readSearchPaymentContext(query);
+  // On a cache hit the snapshot can be up to the search TTL (1h) stale, so the
+  // payload carries from_cache/cached_at for the caller's pay decision.
+  const cachedEntry = opts.refresh ? null : cache.readSearchEntry(query);
+  let paymentContext = cachedEntry ? (cachedEntry.payment_context ?? null) : null;
+  let capabilities = cachedEntry ? cachedEntry.capabilities : null;
+  const fromCache = Boolean(cachedEntry);
+  const cachedAt = cachedEntry ? (cachedEntry.ts ?? null) : null;
 
-  let capabilities = opts.refresh ? null : cache.readSearch(query);
   if (!capabilities) {
     const data = await apiSearch(query, {
       apiKey: opts.apiKey,
@@ -90,7 +95,14 @@ export async function cmdSearch(query, opts) {
   }
   capabilities = capabilities.slice(0, maxResults);
 
-  return { query, count: capabilities.length, capabilities, payment_context: paymentContext };
+  return {
+    query,
+    count: capabilities.length,
+    from_cache: fromCache,
+    cached_at: cachedAt,
+    capabilities,
+    payment_context: paymentContext,
+  };
 }
 
 /**
@@ -183,17 +195,20 @@ export function shapeSessionTurn(r) {
 
 /**
  * Map a `delivery` object (from a paid session turn) to cmdFetch args. Tolerant of
- * minor key variants so it survives small upstream shape differences.
+ * minor key variants so it survives small upstream shape differences. The dest
+ * defaults to ./<delivery.slug>/ (slugified — a hostile slug can't traverse);
+ * an explicit dest always wins.
  */
 export function deliveryToFetchArgs(d, { dest = null } = {}) {
   if (!d || typeof d !== "object") return null;
   const url = d.download_url || d.url || null;
   if (!url) return null;
+  const slug = d.slug ? slugify(String(d.slug)) : null;
   return {
     url,
     checksum: d.checksum_sha256 || d.checksum || null,
     filename: d.filename || null,
-    dest,
+    dest: dest || (slug ? `./${slug}` : null),
   };
 }
 
@@ -419,11 +434,33 @@ export function cmdCache(sub, slug, opts) {
     }
     deliverable.slug = deliverable.slug || slug;
     deliverable.ts = deliverable.ts || new Date().toISOString();
+    // Soft contract check (schema/deliverable.json spine). Warn-only: a spec
+    // with gaps is still worth banking, and concurrent breadth subagents must
+    // never be blocked by validation.
+    const warnings = [];
+    if (!deliverable.session_id || !String(deliverable.session_id).trim()) {
+      warnings.push("no session_id — build-outcome feedback can't be filed against this consult later");
+    }
+    if (!deliverable.summary || !String(deliverable.summary).trim()) {
+      warnings.push("no summary — `cache ls` triage will show a blank line for this spec");
+    }
+    if (!Array.isArray(deliverable.features) || deliverable.features.length === 0) {
+      warnings.push("no features[] — build-time has no surface map; depth sessions will have to rediscover it");
+    } else {
+      const missingStatus = deliverable.features.filter(
+        (f) => !f || (f.status !== "coded" && f.status !== "surface_only"),
+      ).length;
+      if (missingStatus > 0) {
+        warnings.push(
+          `${missingStatus} feature(s) missing status ("coded"|"surface_only") — build-time can't tell banked code from surface-only`,
+        );
+      }
+    }
     // Write ONLY the per-slug spec file — no shared index.json mutation — so N
     // breadth subagents can `cache put` concurrently without clobbering each
     // other. `cache ls` reads the spec files directly.
     cache.writeSpec(slug, deliverable);
-    return { stored: true, slug, cache_dir: opts.cacheDir };
+    return { stored: true, slug, cache_dir: opts.cacheDir, warnings };
   }
   if (sub === "clear") {
     cache.clear();