@crewhaus/ir 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -69,11 +69,14 @@ export type IrToolConfigs = Readonly<Record<string, unknown>>;
  */
 export type IrCompaction = {
     readonly model?: string;
-    /** Pillar 2 — when true, target emitters wire `compaction-curator`
-     *  as a pre-pass before the autocompact threshold check. The spec
-     *  layer accepts this verbatim (validated in `packages/spec`); the
-     *  IR holds it as an opt-in flag with no default so emitters can
-     *  distinguish "user said false" from "user didn't say". */
+    /** Pillar 2 — RESERVED, not yet wired at runtime. Intended to make
+     *  target emitters wire `compaction-curator` as a pre-pass before the
+     *  autocompact threshold check, but no emitter or runtime-core path
+     *  consumes this field today — setting it is currently a no-op. The
+     *  spec layer accepts this verbatim (validated in `packages/spec`) and
+     *  it lowers here unchanged so the value round-trips once wiring lands;
+     *  the IR holds it as an opt-in flag with no default so emitters can
+     *  eventually distinguish "user said false" from "user didn't say". */
     readonly curate?: boolean;
     /** Cosine threshold for the curator's dedupe pass. Curator's own
      *  default (0.92, `DEFAULT_DEDUPE_THRESHOLD` in
@@ -83,6 +86,38 @@ export type IrCompaction = {
      *  reorder without trimming. */
     readonly relevanceTopK?: number;
 };
+/**
+ * Item 22 — per-candidate circuit-breaker tuning lowered from the spec's
+ * `agent.circuit_breaker` block. Field names mirror `CircuitBreakerOptions`
+ * in `@crewhaus/circuit-breaker` exactly; every field optional so the
+ * breaker package's own defaults apply per knob. Carried on the agent
+ * blocks of the shapes wired for the failover chain (cli, channel,
+ * managed). Absent when the spec omits the block — declaring it WITHOUT
+ * `modelFallbacks` still breaker-wraps the single primary adapter.
+ */
+export type IrCircuitBreaker = {
+    readonly failureThreshold?: number;
+    readonly windowMs?: number;
+    readonly cooldownMs?: number;
+};
+/**
+ * Item 26 — two-tier turn-difficulty router config. `fast`/`default` are full
+ * model-router grammar strings; `routing` tunes the per-turn escalation
+ * thresholds (all optional — runtime defaults apply per knob). Carried on the
+ * agent blocks of the failover-capable shapes (cli, channel, managed). Absent
+ * when the spec omits `model_tiers` — codegen gates on presence so an unset
+ * block leaves bundles byte-identical.
+ */
+export type IrModelTiers = {
+    readonly fast: string;
+    readonly default: string;
+    readonly routing?: {
+        readonly contextTokenThreshold?: number;
+        readonly toolsToDefault?: boolean;
+        readonly firstTurnToDefault?: boolean;
+        readonly priorToolDensityThreshold?: number;
+    };
+};
 /**
  * Section 55 (Track A) — named failure taxonomy. Cross-cutting; carried
  * through to runtime-core so `recovery-engine` can consult the user's
@@ -100,10 +135,30 @@ export type IrCompaction = {
 export type IrFailureTaxonomyEntry = {
     readonly class: string;
     readonly pattern: string;
-    readonly recovery: "retry" | "compact" | "continue" | "tombstone" | "fail";
+    /** Item 23 — `switch-model` reroutes onto the next provider failover
+     *  candidate mid-turn (see recovery-engine). */
+    readonly recovery: "retry" | "compact" | "continue" | "tombstone" | "switch-model" | "fail";
     readonly hint?: string;
 };
 export type IrFailureTaxonomy = readonly IrFailureTaxonomyEntry[];
+/**
+ * Item 27 — run-level spend cap with a degradation ladder, lowered from the
+ * spec's `budget` block. `usdMicros` is the dollar ceiling in USD-micros
+ * (1 USD = 1_000_000) — the unit the runtime meters in. `onExceed` decides
+ * the behaviour when accrued spend reaches the cap: `stop` ends the run
+ * before the next turn; `degrade` re-resolves the primary model to `model`
+ * (one cheaper rung) and continues. Carried on the interactive shapes that
+ * loop (cli, channel, managed); absent when the spec omits the block.
+ */
+export type IrBudget = {
+    readonly usdMicros: number;
+    readonly onExceed: {
+        readonly kind: "stop";
+    } | {
+        readonly kind: "degrade";
+        readonly model: string;
+    };
+};
 /**
  * Pillar 3 (FR-004) — per-target security fabric configuration the
  * compiler lowers from the spec's `security` block. Today it carries the
@@ -160,8 +215,56 @@ export type IrFeedback = {
         readonly location: string;
     };
     readonly autoDistill?: boolean;
+    /** Item 1 — gate for the CLI REPL's one-keystroke exit rating prompt.
+     *  Absent → prompt (the block's presence opts in); `false` → never. */
+    readonly exitPrompt?: boolean;
     readonly channelReactions?: boolean;
 };
