crewhaus 0.1.3 → 0.1.4

package/README.md

@@ -11,7 +11,7 @@ CrewHaus compiles one spec into the shape each situation calls for — a CLI age
 The fastest path is the self-contained binary — one file, no Bun/Node required:
 
 ```bash
-brew install crewhaus/tap/crewhaus          # macOS / Linux (Homebrew)
+brew tap crewhaus/tap && brew install crewhaus          # macOS / Linux (Homebrew)
 scoop install crewhaus                       # Windows (Scoop; see repo for the bucket)
 winget install CrewHaus.CLI                   # Windows (winget)
 # Debian / Ubuntu (apt): signed repo at https://crewhaus.github.io/apt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewhaus",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "CrewHaus — the meta-harness compiler for AI agents. Compile one crewhaus.yaml spec into a CLI agent, channel bot, RAG pipeline, multi-agent crew, eval harness, voice or browser agent, and more.",
   "keywords": [
@@ -28,69 +28,69 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/adapter-anthropic": "0.1.3",
-    "@crewhaus/agent-context-isolation": "0.1.3",
-    "@crewhaus/audit-log": "0.1.3",
-    "@crewhaus/eval-optimizer-orchestrator": "0.1.3",
-    "@crewhaus/prompt-optimizer": "0.1.3",
-    "@crewhaus/prompt-optimizer-claude": "0.1.3",
-    "@crewhaus/justification-judge-claude": "0.1.3",
-    "@crewhaus/spec-patch": "0.1.3",
-    "@crewhaus/canary-controller": "0.1.3",
-    "@crewhaus/compiler": "0.1.3",
-    "@crewhaus/computer-use-driver": "0.1.3",
-    "@crewhaus/context-bundle": "0.1.3",
-    "@crewhaus/deployment-controller": "0.1.3",
-    "@crewhaus/egress-classifier": "0.1.3",
-    "@crewhaus/egress-matcher-semantic": "0.1.3",
-    "@crewhaus/embedder": "0.1.3",
-    "@crewhaus/errors": "0.1.3",
-    "@crewhaus/eval-dataset": "0.1.3",
-    "@crewhaus/eval-grader": "0.1.3",
-    "@crewhaus/eval-report": "0.1.3",
-    "@crewhaus/eval-runner": "0.1.3",
-    "@crewhaus/hooks-engine": "0.1.3",
-    "@crewhaus/infra-utils": "0.1.3",
-    "@crewhaus/ir": "0.1.3",
-    "@crewhaus/logging": "0.1.3",
-    "@crewhaus/mcp-host": "0.1.3",
-    "@crewhaus/model-router": "0.1.3",
-    "@crewhaus/migration-engine": "0.1.3",
-    "@crewhaus/migration-runner": "0.1.3",
-    "@crewhaus/permission-engine": "0.1.3",
-    "@crewhaus/run-context": "0.1.3",
-    "@crewhaus/runtime-core": "0.1.3",
-    "@crewhaus/secrets-manager": "0.1.3",
-    "@crewhaus/session-store": "0.1.3",
-    "@crewhaus/spec-registry": "0.1.3",
-    "@crewhaus/skills-registry": "0.1.3",
-    "@crewhaus/slash-commands": "0.1.3",
-    "@crewhaus/spec": "0.1.3",
-    "@crewhaus/sub-agent-spawner": "0.1.3",
-    "@crewhaus/trace-event-bus": "0.1.3",
-    "@crewhaus/tool-bash": "0.1.3",
-    "@crewhaus/tool-builder": "0.1.3",
-    "@crewhaus/tool-catalog": "0.1.3",
-    "@crewhaus/tool-codegraph": "0.1.3",
-    "@crewhaus/tool-fetch": "0.1.3",
-    "@crewhaus/tool-fs": "0.1.3",
-    "@crewhaus/tool-image": "0.1.3",
-    "@crewhaus/tool-image-generation": "0.1.3",
-    "@crewhaus/tool-document-ingest": "0.1.3",
-    "@crewhaus/tool-mcp": "0.1.3",
-    "@crewhaus/tool-mouse-keyboard": "0.1.3",
-    "@crewhaus/tool-navigate": "0.1.3",
-    "@crewhaus/tool-screen-capture": "0.1.3",
-    "@crewhaus/tool-task": "0.1.3",
-    "@crewhaus/tool-todo": "0.1.3",
-    "@crewhaus/tool-vision-grounding": "0.1.3",
-    "@crewhaus/tool-web": "0.1.3",
-    "@crewhaus/docker-images": "0.1.3",
-    "@crewhaus/crewhaus-cloud": "0.1.3",
-    "@crewhaus/federation-discovery": "0.1.3",
-    "@crewhaus/sandbox": "0.1.3",
-    "@crewhaus/sandbox-image-registry": "0.1.3",
-    "@crewhaus/compliance-controls": "0.1.3"
+    "@crewhaus/adapter-anthropic": "0.1.4",
+    "@crewhaus/agent-context-isolation": "0.1.4",
+    "@crewhaus/audit-log": "0.1.4",
+    "@crewhaus/eval-optimizer-orchestrator": "0.1.4",
+    "@crewhaus/prompt-optimizer": "0.1.4",
+    "@crewhaus/prompt-optimizer-claude": "0.1.4",
+    "@crewhaus/justification-judge-claude": "0.1.4",
+    "@crewhaus/spec-patch": "0.1.4",
+    "@crewhaus/canary-controller": "0.1.4",
+    "@crewhaus/compiler": "0.1.4",
+    "@crewhaus/computer-use-driver": "0.1.4",
+    "@crewhaus/context-bundle": "0.1.4",
+    "@crewhaus/deployment-controller": "0.1.4",
+    "@crewhaus/egress-classifier": "0.1.4",
+    "@crewhaus/egress-matcher-semantic": "0.1.4",
+    "@crewhaus/embedder": "0.1.4",
+    "@crewhaus/errors": "0.1.4",
+    "@crewhaus/eval-dataset": "0.1.4",
+    "@crewhaus/eval-grader": "0.1.4",
+    "@crewhaus/eval-report": "0.1.4",
+    "@crewhaus/eval-runner": "0.1.4",
+    "@crewhaus/hooks-engine": "0.1.4",
+    "@crewhaus/infra-utils": "0.1.4",
+    "@crewhaus/ir": "0.1.4",
+    "@crewhaus/logging": "0.1.4",
+    "@crewhaus/mcp-host": "0.1.4",
+    "@crewhaus/model-router": "0.1.4",
+    "@crewhaus/migration-engine": "0.1.4",
+    "@crewhaus/migration-runner": "0.1.4",
+    "@crewhaus/permission-engine": "0.1.4",
+    "@crewhaus/run-context": "0.1.4",
+    "@crewhaus/runtime-core": "0.1.4",
+    "@crewhaus/secrets-manager": "0.1.4",
+    "@crewhaus/session-store": "0.1.4",
+    "@crewhaus/spec-registry": "0.1.4",
+    "@crewhaus/skills-registry": "0.1.4",
+    "@crewhaus/slash-commands": "0.1.4",
+    "@crewhaus/spec": "0.1.4",
+    "@crewhaus/sub-agent-spawner": "0.1.4",
+    "@crewhaus/trace-event-bus": "0.1.4",
+    "@crewhaus/tool-bash": "0.1.4",
+    "@crewhaus/tool-builder": "0.1.4",
+    "@crewhaus/tool-catalog": "0.1.4",
+    "@crewhaus/tool-codegraph": "0.1.4",
+    "@crewhaus/tool-fetch": "0.1.4",
+    "@crewhaus/tool-fs": "0.1.4",
+    "@crewhaus/tool-image": "0.1.4",
+    "@crewhaus/tool-image-generation": "0.1.4",
+    "@crewhaus/tool-document-ingest": "0.1.4",
+    "@crewhaus/tool-mcp": "0.1.4",
+    "@crewhaus/tool-mouse-keyboard": "0.1.4",
+    "@crewhaus/tool-navigate": "0.1.4",
+    "@crewhaus/tool-screen-capture": "0.1.4",
+    "@crewhaus/tool-task": "0.1.4",
+    "@crewhaus/tool-todo": "0.1.4",
+    "@crewhaus/tool-vision-grounding": "0.1.4",
+    "@crewhaus/tool-web": "0.1.4",
+    "@crewhaus/docker-images": "0.1.4",
+    "@crewhaus/crewhaus-cloud": "0.1.4",
+    "@crewhaus/federation-discovery": "0.1.4",
+    "@crewhaus/sandbox": "0.1.4",
+    "@crewhaus/sandbox-image-registry": "0.1.4",
+    "@crewhaus/compliance-controls": "0.1.4"
   },
   "devDependencies": {
     "zod": "^3.23.8"

package/src/index.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { parseSpec } from "@crewhaus/spec";
@@ -213,6 +213,35 @@ describe("crewhaus compile", () => {
     expect(existsSync(join(outDir, "agent.ts"))).toBe(false);
   });
 
+  // A malformed credential env-ref (`$lowercase` on a Slack token) is a hard
+  // compile error from lowerCredential(). It must render as a clean die()
+  // one-liner — exit 1, `crewhaus: ` prefix, no uncaught stack trace — on BOTH
+  // the --emit-ir and bundle paths (the lower() catch routes CompilerError, not
+  // just SpecParseError, through die()).
+  const BAD_CRED_SPEC =
+    "name: status-bot\ntarget: channel\nagent:\n  model: claude-sonnet-4-6\n  instructions: announce status\nchannels:\n  slack:\n    botToken: $slack_bot_token\n    signingSecret: $SLACK_SIGNING_SECRET\nrouting:\n  sessionKey: thread\n";
+
+  for (const mode of ["--emit-ir", "bundle"] as const) {
+    test(`compile (${mode}) on a malformed credential $ref fails cleanly (die, not crash)`, async () => {
+      const specPath = join(tmp, "crewhaus.yaml");
+      writeFileSync(specPath, BAD_CRED_SPEC);
+      const outDir = join(tmp, "out");
+      const argv =
+        mode === "--emit-ir"
+          ? ["compile", specPath, "--emit-ir"]
+          : ["compile", specPath, "-o", outDir];
+      const result = await runCli(argv);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain(
+        'crewhaus: channels.slack.botToken value "$slack_bot_token" looks like an environment reference',
+      );
+      // Not an uncaught crash: no error-class name, no "at file:line:col" frame.
+      expect(result.stderr).not.toContain("CompilerError");
+      expect(result.stderr).not.toMatch(/\bat .+:\d+:\d+/);
+      if (mode === "bundle") expect(existsSync(join(outDir, "agent.ts"))).toBe(false);
+    });
+  }
+
   // (c) CLEAN spec still compiles by default (no flag, no opt-out).
   test("compile (no flag) on a clean (toolless) spec still emits and exits 0", async () => {
     const result = await runCli(["compile", HELLO_SPEC, "-o", tmp]);
@@ -663,13 +692,21 @@ describe("crewhaus optimize --budget-usd", () => {
 });
 
 describe("crewhaus help and unknown subcommand", () => {
-  test("--help prints usage listing all four subcommands", async () => {
-    const result = await runCli(["--help"]);
+  for (const flag of ["--help", "-h"]) {
+    test(`${flag} prints usage to stdout and exits 0 (works in \`set -e\` health checks)`, async () => {
+      const result = await runCli([flag]);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("compile");
+      expect(result.stdout).toContain("run");
+      expect(result.stdout).toContain("init");
+      expect(result.stdout).toContain("doctor");
+    });
+  }
+
+  test("no subcommand prints usage to stderr and exits 1 (usage error)", async () => {
+    const result = await runCli([]);
     expect(result.exitCode).toBe(1);
-    expect(result.stderr).toContain("compile");
-    expect(result.stderr).toContain("run");
-    expect(result.stderr).toContain("init");
-    expect(result.stderr).toContain("doctor");
+    expect(result.stderr).toContain("usage: crewhaus");
   });
 
   test("unknown subcommand exits 1 with a clear message", async () => {
@@ -679,6 +716,89 @@ describe("crewhaus help and unknown subcommand", () => {
   });
 });
 
