crewhaus 0.2.3 → 0.3.0

package/dist/init-interactive.js

@@ -1,22 +1,25 @@
-import { SpecParseError, parseSpec } from "@crewhaus/spec";
+import { parseSpec } from "@crewhaus/spec";
 /**
- * Item 39 — `crewhaus init --interactive`. Folds the demos harness-designer
- * pattern (an agent that interviews the user in plain English and emits a
- * validated crewhaus.yaml) into core. Two design commitments:
+ * Item 39 / v0.3.0 §2.9 — `crewhaus init --interactive`. Folds the demos
+ * harness-designer pattern (an agent that interviews the user in plain
+ * English and emits a validated crewhaus.yaml) into core. Design commitments:
  *
  *   1. NO dependency on the demos repo. The shape-decision guidance is
  *      bundled inline here ({@link SHAPE_GUIDANCE} / {@link buildInterviewSystemPrompt}),
  *      and validation is `parseSpec` called in-process — the single source of
  *      truth for what compiles.
  *   2. Every draft the model emits is validated against the LIVE Zod union via
- *      `parseSpec`, and on a structured error the error text is fed back for a
- *      retry. So `init --interactive` cannot emit a spec that won't parse.
- *
- * Everything here is side-effect-free and unit-testable: the interview loop is
- * driven by an INJECTED `proposeSpec` callback (the CLI wires the model
- * adapter behind it), and the credential-free fallback is a pure
- * {@link buildScriptedSpec} over stdin answers. The CLI wrapper in `index.ts`
- * owns all I/O.
+ *      `parseSpec`, and on a structured error the error text goes back into
+ *      the conversation as a tool error the model fixes in-context. So
+ *      `init --interactive` cannot emit a spec that won't parse.
+ *   3. The interview is a REAL conversation (v0.3.0 PR 18): a `runChatLoop`
+ *      session with `ask_user` + `emit_spec` and NO forced toolChoice —
+ *      persisted, ledger-protected, and resumable. The conversational loop
+ *      lives in `init-conversation.ts`; this module keeps the pure,
+ *      side-effect-free pieces: the shape catalog, the interviewer system
+ *      prompt, the tool contracts, and the credential-free fallback
+ *      ({@link buildScriptedSpec} over stdin answers). The CLI wrapper in
+ *      `index.ts` owns all I/O.
  */
 /** The fourteen target shapes, with the one-line "pick me when" guidance the
  *  interviewer uses. Bundled inline so core never reaches into the demos repo. */
@@ -54,17 +57,42 @@ export function isScriptedShape(s) {
     return SCRIPTED_SHAPES.includes(s);
 }
 /**
- * The interviewer's system prompt. Bundles the shape catalog + the hard rules
- * the emitted YAML must obey (single-line-safe names, the `$UPPER_SNAKE_CASE`
+ * The interviewer's system prompt — a focused variant of the `continuity`
+ * discipline (v0.3.0 §2.9) on top of the shape catalog + the hard rules the
+ * emitted YAML must obey (single-line-safe names, the `$UPPER_SNAKE_CASE`
  * secret convention, no `permissions.mode: bypass`). Kept as a builder so a
  * test can assert the guidance is present without shipping a golden file.
  */
 export function buildInterviewSystemPrompt() {
     const shapes = SHAPE_GUIDANCE.map((s) => `  - ${s.target}: ${s.when}`).join("\n");
     return [
-        "You are the CrewHaus harness designer. Interview the user in plain English to",
-        "understand what agent they want to build, then emit a single valid crewhaus.yaml",
-        "by calling the `emit_spec` tool with the full YAML as its `yaml` argument.",
+        "You are the CrewHaus harness designer, running a real multi-turn interview to",
+        "understand what agent the user wants to build and emit ONE valid crewhaus.yaml.",
+        "Two interview tools drive the conversation:",
+        "",
+        "  - `ask_user`: pose ONE focused clarifying question. After calling it, end your",
+        "    turn — the user's answer arrives as the next user message. Never bundle",
+        "    several questions into one call, and never call it twice in one turn.",
+        "  - `emit_spec`: submit the complete crewhaus.yaml as the `yaml` argument. The",
+        "    validator replies in the tool result; on an error, FIX exactly that error and",
+        "    re-emit in this same conversation — do not restart the interview.",
+        "",
+        "Requirements discipline (binding, every turn):",
+        "  - Turn 1: extract EVERY requirement from the user's opening message into",
+        "    verbatim REQ entries (REQ-001, REQ-002, …) — quote the user's exact words,",
+        "    never paraphrase — pin them with FocusWrite, and ECHO them back:",
+        '    "Got it. Requirements so far: REQ-001 …; open questions: …".',
+        '  - Each later answer: pin it, confirm the REQ ("REQ-002 confirmed"), and keep',
+        "    the echo current.",
+        "  - NEVER re-ask a requirement recorded as confirmed. Check the",
+        "    <requirements_ledger> block, <current_plan>, and FocusRead before asking",
+        "    anything — a confirmed REQ is already answered, in the user's own words.",
+        "  - Before calling emit_spec: read the ledger, verify each REQ maps to a spec",
+        "    field, and list the mapping in your reply, one line per REQ, using the →",
+        '    arrow: REQ-001 "…" → name',
+        '  - On a resumed session, your FIRST reply must start with "Resuming: N',
+        '    requirements confirmed, M open questions", computed from the ledger and',
+        "    focus — then continue where the interview stopped, without re-asking.",
         "",
         "Pick exactly ONE target shape:",
         shapes,
@@ -78,13 +106,12 @@ export function buildInterviewSystemPrompt() {
         "  - For a cli target: top-level `name`, `target: cli`, and an `agent` block with",
         "    `model` and `instructions`. Tools go in a top-level `tools:` list of names.",
         "  - Keep the spec minimal — only the blocks the user actually asked for.",
-        "",
-        "When the validator reports an error on your draft, FIX exactly that error and re-emit",
-        "— do not restart the interview.",
     ].join("\n");
 }
-/** The tool the interviewer calls to submit a candidate spec. Exported so the
- *  CLI wires the same schema into the adapter request. */
+/** The tool the interviewer calls to submit a candidate spec — the SAME
+ *  contract the pre-0.3.0 single-shot interview used (`{ yaml: string }`).
+ *  Exported so tests can pin the schema and `init-conversation.ts` builds
+ *  the RegisteredTool from it. */
 export const EMIT_SPEC_TOOL = {
     name: "emit_spec",
     description: "Submit the complete crewhaus.yaml as a single YAML string. The validator parses it " +
@@ -97,40 +124,23 @@ export const EMIT_SPEC_TOOL = {
         required: ["yaml"],
     },
 };
-export class InterviewError extends SpecParseError {
-}
-/**
- * Drive the validate-and-retry interview loop. Each attempt asks the injected
- * `proposeSpec` for a draft, runs it through `parseSpec` (the LIVE union), and
- * on a `SpecParseError` appends the error to the feedback log for the next
- * attempt. Succeeds on the first draft that validates; throws
- * {@link InterviewError} after `maxAttempts` failed drafts (or if the model
- * declines to emit). Pure given its `proposeSpec` seam — no I/O.
- */
-export async function runInterview(opts) {
-    const maxAttempts = opts.maxAttempts ?? 4;
-    const feedback = [];
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const yaml = await opts.proposeSpec(feedback);
-        if (yaml === undefined) {
-            throw new InterviewError("the interviewer did not emit a spec (no emit_spec tool call) — try a more concrete description");
-        }
-        try {
-            const spec = parseSpec(yaml);
-            return { yaml, spec, attempts: attempt };
-        }
-        catch (err) {
-            if (err instanceof SpecParseError) {
-                feedback.push(err.message);
-                continue;
-            }
-            throw err;
-        }
-    }
-    throw new InterviewError(`interviewer failed to produce a valid spec after ${maxAttempts} attempts. Last errors:\n${feedback
-        .map((f) => `  - ${f}`)
-        .join("\n")}`);
-}
+/** v0.3.0 §2.9 — the interviewer's clarifying-question tool. The loop
+ *  surfaces the question on the terminal; the user's answer arrives as the
+ *  next user message through the multi-turn REPL (nothing typed is ever
+ *  discarded — the exact failure the single-shot path had). */
+export const ASK_USER_TOOL = {
+    name: "ask_user",
+    description: "Ask the user ONE focused clarifying question. The question is shown on the terminal; " +
+        "end your turn after calling this — the user's answer arrives as the next user message. " +
+        "Check the requirements ledger first: never re-ask a confirmed requirement.",
+    input_schema: {
+        type: "object",
+        properties: {
+            question: { type: "string", description: "The single question to ask." },
+        },
+        required: ["question"],
+    },
+};
 /** YAML-quote a scalar that might contain special characters. The scripted
  *  answers are user free-text, so a name/model with a colon or `#` must be
  *  double-quoted to parse. Instructions use a block scalar (see below). */

package/dist/lint.js

@@ -67,7 +67,23 @@ export function runLint(yamlText, resolveTool, passes = DEFAULT_PIPELINE) {
             rule: "scope",
         });
     }
-    return { ok: findings.length === 0, findings, spec, ir };
+    // Stage 5 — v0.3.0 Goal 3 (design §4.1): a user-declared
+    // `mcp_servers.thredz` next to a `thredz:` block WINS over the compiler's
+    // synthesis (explicit beats implicit). That is deliberate — the vendored
+    // -server escape hatch — but worth a warning so nobody wonders why their
+    // `base_url`/`visibility` knobs stopped applying.
+    const specThredz = spec.thredz;
+    const specMcp = spec.mcp_servers;
+    if (specThredz !== undefined && specThredz !== false && specMcp?.["thredz"] !== undefined) {
+        findings.push({
+            message: "mcp_servers.thredz is user-declared, so the thredz: block does not synthesize a server — your explicit entry wins (explicit beats implicit). The thredz: knobs still drive the wiring (aliases, goal mirror), but api_key/base_url/visibility only apply through YOUR server's env; it must speak the thredz-mcp v0.2.0 tool contract.",
+            path: "mcp_servers.thredz",
+            severity: "warning",
+            rule: "thredz-override",
+        });
+    }
+    // Warnings inform; only errors gate (`ok` drives the CLI exit code).
+    return { ok: findings.every((f) => f.severity !== "error"), findings, spec, ir };
 }
 /** Re-exported for the CLI wrapper's philosophy-alignment parity note. */
 export { auditToolScopes };