+/**
+ * Feature #53 — cross-session memory config, lowered from `spec.memory`.
+ * Presence of the block wires Remember/Recall into the target; the auto-*
+ * switches gate auto-capture (summarize durable outcomes at teardown) and
+ * auto-recall (inject top-K memories into the system prompt at session start).
+ * Carried on the interactive shapes that run a chat loop (IrV0/cli,
+ * IrChannelV0, IrManagedV0, IrResearchV0). Absent when the spec omits `memory`.
+ */
+export type IrMemory = {
+    readonly enabled?: boolean;
+    readonly autoCapture?: boolean;
+    readonly autoCaptureThreshold?: number;
+    readonly autoRecall?: boolean;
+    readonly recallK?: number;
+};
+/** Ops item 37 — a mitigation-ladder rung the runtime SLO monitor walks on a
+ *  sustained breach, in declared order. See {@link IrSlo}. */
+export type IrSloMitigation = "alert" | "pause-intake" | "rollback";
+/**
+ * Ops item 37 — production SLO targets + the mitigation ladder, lowered from
+ * `spec.observability.slo`. Every target is optional (declare only the ones you
+ * care about); an omitted target is never evaluated by the monitor. `windowMs`
+ * is the rolling window a breach must persist before the ladder fires (spec's
+ * `window_seconds` × 1000; the monitor defaults it when absent). `mitigation`
+ * defaults to `["alert"]` at lower time so an observe-only spec still warns.
+ * Absent from the IR when the spec omits the block.
+ */
+export type IrSlo = {
+    readonly errorRate?: number;
+    readonly p95LatencyMs?: number;
+    readonly ttftMs?: number;
+    readonly costPerHourUsd?: number;
+    readonly egressBlockRate?: number;
+    readonly windowMs?: number;
+    readonly mitigation: ReadonlyArray<IrSloMitigation>;
+};
+/**
+ * Ops item 37 — cross-cutting observability config, lowered from
+ * `spec.observability`. Today it carries one sub-block, `slo`. Carried on the
+ * interactive/daemon shapes that run a chat loop (IrV0/cli, IrChannelV0,
+ * IrManagedV0). Absent when the spec omits the `observability` block.
+ */
+export type IrObservability = {
+    readonly slo?: IrSlo;
+};
 /**
  * Track F (Section 57) — typed message schemas (Σ) for multi-agent
  * communication. Source: AgentFlow (arxiv 2604.20801). A typed graph
@@ -216,6 +319,14 @@ export type IrV0 = {
         /** Model max OUTPUT tokens for one turn (spec `agent.max_tokens`).
          *  Optional; when absent the runtime default applies. */
         readonly maxTokens?: number;
+        /** Item 22 — ordered failover models (spec `agent.model_fallbacks`).
+         *  Absent when the spec omits the block; the runtime then keeps its
+         *  single-adapter path. */
+        readonly modelFallbacks?: readonly string[];
+        /** Item 22 — breaker tuning (spec `agent.circuit_breaker`). */
+        readonly circuitBreaker?: IrCircuitBreaker;
+        /** Item 26 — two-tier turn-difficulty router. Absent → single-model. */
+        readonly modelTiers?: IrModelTiers;
     };
     readonly tools: readonly string[];
     readonly toolConfigs: IrToolConfigs;