+describe("crewhaus secrets backend selection", () => {
+  test("--backend vault errors clearly instead of silently using env-var", async () => {
+    const result = await runCli(["secrets", "doctor", "--backend", "vault"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("vault backend is not wired into the CLI");
+  });
+
+  test("an unknown backend is rejected", async () => {
+    const result = await runCli(["secrets", "doctor", "--backend", "bogus"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('unknown secrets backend "bogus"');
+  });
+
+  test("--backend file rotates into a not-yet-existing root dir (auto-mkdir)", async () => {
+    const root = join(tmp, "nested", "secrets");
+    const result = await runCli([
+      "secrets",
+      "rotate",
+      "demo",
+      "--backend",
+      "file",
+      "--root-dir",
+      root,
+    ]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("rotated demo");
+    expect(existsSync(join(root, "demo"))).toBe(true);
+  });
+});
+
+describe("crewhaus cost-summary", () => {
+  const SESSION_ID = "sess_00000000000000ab";
+
+  function seedSession(lines: ReadonlyArray<unknown>): void {
+    const dir = join(tmp, ".crewhaus", "sessions");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, `${SESSION_ID}.jsonl`),
+      `${lines.map((l) => JSON.stringify(l)).join("\n")}\n`,
+    );
+  }
+
+  test("sums cost_accrual events written in the real event-log envelope shape", async () => {
+    seedSession([
+      { ts: 1, version: 1, kind: "user_message", payload: { content: "hi" } },
+      {
+        ts: 2,
+        version: 1,
+        kind: "cost_accrual",
+        payload: { provider: "anthropic", modelId: "claude-sonnet-4-6", costUsdMicros: 450 },
+      },
+      {
+        ts: 3,
+        version: 1,
+        kind: "cost_accrual",
+        payload: { provider: "anthropic", modelId: "claude-sonnet-4-6", costUsdMicros: 300 },
+      },
+    ]);
+    const result = await runCli(["cost-summary", "--session", SESSION_ID, "--format", "json"], {
+      cwd: tmp,
+    });
+    expect(result.exitCode).toBe(0);
+    const out = JSON.parse(result.stdout) as {
+      count: number;
+      totalUsdMicros: number;
+      byProvider: Record<string, number>;
+    };
+    expect(out.count).toBe(2);
+    expect(out.totalUsdMicros).toBe(750);
+    expect(out.byProvider["anthropic"]).toBe(750);
+  });
+
+  test("still reads flat (non-enveloped) cost_accrual lines for back-compat", async () => {
+    seedSession([{ kind: "cost_accrual", provider: "openai", costUsdMicros: 1000 }]);
+    const result = await runCli(["cost-summary", "--session", SESSION_ID, "--format", "json"], {
+      cwd: tmp,
+    });
+    expect(result.exitCode).toBe(0);
+    const out = JSON.parse(result.stdout) as { totalUsdMicros: number };
+    expect(out.totalUsdMicros).toBe(1000);
+  });
+});
+
 describe("crewhaus version", () => {
   const pkgVersion = (
     JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf-8")) as {

package/src/index.ts

@@ -296,62 +296,76 @@ const FEDERATION_SCHEMA: ParseArgsSchema = {
   ],
 };
 
+function usageText(): string {
+  return [
+    "usage: crewhaus <subcommand> [args]",
+    "",
+    "subcommands:",
+    "  compile <spec.yaml> -o <out-dir>     compile a spec to a runnable bundle",
+    "                                       (fails if an outward tool is left non-external — FR-002)",
+    "                  [--allow-unmarked-sinks]  opt out of the external-sink scope gate",
+    "  compile <spec.yaml> --emit-ir        print the lowered IR as JSON (debug)",
+    "  run <spec.yaml> [--model <model>]    compile in-memory and execute the agent",
+    "                  [--resume <id>]      resume a specific session (cli targets only)",
+    "                  [--continue]         resume the most-recent session (cli targets only)",
+    "                  [--prompt <text>]    initial user prompt (browser targets; defaults to stdin)",
+    "                  [--justification-judge rule-based|claude]  Pillar 3 intent-gate judge (FR-004)",
+    "                  [--egress-matcher substring|semantic]  Pillar 3 sink-side matcher (FR-006)",
+    "                  [--egress-embedder <model>]  embedder for --egress-matcher semantic",
+    "  eval <spec.yaml> --dataset <data>    run the agent against a dataset and grade",
+    "       --graders <graders.yaml>       (deterministic graders + LLM-as-judge)",
+    "       [--judge-model <model>] [--concurrency N] [--seed N] -o <out-dir>",
+    "  eval-report diff <prev> <new>        compare two eval runs and emit a diff report",
+    "       [-o <out-dir>]",
+    "  optimize <spec.yaml> --dataset <data> --graders <graders.yaml>",
+    "       [--mutator rule-based|claude] [--iterations N] [--seed N]",
+    "       [--budget-usd N]                     stop a model-driven run before it exceeds $N (FR-003)",
+    "       [--write-back] [-o <out-dir>]        active eval-driven optimization (Pillar 2)",
+    "  init [name]                          scaffold a new crewhaus.yaml",
+    "  doctor                               check environment health",
+    "  context --bundle [-o <file>]         emit a single-markdown orientation manifest",
+    "       [--factory-root <p>] [--docs-root <p>] [--demos-root <p>]",
+    "  cost-summary --session <id>          summarize cost_accrual events for a session",
+    "  secrets doctor                       list known secrets via the configured backend",
+    "  secrets rotate <name> [--value V]    rotate a named secret (file backend)",
+    "  spec put|list|get|pin|alias ...      versioned spec storage (Section 28 spec-registry)",
+    "  deploy promote|rollback ...          re-pin a spec for an environment (Section 28)",
+    "  migrate-all --from N --to N          batch-migrate every spec in the registry",
+    "  build-image <target> --tag <tag>     build the docker image for a target shape (Section 32)",
+    "       [--platform <p>] [--push]",
+    "  cloud deploy --provider <p>          deploy a managed CrewHaus cluster (Section 32)",
+    "       --region <r> [--tier <t>] [--image-tag <tag>]",
+    "  cloud teardown --provider <p>        tear down a managed cluster",
+    "       --region <r>",
+    "  federation discover <deployment>     resolve a federated peer's endpoint + cert fingerprint (Section 34)",
+    "       [--srv-domain <d>] [--format json|yaml]",
+    "  sandbox doctor [--probe]             list registered sandbox images + healthcheck status (Section 36)",
+    "       [--format json|table]",
+    "  compliance evidence                  collect SOC 2 / ISO 27001 / HIPAA evidence (Section 39)",
+    "       --framework <id> [--control <id>] --period <p> [--audit-dir <d>]",
+    "       [--out-dir <d>] [--signing-key-env <ENV>]",
+    "  version                              print the CLI version (also: --version, -v)",
+    "",
+  ].join("\n");
+}
+
+/** No subcommand given (or a parse error) — usage to stderr, exit 1. */
 function usage(): never {
-  process.stderr.write(
-    [
-      "usage: crewhaus <subcommand> [args]",
-      "",
-      "subcommands:",
-      "  compile <spec.yaml> -o <out-dir>     compile a spec to a runnable bundle",
-      "                                       (fails if an outward tool is left non-external — FR-002)",
-      "                  [--allow-unmarked-sinks]  opt out of the external-sink scope gate",
-      "  compile <spec.yaml> --emit-ir        print the lowered IR as JSON (debug)",
-      "  run <spec.yaml> [--model <model>]    compile in-memory and execute the agent",
-      "                  [--resume <id>]      resume a specific session (cli targets only)",
-      "                  [--continue]         resume the most-recent session (cli targets only)",
-      "                  [--prompt <text>]    initial user prompt (browser targets; defaults to stdin)",
-      "                  [--justification-judge rule-based|claude]  Pillar 3 intent-gate judge (FR-004)",
-      "                  [--egress-matcher substring|semantic]  Pillar 3 sink-side matcher (FR-006)",
-      "                  [--egress-embedder <model>]  embedder for --egress-matcher semantic",
-      "  eval <spec.yaml> --dataset <data>    run the agent against a dataset and grade",
-      "       --graders <graders.yaml>       (deterministic graders + LLM-as-judge)",
-      "       [--judge-model <model>] [--concurrency N] [--seed N] -o <out-dir>",
-      "  eval-report diff <prev> <new>        compare two eval runs and emit a diff report",
-      "       [-o <out-dir>]",
-      "  optimize <spec.yaml> --dataset <data> --graders <graders.yaml>",
-      "       [--mutator rule-based|claude] [--iterations N] [--seed N]",
-      "       [--budget-usd N]                     stop a model-driven run before it exceeds $N (FR-003)",
-      "       [--write-back] [-o <out-dir>]        active eval-driven optimization (Pillar 2)",
-      "  init [name]                          scaffold a new crewhaus.yaml",
-      "  doctor                               check environment health",
-      "  context --bundle [-o <file>]         emit a single-markdown orientation manifest",
-      "       [--factory-root <p>] [--docs-root <p>] [--demos-root <p>]",
-      "  cost-summary --session <id>          summarize cost_accrual events for a session",
-      "  secrets doctor                       list known secrets via the configured backend",
-      "  secrets rotate <name> [--value V]    rotate a named secret (file or vault backend)",
-      "  spec put|list|get|pin|alias ...      versioned spec storage (Section 28 spec-registry)",
-      "  deploy promote|rollback ...          re-pin a spec for an environment (Section 28)",
-      "  migrate-all --from N --to N          batch-migrate every spec in the registry",
-      "  build-image <target> --tag <tag>     build the docker image for a target shape (Section 32)",
-      "       [--platform <p>] [--push]",
-      "  cloud deploy --provider <p>          deploy a managed CrewHaus cluster (Section 32)",
-      "       --region <r> [--tier <t>] [--image-tag <tag>]",
-      "  cloud teardown --provider <p>        tear down a managed cluster",
-      "       --region <r>",
-      "  federation discover <deployment>     resolve a federated peer's endpoint + cert fingerprint (Section 34)",
-      "       [--srv-domain <d>] [--format json|yaml]",
-      "  sandbox doctor [--probe]             list registered sandbox images + healthcheck status (Section 36)",
-      "       [--format json|table]",
-      "  compliance evidence                  collect SOC 2 / ISO 27001 / HIPAA evidence (Section 39)",
-      "       --framework <id> [--control <id>] --period <p> [--audit-dir <d>]",
-      "       [--out-dir <d>] [--signing-key-env <ENV>]",
-      "  version                              print the CLI version (also: --version, -v)",
-      "",
-    ].join("\n"),
-  );
+  process.stderr.write(usageText());
   process.exit(1);
 }
 
+/**
+ * Explicit `-h`/`--help` at the top level — usage to stdout, exit 0. Help was
+ * requested, so it is not an error; this matches every subcommand's own
+ * `--help` (stdout, exit 0) and lets `crewhaus --help` work in `set -e` health
+ * checks instead of looking like a broken CLI.
+ */
+function help(): never {
+  process.stdout.write(usageText());
+  process.exit(0);
+}
+
 function die(message: string): never {
   process.stderr.write(`crewhaus: ${message}\n`);
   process.exit(1);
@@ -464,7 +478,10 @@ async function runCompile(args: ParsedArgs): Promise<void> {
     try {
       ir = lower(parseSpec(yamlText));
     } catch (err) {
-      if (err instanceof SpecParseError) die(err.message);
+      // parseSpec throws SpecParseError; lower() can throw CompilerError (e.g. a
+      // malformed credential env-ref). Both extend CrewhausError — route the
+      // family through die() for a clean one-liner instead of a raw stack trace.
+      if (err instanceof CrewhausError) die(err.message);
       throw err;
     }
     const json = `${JSON.stringify(ir, null, 2)}\n`;
@@ -524,7 +541,10 @@ async function runStrictScopeGate(yamlText: string): Promise<void> {
   try {
     ir = lower(parseSpec(yamlText));
   } catch (err) {
-    if (err instanceof SpecParseError) die(err.message);
+    // SpecParseError (parse) and CompilerError (lower, e.g. a malformed
+    // credential env-ref) both extend CrewhausError — render as a clean die()
+    // one-liner rather than an uncaught stack trace.
+    if (err instanceof CrewhausError) die(err.message);
     throw err;
   }
   const toolNames = collectToolNames(ir);
@@ -1828,13 +1848,21 @@ async function runCostSummary(args: ParsedArgs): Promise<void> {
       "kind" in parsed &&
       (parsed as { kind?: string }).kind === "cost_accrual"
     ) {
-      const e = parsed as unknown as {
-        provider: string;
-        costUsdMicros: number;
+      // event-log writes a `{ ts, version, kind, payload }` envelope, so the
+      // cost fields live under `payload`. Fall back to top-level fields so a
+      // hand-written/flat cost_accrual line still aggregates.
+      const e = parsed as {
+        provider?: string;
+        costUsdMicros?: number;
+        payload?: { provider?: string; costUsdMicros?: number };
       };
-      totalMicros += e.costUsdMicros;
-      byProvider[e.provider] = (byProvider[e.provider] ?? 0) + e.costUsdMicros;
-      count++;
+      const provider = e.payload?.provider ?? e.provider;
+      const micros = e.payload?.costUsdMicros ?? e.costUsdMicros;
+      if (typeof provider === "string" && typeof micros === "number") {
+        totalMicros += micros;
+        byProvider[provider] = (byProvider[provider] ?? 0) + micros;
+        count++;
+      }
     }
   }
   const totalDollars = totalMicros / 1_000_000;
@@ -1855,13 +1883,13 @@ async function runCostSummary(args: ParsedArgs): Promise<void> {
 /**
  * Section 27 — `crewhaus secrets <action> <name> [opts]`. Two actions:
  *   doctor                 list configured secrets and report missing
- *   rotate <name>          rotate the named secret (file or vault backends)
+ *   rotate <name>          rotate the named secret (file backend)
  */
 async function runSecrets(args: ParsedArgs, action: string): Promise<void> {
   if (args.flags["help"]) {
     process.stdout.write(
       "usage:\n" +
-        "  crewhaus secrets doctor [--backend env-var|file|vault] [--root-dir <dir>]\n" +
+        "  crewhaus secrets doctor [--backend env-var|file] [--root-dir <dir>]\n" +
         "  crewhaus secrets rotate <name> [--value <new-value>] [--backend ...]\n",
     );
     return;
@@ -1874,7 +1902,23 @@ async function runSecrets(args: ParsedArgs, action: string): Promise<void> {
   const { createSecrets, createEnvVarBackend, createFileBackend } = await import(
     "@crewhaus/secrets-manager"
   );
-  const backend = backendId === "file" ? createFileBackend({ rootDir }) : createEnvVarBackend();
+  // The `vault` backend exists in @crewhaus/secrets-manager but is not wired
+  // into the CLI (it needs an address/auth story the CLI does not yet expose).
+  // Fail loudly rather than silently degrading a security-sensitive flag to the
+  // env-var backend — a silent fallback would, e.g., make `secrets doctor`
+  // cheerfully list process env var names as if they were Vault secrets.
+  let backend: ReturnType<typeof createFileBackend>;
+  if (backendId === "env-var") {
+    backend = createEnvVarBackend();
+  } else if (backendId === "file") {
+    backend = createFileBackend({ rootDir });
+  } else if (backendId === "vault") {
+    die(
+      "vault backend is not wired into the CLI in this build — construct it programmatically via createVaultBackend(), or use --backend env-var|file",
+    );
+  } else {
+    die(`unknown secrets backend "${backendId}" (expected: env-var | file)`);
+  }
   const secrets = createSecrets({ backend });
 
   if (action === "doctor") {
@@ -2503,9 +2547,11 @@ switch (subcommand) {
   case "--version":
     printVersion();
     break;
-  case "":
   case "-h":
   case "--help":
+    help();
+    break;
+  case "":
     usage();
     break;
   default: