crewhaus 0.2.3 → 0.3.0

package/dist/ci-scaffold.d.ts

@@ -1,5 +1,23 @@
 export declare const EVAL_CI_WORKFLOW_RELPATH: string;
 export declare const SENTINEL_WORKFLOW_RELPATH: string;
+export declare const DREAM_WORKFLOW_RELPATH: string;
+/**
+ * v0.3.0 PR 14 (§6.3) — the scheduled-consolidation cron workflow,
+ * scaffolded by `crewhaus dream init <spec>`. Follows the sentinel/flywheel
+ * conventions: odd-minute cron (every workflow scheduled at :00 queues
+ * behind GitHub's backlog), `workflow_dispatch` for manual runs, and a
+ * human-auditable job body. The cadence is derived from the spec's
+ * `memory.dream.every`: sub-daily schedules get an hourly cron, daily and
+ * slower get a nightly one — over-firing is harmless because `crewhaus
+ * dream run` is WINDOW-IDEMPOTENT (a second invocation inside one
+ * `every` window is a cached no-op), which is exactly what makes the verb
+ * cron-safe.
+ */
+export declare function buildDreamWorkflowYaml(opts: {
+    readonly specPath: string;
+    readonly everyMs: number;
+    readonly harnessDir?: string;
+}): string;
 /**
  * Item 30 — the nightly model-drift sentinel workflow, scaffolded by
  * `crewhaus init --sentinel`. Mirrors the shipped

package/dist/ci-scaffold.js

@@ -35,6 +35,80 @@ import { join } from "node:path";
 import { normalizeHarnessDir } from "./flywheel";
 export const EVAL_CI_WORKFLOW_RELPATH = join(".github", "workflows", "crewhaus-eval.yml");
 export const SENTINEL_WORKFLOW_RELPATH = join(".github", "workflows", "sentinel-drift.yml");
+export const DREAM_WORKFLOW_RELPATH = join(".github", "workflows", "crewhaus-dream.yml");
+/**
+ * v0.3.0 PR 14 (§6.3) — the scheduled-consolidation cron workflow,
+ * scaffolded by `crewhaus dream init <spec>`. Follows the sentinel/flywheel
+ * conventions: odd-minute cron (every workflow scheduled at :00 queues
+ * behind GitHub's backlog), `workflow_dispatch` for manual runs, and a
+ * human-auditable job body. The cadence is derived from the spec's
+ * `memory.dream.every`: sub-daily schedules get an hourly cron, daily and
+ * slower get a nightly one — over-firing is harmless because `crewhaus
+ * dream run` is WINDOW-IDEMPOTENT (a second invocation inside one
+ * `every` window is a cached no-op), which is exactly what makes the verb
+ * cron-safe.
+ */
+export function buildDreamWorkflowYaml(opts) {
+    const sub = normalizeHarnessDir(opts.harnessDir);
+    const workingDirLine = sub === "" ? "" : `\n        working-directory: ${sub}`;
+    const subdirNote = sub === ""
+        ? ""
+        : `#   - Scaffolded for the harness at ${sub}/ — the job's working-directory is
+#     set so the spec path resolves inside it.\n`;
+    const hourly = opts.everyMs < 24 * 60 * 60 * 1000;
+    const cron = hourly ? "19 * * * *" : "19 4 * * *";
+    const cadenceNote = hourly
+        ? "# Hourly at :19 (off the hour to dodge cron scheduling backlog) — the\n# spec's dream cadence is sub-daily; window idempotency dedupes over-fires."
+        : "# Nightly at 04:19 UTC (off the hour to dodge cron scheduling backlog).";
+    return `# crewhaus-dream.yml — scaffolded by \`crewhaus dream init\` (v0.3.0 §6.3).
+#
+# Scheduled memory consolidation: runs \`crewhaus dream run\` on a cron. The
+# verb is CRON-SAFE by construction — runs are idempotency-keyed on the
+# schedule window (dream:<spec>:<floor(now/every)>), so this cron, a daemon
+# janitor tick, and a manual \`crewhaus dream\` can never double-fire; a
+# fresh window runs the deterministic pass plus (mode: full, budget_usd > 0)
+# ONE bounded model synthesis session capped by the spec's budget.
+${subdirNote}#
+# Required repo secret: ANTHROPIC_API_KEY (billed by the model phase, capped
+# at the spec's memory.dream.budget_usd per run).
+
+name: crewhaus-dream
+
+on:
+  schedule:
+    ${cadenceNote.replace(/\n/g, "\n    ")}
+    - cron: "${cron}"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  dream:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash${workingDirLine}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install crewhaus CLI
+        run: |
+          bun add -g crewhaus
+          echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
+
+      - name: Run the consolidation pass
+        env:
+          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          crewhaus dream run ${opts.specPath}
+`;
+}
 /**
  * Item 30 — the nightly model-drift sentinel workflow, scaffolded by
  * `crewhaus init --sentinel`. Mirrors the shipped

package/dist/doctor-probe.d.ts

@@ -0,0 +1,72 @@
+/**
+ * v0.3.0 Goal 6 — `crewhaus doctor --probe`: an OPT-IN live credential
+ * probe. The default doctor checks only credential PRESENCE, so a present-
+ * but-invalid key or an out-of-funding account sails through doctor and
+ * dies mid-run. `--probe` issues one ~1-token live call per configured
+ * provider (maxTokens: 1, a two-character prompt — fractions of a cent at
+ * worst) through the SAME adapter stack the run path uses (model-router's
+ * `resolveModel`), so what passes here is exactly what the run will do.
+ *
+ * Failures classify through recovery-engine's `classify()` — the single
+ * choke point all four adapters normalise into — so an unfunded account
+ * reports `billing`, a bad key `auth`, and doctor's output names the fix
+ * class instead of dumping a raw SDK message shape.
+ *
+ * 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).
+ * Plan-building is pure; the prober takes an injected `resolve` seam so
+ * tests drive it with a mocked adapter and no network.
+ */
+import type { ProviderAdapter } from "@crewhaus/adapter-anthropic";
+import { type DoctorCredentialCheck, type DoctorProviderId } from "./doctor-checks";
+/**
+ * Cheapest sensible probe model per provider, used for providers whose env
+ * is configured but which the cwd spec does not select. The spec's own
+ * `agent.model` is always probed verbatim for the selected provider — that
+ * also catches per-model access failures (e.g. Bedrock model-access 403s).
+ * bedrock and local have no default: bedrock needs a region-dependent model
+ * id (probed only when the spec selects it) and local endpoints are covered
+ * by `doctor --detect`'s reachability probe.
+ */
+export declare const DEFAULT_PROBE_MODELS: Partial<Record<DoctorProviderId, string>>;
+export type ProbeTarget = {
+    readonly provider: DoctorProviderId;
+    readonly model: string;
+    /** Why this target is in the plan. */
+    readonly reason: "spec-model" | "configured-env";
+};
+/**
+ * Decide which providers to probe: the cwd spec's model (verbatim) for its
+ * selected provider, plus the cheap default model for every OTHER provider
+ * whose credentials are visibly configured. Pure — no network.
+ */
+export declare function buildProbePlan(specModel: string | undefined, env: NodeJS.ProcessEnv): ProbeTarget[];
+export type ProbeResult = {
+    readonly provider: DoctorProviderId;
+    readonly model: string;
+    readonly pass: boolean;
+    /** Human-readable outcome ("live call ok (312ms)" / "billing — …"). */
+    readonly detail: string;
+    /** recovery-engine taxonomy bucket on failure (billing/auth/rate_limit/…). */
+    readonly failureClass?: string;
+};
+export type ProbeDeps = {
+    /** Injected model→adapter resolution; production uses model-router's resolveModel. */
+    readonly resolve?: (model: string) => Promise<{
+        readonly adapter: ProviderAdapter;
+        readonly modelId: string;
+    }>;
+    /** Injected clock for deterministic durations in tests. */
+    readonly now?: () => number;
+};
+/** Issue the ~1-token live call for one target and classify the outcome. */
+export declare function probeProvider(target: ProbeTarget, deps?: ProbeDeps): Promise<ProbeResult>;
+/** Run the whole plan sequentially (a probe per provider; order = plan order). */
+export declare function runProviderProbes(plan: ReadonlyArray<ProbeTarget>, deps?: ProbeDeps): Promise<ProbeResult[]>;
+/**
+ * Fold probe results into doctor's check shape (✓ / ✗ lines + exit gate).
+ * Doctor's renderer prints `✓ <label>` for passes (no reason) and
+ * `✗ <label>: <reason>` for failures, so the ok-detail rides in the pass
+ * label and the classified failure detail in the reason.
+ */
+export declare function probeResultsToChecks(results: ReadonlyArray<ProbeResult>): DoctorCredentialCheck[];

package/dist/doctor-probe.js

@@ -0,0 +1,92 @@
+import { resolveModel } from "@crewhaus/model-router";
+import { classify } from "@crewhaus/recovery-engine";
+import { providerCredentialsSatisfied, selectedProvider, } from "./doctor-checks";
+/**
+ * Cheapest sensible probe model per provider, used for providers whose env
+ * is configured but which the cwd spec does not select. The spec's own
+ * `agent.model` is always probed verbatim for the selected provider — that
+ * also catches per-model access failures (e.g. Bedrock model-access 403s).
+ * bedrock and local have no default: bedrock needs a region-dependent model
+ * id (probed only when the spec selects it) and local endpoints are covered
+ * by `doctor --detect`'s reachability probe.
+ */
+export const DEFAULT_PROBE_MODELS = {
+    anthropic: "claude-haiku-4-5",
+    openai: "openai/gpt-4o-mini",
+    gemini: "gemini/gemini-2.5-flash",
+};
+/**
+ * Decide which providers to probe: the cwd spec's model (verbatim) for its
+ * selected provider, plus the cheap default model for every OTHER provider
+ * whose credentials are visibly configured. Pure — no network.
+ */
+export function buildProbePlan(specModel, env) {
+    const targets = [];
+    const specProvider = specModel !== undefined ? selectedProvider(specModel) : undefined;
+    if (specModel !== undefined && specProvider !== undefined) {
+        targets.push({ provider: specProvider, model: specModel, reason: "spec-model" });
+    }
+    for (const [provider, model] of Object.entries(DEFAULT_PROBE_MODELS)) {
+        if (provider === specProvider)
+            continue;
+        if (!providerCredentialsSatisfied(model, env))
+            continue;
+        targets.push({ provider, model, reason: "configured-env" });
+    }
+    return targets;
+}
+/** Issue the ~1-token live call for one target and classify the outcome. */
+export async function probeProvider(target, deps = {}) {
+    const resolve = deps.resolve ?? (async (m) => await resolveModel(m));
+    const now = deps.now ?? (() => performance.now());
+    const startMs = now();
+    try {
+        const { adapter, modelId } = await resolve(target.model);
+        const stream = adapter.stream({
+            model: modelId,
+            system: [],
+            messages: [{ role: "user", content: "hi" }],
+            maxTokens: 1,
+        });
+        // Drain — with maxTokens: 1 the whole exchange is a handful of events.
+        for await (const _ of stream) {
+            // Nothing to do with the token; reaching the end proves the account works.
+        }
+        return {
+            provider: target.provider,
+            model: target.model,
+            pass: true,
+            detail: `live call ok (${Math.round(now() - startMs)}ms)`,
+        };
+    }
+    catch (err) {
+        const failureClass = classify(err);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            provider: target.provider,
+            model: target.model,
+            pass: false,
+            detail: failureClass === "unknown" ? message : `${failureClass} — ${message}`,
+            failureClass,
+        };
+    }
+}
+/** Run the whole plan sequentially (a probe per provider; order = plan order). */
+export async function runProviderProbes(plan, deps = {}) {
+    const results = [];
+    for (const target of plan) {
+        results.push(await probeProvider(target, deps));
+    }
+    return results;
+}
+/**
+ * Fold probe results into doctor's check shape (✓ / ✗ lines + exit gate).
+ * Doctor's renderer prints `✓ <label>` for passes (no reason) and
+ * `✗ <label>: <reason>` for failures, so the ok-detail rides in the pass
+ * label and the classified failure detail in the reason.
+ */
+export function probeResultsToChecks(results) {
+    return results.map((r) => r.pass
+        ? { label: `live probe: ${r.provider} (${r.model}) — ${r.detail}`, pass: true }
+        : { label: `live probe: ${r.provider} (${r.model})`, pass: false, reason: r.detail });
+}

package/dist/dream-cli.d.ts

@@ -0,0 +1,53 @@
+import { CrewhausError } from "@crewhaus/errors";
+import type { ParseArgsSchema, ParsedArgs } from "@crewhaus/infra-utils";
+import { type DreamModelPhase, type DreamRunReport, type MemoryWiringFragment } from "@crewhaus/memory-service";
+import { type RunContext } from "@crewhaus/run-context";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+export declare class DreamCliError extends CrewhausError {
+    readonly name = "DreamCliError";
+    constructor(message: string, cause?: unknown);
+}
+export declare const DREAM_CLI_SCHEMA: ParseArgsSchema;
+/** The exact runChatLoop option subset the dream session uses — a dedicated
+ *  type so tests can inject a capturing `chatLoop` and pin every field. */
+export type DreamChatLoopOptions = {
+    readonly model: string;
+    readonly instructions: string;
+    readonly runContext: RunContext;
+    readonly singleTurn: true;
+    readonly seedMessages: ReadonlyArray<{
+        readonly role: "user";
+        readonly content: string;
+    }>;
+    readonly sessionName: string;
+    readonly sessionTarget: "dream";
+    readonly tools: ReadonlyArray<RegisteredTool>;
+    readonly hooks: ReadonlyArray<never>;
+    readonly maxToolIterations: number;
+    readonly budget: {
+        readonly usdMicros: number;
+        readonly onExceed: {
+            readonly kind: "stop";
+        };
+    };
+    readonly spinner: false;
+};
+export type DreamChatLoopFn = (opts: DreamChatLoopOptions) => Promise<string>;
+/**
+ * Build the model-phase runner (§6.2): ONE bounded fresh session seeded
+ * with the playbook + phase-1 findings, seeing ONLY the memory-fabric
+ * tools (wired fresh, spec scope), capped by the item-27 budget option
+ * (`budget_usd` → usdMicros, `onExceed: stop`) and the tool-iteration
+ * bound. Spend is observed with a cost-tracker on the run's own trace bus.
+ */
+export declare function buildDreamModelPhase(opts: {
+    readonly model: string;
+    readonly specName: string;
+    readonly fragment: MemoryWiringFragment;
+    readonly cwd: string;
+    readonly chatLoop?: DreamChatLoopFn;
+}): DreamModelPhase;
+/** Render a run report in the design-§6.3 shape. Exported for tests. */
+export declare function renderDreamRunReport(report: DreamRunReport): string[];
+/** The `crewhaus dream` dispatch target — `index.ts` routes here. */
+export declare function runDreamCommand(args: ParsedArgs, action: "run" | "status" | "init"): Promise<void>;

package/dist/dream-cli.js

@@ -0,0 +1,329 @@
+import { spawnSync } from "node:child_process";
+/**
+ * v0.3.0 PR 14 (design §6.3) — the `crewhaus dream run|status|init` verbs.
+ *
+ * Kept in a side-effect-free module (the CLI entry file runs an argv switch
+ * on import), mirroring `retention.ts` / `memory-cli.ts`: `index.ts` holds
+ * only the dispatch registration.
+ *
+ *   - `run`    — both phases per the spec's `memory.dream` (mode/budget):
+ *                the deterministic pass always; then, for `mode: full` with
+ *                `budget_usd > 0`, ONE bounded model synthesis session
+ *                (`sessionTarget: "dream"`, singleTurn, capped tool loop,
+ *                item-27 budget option). CRON-SAFE: runs are idempotency-
+ *                keyed on the schedule window, so a cron, a daemon janitor
+ *                tick, and a manual invocation can never double-fire.
+ *   - `status` — schedule state + next due, from
+ *                `.crewhaus/dream/<spec>/state.json`.
+ *   - `init`   — scaffolds `.github/workflows/crewhaus-dream.yml` (odd-
+ *                minute cron convention) via ci-scaffold.
+ *
+ * The model-phase runner built here is the REFERENCE implementation of
+ * dream-engine's `DreamModelPhase` seam: the daemon emitters generate the
+ * same shape. `buildDreamModelPhase` takes an injectable `chatLoop` so
+ * tests can pin the exact runChatLoop options (budget mapping included)
+ * without a model call.
+ */
+import { readFileSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { lower } from "@crewhaus/compiler";
+import { createCostTracker } from "@crewhaus/cost-tracker";
+import { CrewhausError } from "@crewhaus/errors";
+import { openEventLog } from "@crewhaus/event-log";
+import { memoryFragmentFromIr, wireDream, wireMemory, } from "@crewhaus/memory-service";
+import { createRunContext } from "@crewhaus/run-context";
+import { runChatLoop } from "@crewhaus/runtime-core";
+import { parseSpec } from "@crewhaus/spec";
+import { DREAM_WORKFLOW_RELPATH, buildDreamWorkflowYaml } from "./ci-scaffold";
+import { scaffoldWorkflowFile } from "./flywheel";
+export class DreamCliError extends CrewhausError {
+    name = "DreamCliError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export const DREAM_CLI_SCHEMA = {
+    flags: [
+        // Bypass the window idempotency (the run still takes the lock and
+        // records its outcome) — for operators re-running after fixing config.
+        { name: "force" },
+        // `init`: overwrite an existing workflow scaffold.
+        { name: "help", short: "h" },
+    ],
+};
+const DREAM_USAGE = "usage: crewhaus dream [run|status|init] <spec.yaml> [--force]\n" +
+    "  run     both phases per the spec's memory.dream (cron-safe: window-idempotent)\n" +
+    "  status  schedule state + next due (.crewhaus/dream/<spec>/state.json)\n" +
+    "  init    scaffold .github/workflows/crewhaus-dream.yml (odd-minute cron)\n" +
+    "  --force run: bypass the window idempotency · init: overwrite the workflow\n";
+function loadDreamSpec(specPath) {
+    if (specPath === undefined || specPath === "") {
+        throw new DreamCliError(`crewhaus dream: missing <spec.yaml> argument\n${DREAM_USAGE}`);
+    }
+    const absSpec = resolve(specPath);
+    let yamlText;
+    try {
+        yamlText = readFileSync(absSpec, "utf-8");
+    }
+    catch (err) {
+        throw new DreamCliError(`crewhaus dream: cannot read spec "${specPath}": ${err.message}`);
+    }
+    const ir = lower(parseSpec(yamlText));
+    if (ir.memory?.dream === undefined || ir.memory.enabled === false) {
+        throw new DreamCliError(`crewhaus dream: spec "${ir.name}" declares no memory.dream schedule — add\n  memory:\n    dream:\n      every: 24h\n      mode: full\n      budget_usd: 0.5\nand recompile. (mode: deterministic / budget_usd: 0 keep the pass model-free.)`);
+    }
+    // The dream always consolidates the SPEC-scoped agenda (§14.5) — override
+    // a session-scoped continuity (channel) so the store wiring never needs a
+    // conversation id.
+    const raw = memoryFragmentFromIr(ir);
+    const fragment = raw.continuity !== undefined
+        ? { ...raw, continuity: { ...raw.continuity, scope: "spec" } }
+        : raw;
+    return { ir, fragment, absSpec };
+}
+/**
+ * Build the model-phase runner (§6.2): ONE bounded fresh session seeded
+ * with the playbook + phase-1 findings, seeing ONLY the memory-fabric
+ * tools (wired fresh, spec scope), capped by the item-27 budget option
+ * (`budget_usd` → usdMicros, `onExceed: stop`) and the tool-iteration
+ * bound. Spend is observed with a cost-tracker on the run's own trace bus.
+ */
+export function buildDreamModelPhase(opts) {
+    const chatLoop = opts.chatLoop ?? runChatLoop;
+    return {
+        model: opts.model,
+        run: async (input) => {
+            const tools = [];
+            await wireMemory(opts.fragment, {
+                catalog: {
+                    register: (t) => {
+                        tools.push(t);
+                    },
+                },
+                cwd: opts.cwd,
+            });
+            const runContext = createRunContext();
+            const tracker = createCostTracker(runContext.eventBus, { suppressEvents: true });
+            try {
+                const summary = await chatLoop({
+                    model: opts.model,
+                    instructions: input.playbook,
+                    runContext,
+                    singleTurn: true,
+                    seedMessages: [{ role: "user", content: input.prompt }],
+                    sessionName: opts.specName,
+                    sessionTarget: "dream",
+                    tools,
+                    hooks: [],
+                    maxToolIterations: input.maxToolIterations,
+                    budget: {
+                        usdMicros: Math.round(input.budgetUsd * 1_000_000),
+                        onExceed: { kind: "stop" },
+                    },
+                    spinner: false,
+                });
+                return {
+                    sessionId: runContext.sessionId,
+                    spentUsd: tracker.getRunCost(runContext.runId).totalUsdMicros / 1_000_000,
+                    summary,
+                };
+            }
+            finally {
+                tracker.unsubscribe();
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// rendering (the §6.3 output shape)
+// ---------------------------------------------------------------------------
+function shortIso(iso) {
+    return `${iso.slice(0, 16)}Z`;
+}
+function renderEvery(ms) {
+    const DAY = 86_400_000;
+    const HOUR = 3_600_000;
+    const MINUTE = 60_000;
+    if (ms % DAY === 0)
+        return `${ms / DAY}d`;
+    if (ms % HOUR === 0)
+        return `${ms / HOUR}h`;
+    if (ms % MINUTE === 0)
+        return `${ms / MINUTE}m`;
+    return `${Math.round(ms / 1000)}s`;
+}
+function line(label, detail) {
+    return `    ✓ ${label.padEnd(18)} ${detail}`;
+}
+/** Render a run report in the design-§6.3 shape. Exported for tests. */
+export function renderDreamRunReport(report) {
+    const c = report.phase1.counts;
+    const lines = [`crewhaus dream — ${report.specName}`];
+    if (report.cached) {
+        lines.push(`  window ${report.windowKey} already consolidated (cached report from ${shortIso(report.startedAt)})`);
+    }
+    lines.push("  deterministic");
+    lines.push(line("session summaries", c.sessionsIndexed === 0 ? "nothing new to index" : `${c.sessionsIndexed} sessions → indexed`));
+    lines.push(line("fact dedupe", `${c.factsBefore} → ${c.factsAfter} (${c.factsSuperseded} superseded)`));
+    lines.push(line("fact decay", `${c.factsStale} fact${c.factsStale === 1 ? "" : "s"} >90d flagged stale`));
+    lines.push(line("proof freeze", `${c.proofsChecked} checked · ${c.sessionsPinned} session${c.sessionsPinned === 1 ? "" : "s"} pinned before TTL`));
+    lines.push(line("wiki staleness", `${c.wikiStale} article${c.wikiStale === 1 ? "" : "s"} unverified >30d`));
+    lines.push(line("focus refresh", `next-actions rebuilt from ${c.openPlans} open plan${c.openPlans === 1 ? "" : "s"}`));
+    lines.push(line("trash purge", `${c.trashPurged} snapshot${c.trashPurged === 1 ? "" : "s"} past the 7d undo window`));
+    const model = report.model;
+    if (model === undefined) {
+        lines.push("  model              (mode deterministic — no model phase)");
+    }
+    else if (model.ran) {
+        lines.push(`  model (${model.model} · cap $${model.budgetUsd.toFixed(2)})`);
+        if (model.actions.length === 0) {
+            lines.push("    (no tool mutations — the session found nothing to consolidate)");
+        }
+        for (const action of model.actions) {
+            lines.push(`    ✓ ${action.toolName}${action.detail !== undefined ? ` ${action.detail}` : ""}`);
+        }
+    }
+    else if (model.refusal !== undefined) {
+        lines.push(`  model (${model.model}) REFUSED — ${model.refusal}`);
+    }
+    else if (model.error !== undefined) {
+        lines.push(`  model (${model.model}) FAILED — ${model.error} (window not consumed; retries)`);
+    }
+    else {
+        lines.push(`  model              skipped — ${model.skipped ?? "deterministic only"}`);
+    }
+    const seconds = report.durationMs / 1000;
+    const spent = model?.ran === true && model.spentUsd !== undefined ? model.spentUsd : undefined;
+    lines.push(`  done in ${seconds < 10 ? seconds.toFixed(1) : Math.round(seconds).toString()}s` +
+        `${spent !== undefined ? ` · spent $${spent.toFixed(2)}` : ""}` +
+        ` · next due ${shortIso(report.nextDueAt)}`);
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// verbs
+// ---------------------------------------------------------------------------
+async function runVerb(args) {
+    const cwd = process.cwd();
+    const { ir, fragment } = loadDreamSpec(args.positional[0]);
+    const model = ir.agent?.model;
+    const modelPhase = model !== undefined
+        ? buildDreamModelPhase({ model, specName: ir.name, fragment, cwd })
+        : undefined;
+    const sessionRootDir = join(cwd, ".crewhaus", "sessions");
+    const wired = wireDream(fragment, {
+        cwd,
+        ...(modelPhase !== undefined ? { modelPhase } : {}),
+        // The dream_run proof record lands in the dream session's own log when
+        // the model phase ran (state.json is the durable record otherwise).
+        appendEvent: async (event) => {
+            const sessionId = event.payload.sessionId;
+            if (typeof sessionId !== "string")
+                return;
+            const log = await openEventLog(sessionId, { rootDir: sessionRootDir });
+            await log.append({ kind: "dream_run", payload: event.payload });
+            await log.close();
+        },
+        log: (lineText) => process.stderr.write(`${lineText}\n`),
+    });
+    if (wired === null) {
+        throw new DreamCliError(`crewhaus dream: spec "${ir.name}" has no dream schedule`);
+    }
+    if (model === undefined) {
+        process.stderr.write("[dream] this shape has no single agent model — running the deterministic phase only\n");
+    }
+    const report = await wired.engine.run({
+        trigger: "cli",
+        ...(args.flags["force"] === true ? { force: true } : {}),
+    });
+    for (const lineText of renderDreamRunReport(report)) {
+        process.stdout.write(`${lineText}\n`);
+    }
+    // A refusal or model failure exits non-zero AFTER the report renders —
+    // scheduled runs must alert (the deterministic pass still completed).
+    if (report.outcome === "model_refused_unpriced") {
+        throw new DreamCliError(report.model?.refusal ?? "dream: unpriced model refused");
+    }
+    if (report.outcome === "model_failed") {
+        throw new DreamCliError(`dream: model phase failed — ${report.model?.error ?? "unknown error"} (deterministic pass completed; the window was not consumed, so the next scheduled run retries)`);
+    }
+}
+async function statusVerb(args) {
+    const cwd = process.cwd();
+    const { ir, fragment } = loadDreamSpec(args.positional[0]);
+    const wired = wireDream(fragment, { cwd });
+    if (wired === null) {
+        throw new DreamCliError(`crewhaus dream: spec "${ir.name}" has no dream schedule`);
+    }
+    const status = await wired.engine.status();
+    const cfg = status.config;
+    const lines = [
+        `crewhaus dream — ${ir.name}`,
+        `  every ${renderEvery(cfg.everyMs)} · mode ${cfg.mode} · budget $${cfg.budgetUsd.toFixed(2)}`,
+        `  state ${join(wired.engine.stateDir(), "state.json")}`,
+    ];
+    if (status.state === null) {
+        lines.push("  never run — overdue (a boot catch-up or 'crewhaus dream run' will start it)");
+    }
+    else {
+        lines.push(`  last run ${shortIso(status.state.lastRunAt)} (${status.state.lastOutcome})`);
+        lines.push(status.overdue
+            ? "  next due now (overdue)"
+            : `  next due ${shortIso(status.nextDueAt ?? status.state.lastRunAt)}`);
+        if (status.state.lastEvidence.length > 0) {
+            lines.push(`  last evidence ${status.state.lastEvidence.join(", ")}`);
+        }
+    }
+    for (const lineText of lines) {
+        process.stdout.write(`${lineText}\n`);
+    }
+}
+/** Finding 7 (mirrors index.ts's resolveWorkflowRoot, which is private to
+ *  the dispatch module): GitHub only reads workflows at the repo root. */
+function workflowRootFor(harnessAbsDir, fallbackRoot) {
+    const top = spawnSync("git", ["-C", harnessAbsDir, "rev-parse", "--show-toplevel"], {
+        encoding: "utf-8",
+    });
+    const toplevel = top.status === 0 ? top.stdout.trim() : "";
+    const root = toplevel !== "" ? toplevel : realpathSync(fallbackRoot);
+    const rel = relative(root, realpathSync(harnessAbsDir));
+    if (rel === "" || rel === ".")
+        return { root, harnessDir: "" };
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return { root: harnessAbsDir, harnessDir: "" };
+    return { root, harnessDir: rel.split(sep).join("/") };
+}
+async function initVerb(args) {
+    const { ir, absSpec } = loadDreamSpec(args.positional[0]);
+    const dream = ir.memory?.dream;
+    if (dream === undefined)
+        throw new DreamCliError("unreachable: loadDreamSpec guarantees dream");
+    const { root, harnessDir } = workflowRootFor(dirname(absSpec), process.cwd());
+    const specPathInWorkflow = relative(harnessDir === "" ? root : join(root, harnessDir), absSpec)
+        .split(sep)
+        .join("/");
+    const scaffolded = scaffoldWorkflowFile({
+        rootDir: root,
+        relPath: DREAM_WORKFLOW_RELPATH,
+        content: buildDreamWorkflowYaml({
+            specPath: specPathInWorkflow,
+            everyMs: dream.everyMs,
+            ...(harnessDir !== "" ? { harnessDir } : {}),
+        }),
+        force: args.flags["force"] === true,
+    });
+    process.stdout.write(`wrote ${scaffolded.path}\n`);
+    process.stdout.write(`  cron: ${dream.everyMs < 86_400_000 ? '"19 * * * *" (hourly — sub-daily cadence)' : '"19 4 * * *" (nightly)'} · window idempotency dedupes over-fires\n  next: commit the workflow and add the ANTHROPIC_API_KEY repo secret\n        (the model phase is capped at $${(dream.budgetUsd ?? 0).toFixed(2)} per run by memory.dream.budget_usd)\n`);
+}
+/** The `crewhaus dream` dispatch target — `index.ts` routes here. */
+export async function runDreamCommand(args, action) {
+    if (args.flags["help"] === true) {
+        process.stdout.write(DREAM_USAGE);
+        return;
+    }
+    if (action === "run")
+        return runVerb(args);
+    if (action === "status")
+        return statusVerb(args);
+    return initVerb(args);
+}