package/dist/memory-cli.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 0.3.0 memory release (design §3.4) — the `crewhaus memory` verb cluster's
+ * pure/IO helpers plus the `crewhaus migrate memories` data migration. Kept
+ * thin + separately testable, mirroring `sessions-index.ts` / `lessons.ts`
+ * (the entry file runs an argv switch on import, so logic lives here).
+ *
+ * The migration rides the existing migration-engine machinery: memory
+ * entries are versioned by their `schemaVersion` field (absent = v1), the
+ * engine walks the registered 1→2 chain per entry line, and the runner-side
+ * conventions (dry-run plan first, idempotent re-runs) are preserved.
+ * `.crewhaus/meta.json` records the store-level schema version so future
+ * migrations and doctors can see at a glance what has been backfilled.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { type MemoryListItem } from "@crewhaus/memory-store";
+import { type Migration, MigrationEngine } from "@crewhaus/migration-engine";
+export declare class MemoryCliError extends CrewhausError {
+    readonly name = "MemoryCliError";
+    constructor(message: string, cause?: unknown);
+}
+/** The memories root, relative to a harness cwd. */
+export declare const MEMORIES_SUBDIR: string;
+/** Spec names that have a memory file under `memoriesDir`, sorted. */
+export declare function listMemorySpecs(memoriesDir: string): string[];
+/**
+ * Resolve which spec's store a single-target verb (`show`/`forget`) operates
+ * on: an explicit `--spec` wins; otherwise a lone memory file is unambiguous;
+ * anything else is an error naming the candidates.
+ */
+export declare function resolveMemorySpec(memoriesDir: string, specFlag?: string): string;
+/** Compact human age: "3m", "7h", "12d". Injectable clock for tests. */
+export declare function humanAge(createdAtIso: string, nowMs: number): string;
+/**
+ * Render one `memory list` row: id / age / status flag / provenance flag /
+ * tags / text preview. Deterministic given `nowMs`.
+ */
+export declare function renderMemoryListRow(item: MemoryListItem, nowMs: number): string;
+/** Render the `memory list` block for one spec's items. */
+export declare function renderMemoryList(specName: string, items: ReadonlyArray<MemoryListItem>, nowMs: number): string[];
+/** Render `memory show <id>`: the full entry plus its lifecycle status. */
+export declare function renderMemoryShow(item: MemoryListItem): string[];
+/**
+ * Backfill target for v1 auto-capture entries: they tag the sessionId today
+ * (`["auto-capture", "<sess_…>"]`), which is exactly the provenance the v2
+ * schema makes first-class.
+ */
+export declare function deriveAutoCaptureSessionId(tags: ReadonlyArray<string>): string | undefined;
+/**
+ * The memory-entry 1 → 2 step, registered on a `MigrationEngine` so the
+ * chain-walk (and any future 2 → 3 step) reuses Section-28 machinery. The
+ * `version` key is a walk-time shim the file migrator injects from
+ * `schemaVersion` (absent = 1) and strips before serialising.
+ */
+export declare const MEMORY_ENTRY_1_TO_2: Migration;
+/** An engine with the memory-entry chain registered. */
+export declare function createMemoryMigrationEngine(): MigrationEngine;
+export type MigrateMemoriesFileReport = {
+    readonly specName: string;
+    /** v1 entry lines rewritten to v2. */
+    readonly migrated: number;
+    /** Entry lines already at (or beyond) the target version. */
+    readonly skipped: number;
+    /** Non-entry lines (tombstones/unknown/malformed) preserved verbatim. */
+    readonly passthrough: number;
+};
+export type MigrateMemoriesReport = {
+    readonly files: ReadonlyArray<MigrateMemoriesFileReport>;
+    readonly migrated: number;
+    readonly skipped: number;
+    readonly dryRun: boolean;
+    /** Absolute path of the stamped meta file (absent on dry runs). */
+    readonly metaPath?: string;
+};
+/**
+ * Migrate every `.crewhaus/memories/*.jsonl` under `rootDir` to the current
+ * entry schema. Idempotent: entries already at `schemaVersion >= 2` are
+ * skipped, so a re-run migrates 0 and rewrites nothing. Non-entry lines
+ * (tombstones, future line kinds, malformed junk) pass through VERBATIM —
+ * this migration never destroys data. Writes are atomic (tmp + rename).
+ * With `dryRun` no file is touched and no meta is stamped.
+ */
+export declare function migrateMemories(rootDir: string, opts?: {
+    dryRun?: boolean;
+    now?: () => Date;
+}): MigrateMemoriesReport;
+/**
+ * Record the memories schema version in `.crewhaus/meta.json` (created when
+ * absent; other top-level keys are preserved). Returns the meta path.
+ */
+export declare function stampMemoriesMeta(rootDir: string, now?: () => Date): string;
+/** Render the `migrate memories` report, one line per file + a summary. */
+export declare function formatMigrateMemoriesReport(report: MigrateMemoriesReport): string[];

package/dist/memory-cli.js

@@ -0,0 +1,278 @@
+/**
+ * 0.3.0 memory release (design §3.4) — the `crewhaus memory` verb cluster's
+ * pure/IO helpers plus the `crewhaus migrate memories` data migration. Kept
+ * thin + separately testable, mirroring `sessions-index.ts` / `lessons.ts`
+ * (the entry file runs an argv switch on import, so logic lives here).
+ *
+ * The migration rides the existing migration-engine machinery: memory
+ * entries are versioned by their `schemaVersion` field (absent = v1), the
+ * engine walks the registered 1→2 chain per entry line, and the runner-side
+ * conventions (dry-run plan first, idempotent re-runs) are preserved.
+ * `.crewhaus/meta.json` records the store-level schema version so future
+ * migrations and doctors can see at a glance what has been backfilled.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import { MEMORY_SCHEMA_VERSION, isMemoryEntry } from "@crewhaus/memory-store";
+import { MigrationEngine } from "@crewhaus/migration-engine";
+export class MemoryCliError extends CrewhausError {
+    name = "MemoryCliError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+/** The memories root, relative to a harness cwd. */
+export const MEMORIES_SUBDIR = join(".crewhaus", "memories");
+/** Spec names that have a memory file under `memoriesDir`, sorted. */
+export function listMemorySpecs(memoriesDir) {
+    if (!existsSync(memoriesDir))
+        return [];
+    return readdirSync(memoriesDir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((f) => basename(f, ".jsonl"))
+        .sort();
+}
+/**
+ * Resolve which spec's store a single-target verb (`show`/`forget`) operates
+ * on: an explicit `--spec` wins; otherwise a lone memory file is unambiguous;
+ * anything else is an error naming the candidates.
+ */
+export function resolveMemorySpec(memoriesDir, specFlag) {
+    const specs = listMemorySpecs(memoriesDir);
+    if (specFlag !== undefined) {
+        if (!specs.includes(specFlag)) {
+            throw new MemoryCliError(`no memory file for spec "${specFlag}" under ${memoriesDir}${specs.length > 0 ? ` (have: ${specs.join(", ")})` : ""}`);
+        }
+        return specFlag;
+    }
+    if (specs.length === 0) {
+        throw new MemoryCliError(`no memory files under ${memoriesDir}`);
+    }
+    if (specs.length === 1)
+        return specs[0];
+    throw new MemoryCliError(`multiple memory files under ${memoriesDir} — pick one with --spec <name> (have: ${specs.join(", ")})`);
+}
+/** Compact human age: "3m", "7h", "12d". Injectable clock for tests. */
+export function humanAge(createdAtIso, nowMs) {
+    const created = Date.parse(createdAtIso);
+    if (Number.isNaN(created))
+        return "?";
+    const deltaMs = Math.max(0, nowMs - created);
+    const minutes = Math.floor(deltaMs / 60_000);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+const TEXT_PREVIEW_LEN = 72;
+function previewText(text) {
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return oneLine.length > TEXT_PREVIEW_LEN ? `${oneLine.slice(0, TEXT_PREVIEW_LEN - 1)}…` : oneLine;
+}
+/**
+ * Render one `memory list` row: id / age / status flag / provenance flag /
+ * tags / text preview. Deterministic given `nowMs`.
+ */
+export function renderMemoryListRow(item, nowMs) {
+    const { entry, status } = item;
+    const age = humanAge(entry.createdAt, nowMs).padStart(4);
+    const statusCol = (status === "live" ? "" : status).padEnd(10);
+    const provCol = (entry.provenance !== undefined ? "prov" : "").padEnd(4);
+    const tagsCol = entry.tags.length > 0 ? ` [${entry.tags.join(", ")}]` : "";
+    return `  ${entry.id}  ${age}  ${statusCol}  ${provCol}  ${previewText(entry.text)}${tagsCol}`;
+}
+/** Render the `memory list` block for one spec's items. */
+export function renderMemoryList(specName, items, nowMs) {
+    const live = items.filter((i) => i.status === "live").length;
+    const superseded = items.filter((i) => i.status === "superseded").length;
+    const expired = items.filter((i) => i.status === "expired").length;
+    const lines = [
+        `[memory] ${specName} — ${live} live, ${superseded} superseded, ${expired} expired`,
+    ];
+    for (const item of items)
+        lines.push(renderMemoryListRow(item, nowMs));
+    return lines;
+}
+/** Render `memory show <id>`: the full entry plus its lifecycle status. */
+export function renderMemoryShow(item) {
+    const { entry, status } = item;
+    const lines = [
+        `id:            ${entry.id}`,
+        `status:        ${status}`,
+        `created:       ${entry.createdAt}`,
+        `schemaVersion: ${entry.schemaVersion ?? "1 (implicit)"}`,
+        `tags:          ${entry.tags.length > 0 ? entry.tags.join(", ") : "(none)"}`,
+    ];
+    if (entry.expiresAt !== undefined) {
+        lines.push(`expires:       ${new Date(entry.expiresAt).toISOString()}`);
+    }
+    if (entry.supersededBy !== undefined) {
+        lines.push(`supersededBy:  ${entry.supersededBy}`);
+    }
+    if (entry.provenance !== undefined) {
+        const p = entry.provenance;
+        const bits = [];
+        if (p.sessionId !== undefined)
+            bits.push(`session ${p.sessionId}`);
+        if (p.evidence !== undefined && p.evidence.length > 0) {
+            bits.push(`evidence ${p.evidence.join(", ")}`);
+        }
+        lines.push(`provenance:    ${bits.length > 0 ? bits.join(" · ") : "(empty)"}`);
+    }
+    lines.push(`text:          ${entry.text}`);
+    return lines;
+}
+// -------- crewhaus migrate memories --------
+const SESSION_TAG_RE = /^sess_[0-9a-f]{16}$/;
+/**
+ * Backfill target for v1 auto-capture entries: they tag the sessionId today
+ * (`["auto-capture", "<sess_…>"]`), which is exactly the provenance the v2
+ * schema makes first-class.
+ */
+export function deriveAutoCaptureSessionId(tags) {
+    if (!tags.includes("auto-capture"))
+        return undefined;
+    return tags.find((t) => SESSION_TAG_RE.test(t));
+}
+/**
+ * The memory-entry 1 → 2 step, registered on a `MigrationEngine` so the
+ * chain-walk (and any future 2 → 3 step) reuses Section-28 machinery. The
+ * `version` key is a walk-time shim the file migrator injects from
+ * `schemaVersion` (absent = 1) and strips before serialising.
+ */
+export const MEMORY_ENTRY_1_TO_2 = Object.freeze({
+    from: 1,
+    to: 2,
+    up(entry) {
+        const tags = Array.isArray(entry["tags"])
+            ? entry["tags"].filter((t) => typeof t === "string")
+            : [];
+        const sessionId = deriveAutoCaptureSessionId(tags);
+        const backfill = entry["provenance"] === undefined && sessionId !== undefined
+            ? { provenance: { sessionId } }
+            : {};
+        return { ...entry, ...backfill, version: 2, schemaVersion: 2 };
+    },
+    down(entry) {
+        const { schemaVersion: _sv, provenance: _p, expiresAt: _e, supersededBy: _sb, ...rest } = entry;
+        return { ...rest, version: 1 };
+    },
+});
+/** An engine with the memory-entry chain registered. */
+export function createMemoryMigrationEngine() {
+    const engine = new MigrationEngine();
+    engine.register(MEMORY_ENTRY_1_TO_2);
+    return engine;
+}
+/**
+ * Migrate every `.crewhaus/memories/*.jsonl` under `rootDir` to the current
+ * entry schema. Idempotent: entries already at `schemaVersion >= 2` are
+ * skipped, so a re-run migrates 0 and rewrites nothing. Non-entry lines
+ * (tombstones, future line kinds, malformed junk) pass through VERBATIM —
+ * this migration never destroys data. Writes are atomic (tmp + rename).
+ * With `dryRun` no file is touched and no meta is stamped.
+ */
+export function migrateMemories(rootDir, opts = {}) {
+    const dryRun = opts.dryRun === true;
+    const now = opts.now ?? (() => new Date());
+    const memoriesDir = join(rootDir, MEMORIES_SUBDIR);
+    const engine = createMemoryMigrationEngine();
+    const files = [];
+    let totalMigrated = 0;
+    let totalSkipped = 0;
+    for (const specName of listMemorySpecs(memoriesDir)) {
+        const filePath = join(memoriesDir, `${specName}.jsonl`);
+        const raw = readFileSync(filePath, "utf-8");
+        const outLines = [];
+        let migrated = 0;
+        let skipped = 0;
+        let passthrough = 0;
+        for (const line of raw.split("\n")) {
+            if (line.trim() === "")
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                outLines.push(line); // malformed junk passes through untouched
+                passthrough += 1;
+                continue;
+            }
+            if (!isMemoryEntry(parsed)) {
+                outLines.push(line); // tombstones + future line kinds, verbatim
+                passthrough += 1;
+                continue;
+            }
+            const fromVersion = parsed.schemaVersion ?? 1;
+            if (fromVersion >= MEMORY_SCHEMA_VERSION) {
+                outLines.push(line);
+                skipped += 1;
+                continue;
+            }
+            const { version: _shim, ...migratedEntry } = engine.migrate({ ...parsed, version: fromVersion }, MEMORY_SCHEMA_VERSION);
+            outLines.push(JSON.stringify(migratedEntry));
+            migrated += 1;
+        }
+        files.push({ specName, migrated, skipped, passthrough });
+        totalMigrated += migrated;
+        totalSkipped += skipped;
+        if (!dryRun && migrated > 0) {
+            const tmpPath = `${filePath}.tmp`;
+            writeFileSync(tmpPath, outLines.length > 0 ? `${outLines.join("\n")}\n` : "", {
+                mode: 0o600,
+            });
+            renameSync(tmpPath, filePath);
+        }
+    }
+    // Dry runs write nothing; a harness with no memory files has nothing to
+    // stamp either (new stores write v2 natively).
+    if (dryRun || files.length === 0) {
+        return { files, migrated: totalMigrated, skipped: totalSkipped, dryRun };
+    }
+    const metaPath = stampMemoriesMeta(rootDir, now);
+    return { files, migrated: totalMigrated, skipped: totalSkipped, dryRun, metaPath };
+}
+/**
+ * Record the memories schema version in `.crewhaus/meta.json` (created when
+ * absent; other top-level keys are preserved). Returns the meta path.
+ */
+export function stampMemoriesMeta(rootDir, now = () => new Date()) {
+    const crewhausDir = join(rootDir, ".crewhaus");
+    const metaPath = join(crewhausDir, "meta.json");
+    let meta = {};
+    if (existsSync(metaPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(metaPath, "utf-8"));
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                meta = parsed;
+            }
+        }
+        catch {
+            // Unreadable meta — rebuild it rather than fail the migration.
+        }
+    }
+    meta["memories"] = {
+        schemaVersion: MEMORY_SCHEMA_VERSION,
+        migratedAt: now().toISOString(),
+    };
+    mkdirSync(crewhausDir, { recursive: true });
+    writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`, { mode: 0o600 });
+    return metaPath;
+}
+/** Render the `migrate memories` report, one line per file + a summary. */
+export function formatMigrateMemoriesReport(report) {
+    const lines = [];
+    for (const f of report.files) {
+        lines.push(`  ${f.specName}: ${f.migrated} migrated, ${f.skipped} already v${MEMORY_SCHEMA_VERSION}, ${f.passthrough} passthrough line(s)`);
+    }
+    const dryNote = report.dryRun ? " (dry-run — nothing written)" : "";
+    lines.push(`[migrate] memories: ${report.migrated} entry(ies) migrated across ${report.files.length} file(s)${dryNote}`);
+    if (report.metaPath !== undefined) {
+        lines.push(`[migrate] stamped ${report.metaPath} (memories.schemaVersion ${MEMORY_SCHEMA_VERSION})`);
+    }
+    return lines;
+}

package/dist/run-failure.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v0.3.0 Goal 6 — the CLI's terminal-failure rendering, factored out of the
+ * entry file `index.ts` (which runs a top-level argv switch and so cannot be
+ * imported by a test without executing the CLI). `die()` and the `crewhaus
+ * run` failure path both route through {@link renderCliFailure} so the CLI
+ * prints ONE canonical shape:
+ *
+ *   - a `RunFailedError` renders its structured report via
+ *     `formatRunFailure()` with the `crewhaus:` prefix and exits with the
+ *     report's coded status (billing 31, auth 30, …);
+ *   - every other CrewhausError (and every plain-string die()) keeps the
+ *     pre-0.3.0 one-liner `crewhaus: <message>` + exit 1, byte-for-byte.
+ */
+import { type CrewhausError } from "@crewhaus/errors";
+/**
+ * The resume hint `crewhaus run` appends to a terminal failure when the
+ * target is cli and a session was persisted before the run died (design
+ * §8.2's exact wording).
+ */
+export declare const CONTINUE_NOTE = "Your session is saved \u2014 `crewhaus run --continue` resumes exactly where it stopped.";
+export type RenderedCliFailure = {
+    /** Full stderr text (no trailing newline). */
+    readonly text: string;
+    /** Process exit code: report.exitCode for a RunFailedError, else 1. */
+    readonly exitCode: number;
+};
+/**
+ * Render a fatal CLI error. `notes` (e.g. {@link CONTINUE_NOTE}) are only
+ * meaningful for a RunFailedError — they land between the Fix/Docs lines
+ * and the exit line; they are ignored for the one-liner shape.
+ */
+export declare function renderCliFailure(err: string | CrewhausError, opts?: {
+    notes?: readonly string[];
+}): RenderedCliFailure;

package/dist/run-failure.js

@@ -0,0 +1,38 @@
+/**
+ * v0.3.0 Goal 6 — the CLI's terminal-failure rendering, factored out of the
+ * entry file `index.ts` (which runs a top-level argv switch and so cannot be
+ * imported by a test without executing the CLI). `die()` and the `crewhaus
+ * run` failure path both route through {@link renderCliFailure} so the CLI
+ * prints ONE canonical shape:
+ *
+ *   - a `RunFailedError` renders its structured report via
+ *     `formatRunFailure()` with the `crewhaus:` prefix and exits with the
+ *     report's coded status (billing 31, auth 30, …);
+ *   - every other CrewhausError (and every plain-string die()) keeps the
+ *     pre-0.3.0 one-liner `crewhaus: <message>` + exit 1, byte-for-byte.
+ */
+import { formatRunFailure, isRunFailedError } from "@crewhaus/errors";
+/**
+ * The resume hint `crewhaus run` appends to a terminal failure when the
+ * target is cli and a session was persisted before the run died (design
+ * §8.2's exact wording).
+ */
+export const CONTINUE_NOTE = "Your session is saved — `crewhaus run --continue` resumes exactly where it stopped.";
+/**
+ * Render a fatal CLI error. `notes` (e.g. {@link CONTINUE_NOTE}) are only
+ * meaningful for a RunFailedError — they land between the Fix/Docs lines
+ * and the exit line; they are ignored for the one-liner shape.
+ */
+export function renderCliFailure(err, opts) {
+    if (typeof err !== "string" && isRunFailedError(err)) {
+        return {
+            text: formatRunFailure(err.report, {
+                prefix: "crewhaus:",
+                ...(opts?.notes !== undefined ? { notes: opts.notes } : {}),
+            }),
+            exitCode: err.report.exitCode,
+        };
+    }
+    const message = typeof err === "string" ? err : err.message;
+    return { text: `crewhaus: ${message}`, exitCode: 1 };
+}