@@ -226,12 +337,19 @@ export type IrV0 = {
     readonly cli?: IrCliOptions;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** Item 27 — run-level spend cap + degradation ladder. Optional. */
+    readonly budget?: IrBudget;
     /** Pillar 3 (FR-004) — security fabric config (intent-gate judge
      *  selection). Optional; absent when the spec omits the `security`
      *  block. */
     readonly security?: IrSecurity;
     /** Response-feedback config. Optional; absent when the spec omits `feedback`. */
     readonly feedback?: IrFeedback;
+    /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
+    readonly memory?: IrMemory;
+    /** Ops item 37 — SLO targets + mitigation ladder. Optional; absent when the
+     *  spec omits the `observability` block. */
+    readonly observability?: IrObservability;
     /** §47 cross-cutting blockchain subsystem (slice 0). All optional. */
     readonly chains?: readonly IrChainBinding[];
     readonly wallets?: readonly IrWalletBinding[];
@@ -463,6 +581,12 @@ export type IrChannelV0 = {
     readonly agent: {
         readonly model: string;
         readonly instructions: string;
+        /** Item 22 — ordered failover models (spec `agent.model_fallbacks`). */
+        readonly modelFallbacks?: readonly string[];
+        /** Item 22 — breaker tuning (spec `agent.circuit_breaker`). */
+        readonly circuitBreaker?: IrCircuitBreaker;
+        /** Item 26 — two-tier turn-difficulty router. Absent → single-model. */
+        readonly modelTiers?: IrModelTiers;
     };
     readonly tools: readonly string[];
     readonly toolConfigs: IrToolConfigs;
@@ -476,9 +600,16 @@ export type IrChannelV0 = {
     readonly gateway?: IrChannelGateway;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** Item 27 — run-level spend cap + degradation ladder. Optional. */
+    readonly budget?: IrBudget;
     /** Response-feedback config. `feedback.channelReactions` gates Slack 👍/👎
      *  → user_feedback codegen in this target. Absent when spec omits it. */
     readonly feedback?: IrFeedback;
+    /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
+    readonly memory?: IrMemory;
+    /** Ops item 37 — SLO targets + mitigation ladder. Optional; absent when the
+     *  spec omits the `observability` block. */
+    readonly observability?: IrObservability;
     /** §47 cross-cutting blockchain subsystem (slice 0). All optional. */
     readonly chains?: readonly IrChainBinding[];
     readonly wallets?: readonly IrWalletBinding[];
@@ -505,12 +636,26 @@ export type IrManagedV0 = {
     readonly agent: {
         readonly model: string;
         readonly instructions: string;
+        /** Item 22 — ordered failover models (spec `agent.model_fallbacks`). */
+        readonly modelFallbacks?: readonly string[];
+        /** Item 22 — breaker tuning (spec `agent.circuit_breaker`). */
+        readonly circuitBreaker?: IrCircuitBreaker;
+        /** Item 26 — two-tier turn-difficulty router. Absent → single-model. */
+        readonly modelTiers?: IrModelTiers;
     };
     readonly tenants: readonly IrManagedTenant[];
     readonly permissions: IrPermissions;
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** Item 27 — run-level spend cap + degradation ladder. Optional. */
+    readonly budget?: IrBudget;
+    /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
+    readonly memory?: IrMemory;
+    /** Ops item 37 — SLO targets + mitigation ladder. Optional; absent when the
+     *  spec omits the `observability` block. The managed daemon's `pause-intake`
+     *  rung reuses its `budget_exceeded` 429 path. */
+    readonly observability?: IrObservability;
 };
 /**
  * Section 19 — Graph IR. A `target: "graph"` spec lowers into a fixed
@@ -700,6 +845,8 @@ export type IrResearchV0 = {
     readonly compaction: IrCompaction;
     /** Section 55 (Track A) — named failure taxonomy. Optional. */
     readonly failureTaxonomy?: IrFailureTaxonomy;
+    /** #53 cross-session memory config. Optional; absent when the spec omits `memory`. */
+    readonly memory?: IrMemory;
     /** §47 cross-cutting blockchain subsystem (slice 0). All optional. */
     readonly chains?: readonly IrChainBinding[];
     readonly wallets?: readonly IrWalletBinding[];
@@ -969,3 +1116,4 @@ export type Bundle = {
         readonly content: string;
     }>;
 };
+export { type BundleReadmeOptions, type BundleReadmeSection, type CollectedSecretRefs, type EmitReadmeOptions, GENERATED_README_MARKER, collectSecretRefs, renderBundleReadme, } from "./readme";

package/dist/index.js

@@ -1 +1,3 @@
-export {};
+// Generated-bundle README renderer (item 42) — pure functions over the IR,
+// shared by every target emitter. See ./readme.ts for the module docs.
+export { GENERATED_README_MARKER, collectSecretRefs, renderBundleReadme, } from "./readme";

package/dist/readme.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Generated-bundle README renderer (AUTOMATION-OPPORTUNITIES.md item 42).
+ *
+ * Every target emitter drops a `README.md` into its compiled bundle so a
+ * user who cd's into an out-dir can see — without reading generated code —
+ * what the harness is, which tools/MCP servers it wires, WHICH ENV VARS it
+ * needs, and how to launch it. The renderer lives here in `@crewhaus/ir`
+ * because it is a pure function over the lowered IR and this is the one
+ * package every `target-*` emitter already depends on (adding it here
+ * creates zero new dependency edges; `packages/compiler` sits *downstream*
+ * of the emitters, so it cannot be the seam).
+ *
+ * Security invariant: secret refs lowered to `{ kind: "literal" }` are
+ * NEVER printed — the README only names `{ kind: "env" }` variables. A
+ * literal credential is already a spec smell (see `lowerCredential` in
+ * `packages/compiler`), and the README must not widen the blast radius by
+ * copying the value into a second, more-readable artifact.
+ */
+import type { IrNode } from "./index";
+/**
+ * Common emitter option controlling README.md emission. Default ON;
+ * `crewhaus compile --no-readme` threads `readme: false` through
+ * `CompileOptions` to every target emitter.
+ */
+export type EmitReadmeOptions = {
+    readonly readme?: boolean;
+};
+/**
+ * Machine-checkable marker embedded in every generated README. The CLI's
+ * `compile` write path uses it to distinguish a previously-generated
+ * README (safe to overwrite on recompile) from a user-authored one
+ * (kept, with a notice).
+ */
+export declare const GENERATED_README_MARKER = "<!-- crewhaus:generated-readme -->";
+/** A README section: markdown heading text + markdown body. */
+export type BundleReadmeSection = {
+    readonly heading: string;
+    readonly body: string;
+};
+export type BundleReadmeOptions = {
+    /** One-line description under the title. Defaults to a generated line. */
+    readonly description?: string;
+    /**
+     * Replace the default per-target Run section (e.g. the cf-worker
+     * emitters substitute a `wrangler deploy` flow, the claude-plugin
+     * emitter an Install note).
+     */
+    readonly usage?: BundleReadmeSection;
+    /** Include the `.crewhaus/` runtime-data note. Default true. */
+    readonly includeWorkspaceNote?: boolean;
+    /** Extra sections appended at the end (e.g. claude-plugin's Origin). */
+    readonly extraSections?: readonly BundleReadmeSection[];
+};
+/**
+ * Every env var / redacted-literal count referenced by a lowered IR's
+ * secret-shaped fields (`IrSecretRef`), gathered via a recursive walk so
+ * variant-specific nesting (channel credentials, chain `rpcUrls`, wallet
+ * `keyRef`, pipeline `retrieve.apiKey`, …) is covered without coupling to
+ * each variant's shape — the same discipline as `collectToolNames` in
+ * `packages/compiler`.
+ */
+export type CollectedSecretRefs = {
+    /** Deduped, sorted `{ kind: "env" }` variable names. */
+    readonly envNames: readonly string[];
+    /** How many `{ kind: "literal" }` refs were found. Values are REDACTED. */
+    readonly literalCount: number;
+};
+export declare function collectSecretRefs(ir: unknown): CollectedSecretRefs;
+/**
+ * Render the generated bundle README from a lowered IR. Pure; no I/O.
+ * Deterministic for a given IR (tables and env lists are sorted) so
+ * recompiles diff cleanly.
+ */
+export declare function renderBundleReadme(ir: IrNode, opts?: BundleReadmeOptions): string;

package/dist/readme.js

@@ -0,0 +1,381 @@
+import { OPAQUE_TOKEN_RE, maskCredentialTokens } from "./redact";
+/**
+ * Machine-checkable marker embedded in every generated README. The CLI's
+ * `compile` write path uses it to distinguish a previously-generated
+ * README (safe to overwrite on recompile) from a user-authored one
+ * (kept, with a notice).
+ */
+export const GENERATED_README_MARKER = "<!-- crewhaus:generated-readme -->";
+export function collectSecretRefs(ir) {
+    const envNames = new Set();
+    let literalCount = 0;
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        const record = node;
+        // Match the IrSecretRef discriminants exactly. Other IR unions also
+        // carry a `kind` key (`IrChainFinality`, `IrSchemaRef`, triggers) but
+        // none uses the values "env"/"literal", so this cannot misfire.
+        if (record["kind"] === "env" && typeof record["name"] === "string") {
+            envNames.add(record["name"]);
+        }
+        else if (record["kind"] === "literal" && typeof record["value"] === "string") {
+            literalCount += 1;
+        }
+        for (const value of Object.values(record))
+            visit(value);
+    };
+    visit(ir);
+    return { envNames: [...envNames].sort(), literalCount };
+}
+/**
+ * Per-shape launch one-liner, derived from each emitter's output layout:
+ * shapes that emit a `daemon.ts` entrypoint (channel / managed / crew /
+ * voice) launch that; every other shape's entrypoint is `agent.ts`.
+ */
+const RUN_COMMANDS = {
+    cli: "bun agent.ts",
+    workflow: "bun agent.ts",
+    channel: "bun daemon.ts",
+    graph: "bun agent.ts",
+    managed: "bun daemon.ts",
+    pipeline: "bun agent.ts",
+    crew: "bun daemon.ts",
+    research: "bun agent.ts",
+    batch: "bun agent.ts",
+    voice: "bun daemon.ts",
+    browser: "bun agent.ts",
+    eval: "bun agent.ts",
+    onchain: "bun agent.ts",
+    "onchain-game": "bun agent.ts",
+};
+/**
+ * Definitionally outward-reaching tool names, in both the spec-key
+ * (camelCase) and registered (PascalCase) forms the IR can carry. Mirrors
+ * `OUTWARD_TOOL_NAMES` in `@crewhaus/tool-builder` — the canonical rule —
+ * but kept inline (exactly as `IrVectorBackend` mirrors `vector-store`)
+ * so the runtime-agnostic IR keeps its zero package dependencies. Keep in
+ * sync when a name is added or removed.
+ */
+const OUTWARD_TOOL_NAMES = new Set([
+    "fetch",
+    "Fetch",
+    "webFetch",
+    "WebFetch",
+    "webSearch",
+    "WebSearch",
+    "sendMessage",
+    "SendMessage",
+    "evmSendTransaction",
+    "EvmSendTransaction",
+    "imageGenerate",
+    "ImageGenerate",
+]);
+/** Tools executed inside the §18 sandbox (see `target-cli`'s sandbox gate). */
+const SANDBOXED_TOOL_NAMES = new Set(["python", "javascript", "shell"]);
+/**
+ * Tools that `requireJustification: true` by default (the Pillar 3 intent
+ * gate — see AGENTS.md). Both name forms, same mirroring caveat as above.
+ */
+const JUSTIFICATION_GATED_TOOL_NAMES = new Set([
+    "sendMessage",
+    "SendMessage",
+    "evmSendTransaction",
+    "EvmSendTransaction",
+    "imageGenerate",
+    "ImageGenerate",
+]);
+/** Keys whose array items scope the `tools` lists nested beneath them. */
+const NESTED_TOOL_CONTEXTS = {
+    steps: "step",
+    nodes: "node",
+    roles: "role",
+    subAgents: "sub-agent",
+};
+/**
+ * Recursive walk gathering every string under a `tools` key together with
+ * the context that declares it ("agent" at the top level; `step \`x\`` /
+ * `node \`x\`` / `role \`x\`` / `sub-agent \`x\`` when nested). Mirrors
+ * `collectToolNames` in `packages/compiler`, with context tracking added.
+ */
+function collectToolUsage(ir) {
+    const usage = new Map();
+    const add = (tool, context) => {
+        const contexts = usage.get(tool) ?? new Set();
+        contexts.add(context);
+        usage.set(tool, contexts);
+    };
+    const visit = (node, context) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item, context);
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "tools" && Array.isArray(value)) {
+                for (const v of value)
+                    if (typeof v === "string")
+                        add(v, context);
+                continue;
+            }
+            const label = NESTED_TOOL_CONTEXTS[key];
+            if (label !== undefined && Array.isArray(value)) {
+                for (const item of value) {
+                    const name = item?.name;
+                    // The context label lands in a table cell verbatim — escape the
+                    // interpolated name (F5) but not the intentional backticks here.
+                    visit(item, typeof name === "string" ? `${label} \`${escapeCell(name)}\`` : label);
+                }
+                continue;
+            }
+            visit(value, context);
+        }
+    };
+    visit(ir, "agent");
+    return usage;
+}
+/** Every tool name carrying a `tool_config` blob, across nested variants. */
+function collectConfiguredToolNames(ir) {
+    const configured = new Set();
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "toolConfigs" && value !== null && typeof value === "object") {
+                for (const name of Object.keys(value))
+                    configured.add(name);
+                continue;
+            }
+            visit(value);
+        }
+    };
+    visit(ir);
+    return configured;
+}
+/** Deduped models across variant shapes (agent / steps / nodes / roles). */
+function collectModels(ir) {
+    switch (ir.target) {
+        case "workflow":
+            return [...new Set(ir.steps.map((s) => s.model))];
+        case "graph":
+            return [...new Set(ir.nodes.map((n) => n.model))];
+        case "crew":
+            return [...new Set(ir.roles.map((r) => r.model))];
+        default:
+            return [ir.agent.model];
+    }
+}
+/**
+ * Adversarial-review F5 — escape an interpolated value for a GFM table
+ * cell: `|` would split the cell, a raw newline would end the row, and a
+ * stray backtick would terminate the code-span the tables wrap values in.
+ */
+function escapeCell(value) {
+    return value.replace(/\|/g, "\\|").replace(/`/g, "\\`").replace(/\r?\n/g, " ");
+}
+/**
+ * Adversarial-review F2 — words in a CLI flag name that mark its VALUE as a
+ * credential (`--token=…`, `--api-key …`). Matched per dash-separated word
+ * so `--keyboard-layout` stays visible while `--api-key` masks.
+ */
+const CREDENTIAL_FLAG_WORDS = new Set([
+    "key",
+    "apikey",
+    "token",
+    "secret",
+    "password",
+    "pass",
+    "passwd",
+    "pwd",
+    "auth",
+    "authorization",
+    "credential",
+    "credentials",
+    "bearer",
+]);
+function isCredentialFlag(arg) {
+    const m = arg.match(/^--?([A-Za-z][A-Za-z0-9-]*)$/);
+    if (m?.[1] === undefined)
+        return false;
+    return m[1]
+        .toLowerCase()
+        .split("-")
+        .some((word) => CREDENTIAL_FLAG_WORDS.has(word));
+}
+/** Render a stdio server's launch line with credential-valued flags masked
+ *  (`--token=v` and `--token v` forms) and known token shapes (`sk-…`,
+ *  `ghp_…`, …) masked out of every other arg. */
+function maskStdioCommand(command, args) {
+    const masked = [];
+    let maskNext = false;
+    for (const arg of args) {
+        if (maskNext) {
+            masked.push("***");
+            maskNext = false;
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        if (arg.startsWith("-") && eq > 0 && isCredentialFlag(arg.slice(0, eq))) {
+            masked.push(`${arg.slice(0, eq)}=***`);
+            continue;
+        }
+        if (isCredentialFlag(arg)) {
+            masked.push(arg);
+            maskNext = true;
+            continue;
+        }
+        masked.push(maskCredentialTokens(arg));
+    }
+    return [command, ...masked].join(" ");
+}
+/**
+ * Mask the credential-bearing parts of an sse URL: userinfo passwords
+ * (`https://user:***@`), ALL query-parameter values (`?apikey=***` — key
+ * names stay, values never render), and path segments shaped like opaque
+ * credentials (Alchemy/Infura-style `/v2/<key>` → `/v2/***`). Regex-based
+ * so a not-quite-parseable URL still gets masked rather than printed raw.
+ */
+function maskUrlCredentials(url) {
+    // Userinfo: keep the user, mask the password.
+    const out = url.replace(/^([a-z][a-z0-9+.-]*:\/\/[^/@:]+):([^/@]+)@/i, "$1:***@");
+    const q = out.indexOf("?");
+    const query = q === -1 ? "" : out.slice(q).replace(/([?&;][^=&;#]*)=([^&;#]*)/g, "$1=***");
+    let base = q === -1 ? out : out.slice(0, q);
+    const prefix = base.match(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i)?.[0] ?? "";
+    const path = base
+        .slice(prefix.length)
+        .split("/")
+        .map((seg) => (OPAQUE_TOKEN_RE.test(seg) ? "***" : maskCredentialTokens(seg)))
+        .join("/");
+    base = `${prefix}${path}`;
+    return `${base}${query}`;
+}
+function toolScopeHint(name) {
+    if (name.startsWith("mcp__"))
+        return "external (MCP)";
+    if (OUTWARD_TOOL_NAMES.has(name))
+        return "external";
+    return "built-in";
+}
+function toolNotes(name, configured) {
+    const notes = [];
+    if (SANDBOXED_TOOL_NAMES.has(name))
+        notes.push("sandboxed");
+    if (JUSTIFICATION_GATED_TOOL_NAMES.has(name))
+        notes.push("justification-gated by default");
+    if (configured.has(name))
+        notes.push("configured via `tool_config`");
+    return notes.length > 0 ? notes.join("; ") : "—";
+}
+function renderToolsSection(ir) {
+    const usage = collectToolUsage(ir);
+    if (usage.size === 0)
+        return undefined;
+    const configured = collectConfiguredToolNames(ir);
+    const rows = [...usage.keys()].sort().map((name) => {
+        const contexts = [...(usage.get(name) ?? new Set())].sort().join(", ");
+        return `| \`${escapeCell(name)}\` | ${contexts} | ${toolScopeHint(name)} | ${toolNotes(name, configured)} |`;
+    });
+    return ["| Tool | Used by | Scope | Notes |", "| --- | --- | --- | --- |", ...rows].join("\n");
+}
+function renderMcpSection(ir) {
+    const servers = ir.mcp_servers;
+    if (servers === undefined)
+        return undefined;
+    const entries = Object.entries(servers);
+    if (entries.length === 0)
+        return undefined;
+    // Endpoint column: command for stdio, URL for sse. Env values and sse
+    // headers are intentionally NOT rendered — they can carry credentials —
+    // and the command/URL themselves are masked (adversarial-review F2):
+    // credential-valued flags, known token shapes in args, URL userinfo
+    // passwords, ALL query-parameter values, and opaque path segments.
+    const rows = entries.map(([name, cfg]) => cfg.transport === "stdio"
+        ? `| \`${escapeCell(name)}\` | stdio | \`${escapeCell(maskStdioCommand(cfg.command, cfg.args))}\` |`
+        : `| \`${escapeCell(name)}\` | sse | \`${escapeCell(maskUrlCredentials(cfg.url))}\` |`);
+    return ["| Server | Transport | Endpoint |", "| --- | --- | --- |", ...rows].join("\n");
+}
+function renderEnvSection(ir) {
+    const { envNames, literalCount } = collectSecretRefs(ir);
+    const models = collectModels(ir);
+    const lines = [];
+    if (envNames.length > 0) {
+        lines.push("Set these before launching — the bundle reads them from `process.env` at runtime:", "", ...envNames.map((name) => `- \`${name}\``));
+    }
+    else {
+        lines.push("No spec-declared environment variables.");
+    }
+    if (literalCount > 0) {
+        lines.push("", `> ${literalCount} secret-shaped value(s) were supplied as literals in the spec and are compiled into the bundle — they are not shown here. Prefer \`$UPPER_SNAKE_CASE\` env references so credentials stay out of compiled artifacts.`);
+    }
+    lines.push("", `The model provider's API key must also be present (e.g. \`ANTHROPIC_API_KEY\` for Anthropic \`claude-*\` models; model(s) in use: ${models
+        .map((m) => `\`${m}\``)
+        .join(", ")}).`);
+    return lines.join("\n");
+}
+function defaultUsageSection(ir) {
+    return {
+        heading: "Run",
+        body: ["```sh", RUN_COMMANDS[ir.target], "```"].join("\n"),
+    };
+}
+const WORKSPACE_NOTE = [
+    "Launch the bundle from inside this directory — it reads and writes workspace state under `.crewhaus/` relative to the working directory:",
+    "",
+    "- `.crewhaus/sessions/` — session transcripts (one file per session)",
+    "- `.crewhaus/feedback/` — response ratings collected by the feedback tooling",
+].join("\n");
+/**
+ * Render the generated bundle README from a lowered IR. Pure; no I/O.
+ * Deterministic for a given IR (tables and env lists are sorted) so
+ * recompiles diff cleanly.
+ */
+export function renderBundleReadme(ir, opts = {}) {
+    const description = opts.description ?? `Compiled CrewHaus bundle for the \`${ir.target}\` target shape.`;
+    const models = collectModels(ir);
+    const harnessRows = [
+        "| | |",
+        "| --- | --- |",
+        `| Name | \`${escapeCell(ir.name)}\` |`,
+        `| Target | \`${ir.target}\` |`,
+        `| ${models.length > 1 ? "Models" : "Model"} | ${models
+            .map((m) => `\`${escapeCell(m)}\``)
+            .join(", ")} |`,
+    ].join("\n");
+    const sections = [{ heading: "Harness", body: harnessRows }];
+    const tools = renderToolsSection(ir);
+    if (tools !== undefined)
+        sections.push({ heading: "Tools", body: tools });
+    const mcp = renderMcpSection(ir);
+    if (mcp !== undefined)
+        sections.push({ heading: "MCP servers", body: mcp });
+    sections.push({ heading: "Environment variables", body: renderEnvSection(ir) });
+    sections.push(opts.usage ?? defaultUsageSection(ir));
+    if (opts.includeWorkspaceNote !== false) {
+        sections.push({ heading: "Runtime data", body: WORKSPACE_NOTE });
+    }
+    sections.push(...(opts.extraSections ?? []));
+    return [
+        GENERATED_README_MARKER,
+        "",
+        `# ${ir.name}`,
+        "",
+        description,
+        "",
+        "Generated by CrewHaus — do not edit by hand; recompile from the spec instead.",
+        "",
+        ...sections.flatMap((s) => [`## ${s.heading}`, "", s.body, ""]),
+    ].join("\n");
+}

package/dist/redact.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Credential redaction for HUMAN-READABLE renderings of spec/IR content —
+ * changelog diff lines (`spec-patch`) and generated bundle READMEs (`ir`).
+ * Two layers:
+ *
+ *   1. `isCredentialKey` — key-based: a value stored under a key that NAMES
+ *      a credential (`api_key`, `botToken`, `headers`, `env`, …) is redacted
+ *      wholesale, whatever the value looks like.
+ *   2. `maskCredentialTokens` — value-based: strings that are NOT under a
+ *      credential key (instructions prose, command args, URLs) are scanned
+ *      for well-known credential token shapes (`sk-…`, `ghp_…`, `xoxb-…`,
+ *      `AKIA…`, `Bearer <token>`) plus high-length opaque tokens preceded by
+ *      key-ish context words. Deliberately conservative: a bare 32-char
+ *      identifier with no "key/token/secret/password" context is left alone
+ *      so normal prose never gets chewed up.
+ *
+ * KEEP IN SYNC: this module is intentionally duplicated as
+ * `packages/ir/src/redact.ts` and `packages/spec-patch/src/redact.ts`.
+ * `@crewhaus/ir` keeps ZERO package dependencies (its `readme.ts` already
+ * mirrors `OUTWARD_TOOL_NAMES` from tool-builder for the same reason) and
+ * `spec-patch` is spec-layer infrastructure that must not grow an edge onto
+ * the IR layer — so neither package can host the single copy without a new
+ * dependency edge. Change one file, change both.
+ */
+/** Placeholder rendered in place of a value under a credential-carrying key. */
+export declare const REDACTED_VALUE = "[redacted]";
+/** Placeholder substituted for a credential-shaped token inside a string. */
+export declare const MASKED_TOKEN = "***";
+/**
+ * Whether a property key names a credential. Suffix matches require a word
+ * boundary (snake/kebab/camel) so `api_key` / `botToken` / `GITHUB_TOKEN` /
+ * `signingSecret` redact while `monkey` / `max_tokens` don't.
+ */
+export declare function isCredentialKey(key: string): boolean;
+/** A path segment / standalone word shaped like an opaque credential
+ *  (Alchemy/Infura-style `/v2/<key>`): 32+ chars of token alphabet. */
+export declare const OPAQUE_TOKEN_RE: RegExp;
+/**
+ * Mask credential-shaped tokens inside a string. Non-credential text is
+ * returned unchanged (hit/no-hit cases are unit-tested in both packages).
+ */
+export declare function maskCredentialTokens(text: string): string;

package/dist/redact.js

@@ -0,0 +1,102 @@
+/**
+ * Credential redaction for HUMAN-READABLE renderings of spec/IR content —
+ * changelog diff lines (`spec-patch`) and generated bundle READMEs (`ir`).
+ * Two layers:
+ *
+ *   1. `isCredentialKey` — key-based: a value stored under a key that NAMES
+ *      a credential (`api_key`, `botToken`, `headers`, `env`, …) is redacted
+ *      wholesale, whatever the value looks like.
+ *   2. `maskCredentialTokens` — value-based: strings that are NOT under a
+ *      credential key (instructions prose, command args, URLs) are scanned
+ *      for well-known credential token shapes (`sk-…`, `ghp_…`, `xoxb-…`,
+ *      `AKIA…`, `Bearer <token>`) plus high-length opaque tokens preceded by
+ *      key-ish context words. Deliberately conservative: a bare 32-char
+ *      identifier with no "key/token/secret/password" context is left alone
+ *      so normal prose never gets chewed up.
+ *
+ * KEEP IN SYNC: this module is intentionally duplicated as
+ * `packages/ir/src/redact.ts` and `packages/spec-patch/src/redact.ts`.
+ * `@crewhaus/ir` keeps ZERO package dependencies (its `readme.ts` already
+ * mirrors `OUTWARD_TOOL_NAMES` from tool-builder for the same reason) and
+ * `spec-patch` is spec-layer infrastructure that must not grow an edge onto
+ * the IR layer — so neither package can host the single copy without a new
+ * dependency edge. Change one file, change both.
+ */
+/** Placeholder rendered in place of a value under a credential-carrying key. */
+export const REDACTED_VALUE = "[redacted]";
+/** Placeholder substituted for a credential-shaped token inside a string. */
+export const MASKED_TOKEN = "***";
+/**
+ * Keys that carry credentials, matched case-insensitively after lowercasing.
+ * Aligned with the spec schema's credential carriers (`botToken`,
+ * `signingSecret`, `appToken`, `secretToken`, `accessToken`, `appSecret`,
+ * `retrieve.apiKey`, wallet `keyRef`) and the compiler's `lowerCredential` /
+ * `lowerWalletKeyRef` call sites — see `packages/compiler/src/index.ts` §12.
+ * `headers` and `env` are container keys: everything under them redacts.
+ */
+const CREDENTIAL_KEY_EXACT = new Set([
+    "key",
+    "apikey",
+    "api_key",
+    "api-key",
+    "token",
+    "secret",
+    "password",
+    "passwd",
+    "pwd",
+    "authorization",
+    "auth",
+    "credential",
+    "credentials",
+    "headers",
+    "env",
+    "keyref",
+    "key_ref",
+    "key-ref",
+    "privatekey",
+    "private_key",
+    "private-key",
+]);
+/**
+ * Whether a property key names a credential. Suffix matches require a word
+ * boundary (snake/kebab/camel) so `api_key` / `botToken` / `GITHUB_TOKEN` /
+ * `signingSecret` redact while `monkey` / `max_tokens` don't.
+ */
+export function isCredentialKey(key) {
+    const k = key.toLowerCase();
+    if (CREDENTIAL_KEY_EXACT.has(k))
+        return true;
+    if (/[_-](?:key|token|secret|password)$/.test(k))
+        return true;
+    return /[a-z0-9](?:Key|Token|Secret|Password)$/.test(key);
+}
+/** A path segment / standalone word shaped like an opaque credential
+ *  (Alchemy/Infura-style `/v2/<key>`): 32+ chars of token alphabet. */
+export const OPAQUE_TOKEN_RE = /^[A-Za-z0-9_-]{32,}$/;
+/** Well-known credential token shapes, masked wherever they appear. */
+const TOKEN_SHAPE_RES = [
+    /\bsk-[A-Za-z0-9_-]{8,}/g, // OpenAI/Anthropic/Stripe-style secret keys
+    /\bgh[oprsu]_[A-Za-z0-9]{16,}/g, // GitHub tokens (ghp_/gho_/ghu_/ghs_/ghr_)
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, // Slack tokens
+    /\bAKIA[A-Z0-9]{12,}/g, // AWS access key ids
+];
+/** `Bearer <token>` — the scheme word is kept, the token is masked. */
+const BEARER_RE = /\b(bearer)\s+[A-Za-z0-9._~+/-]{8,}=*/gi;
+/**
+ * Generic 32+-char opaque token, masked ONLY when preceded by a key-ish
+ * context word — `key: XXXX…`, `token=XXXX…` — so hashes/ids in ordinary
+ * prose survive. Group 1 (the context) is kept; the token is masked.
+ */
+const CONTEXTUAL_OPAQUE_RE = /\b((?:api[-_ ]?)?(?:key|token|secret|password|credential)s?\b["'\s:=-]{0,5})([A-Za-z0-9+/_-]{32,})/gi;
+/**
+ * Mask credential-shaped tokens inside a string. Non-credential text is
+ * returned unchanged (hit/no-hit cases are unit-tested in both packages).
+ */
+export function maskCredentialTokens(text) {
+    let out = text;
+    for (const re of TOKEN_SHAPE_RES)
+        out = out.replace(re, MASKED_TOKEN);
+    out = out.replace(BEARER_RE, `$1 ${MASKED_TOKEN}`);
+    out = out.replace(CONTEXTUAL_OPAQUE_RE, `$1${MASKED_TOKEN}`);
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/ir",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "type": "module",
   "description": "Canonical typed intermediate representation",
   "main": "dist/index.js",