@femtomc/mu 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @femtomc/mu
+
+Node CLI (and programmatic wrapper) for the mu `.mu/` issue DAG + forum store.
+
+## Install
+
+After publishing:
+
+```bash
+npm install -g @femtomc/mu
+# or: bun add -g @femtomc/mu
+```
+
+From this repo:
+
+```bash
+cd mu
+bun install
+bun run build
+packages/cli/dist/cli.js --help
+```
+
+## Usage
+
+```ts
+import { run } from "@femtomc/mu";
+
+const r = await run(["status", "--json"]);
+if (r.exitCode !== 0) throw new Error(r.stdout);
+console.log(r.stdout);
+```
+
+## Tests / Typecheck
+
+From the `mu/` repo root:
+
+```bash
+bun test packages/cli
+bun run typecheck
+```
+
+## Runtime
+
+- **Node-only** (ESM).
+- Reads/writes a `.mu/` store at the git repo root (use `mu init` to create it).

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from "./index.js";
+const result = await run(process.argv.slice(2));
+if (result.stdout.length > 0) {
+    process.stdout.write(result.stdout);
+}
+if (result.stderr.length > 0) {
+    process.stderr.write(result.stderr);
+}
+process.exitCode = result.exitCode;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type RunResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
+export declare function run(argv: string[], opts?: {
+    cwd?: string;
+}): Promise<RunResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AA4PF,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAoCzF"}

package/dist/index.js

@@ -0,0 +1,1132 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { FsJsonlStore, fsEventLog, getStorePaths, newRunId, runContext } from "@femtomc/mu-core/node";
+import { ForumStore } from "@femtomc/mu-forum";
+import { IssueStore } from "@femtomc/mu-issue";
+import { DagRunner, extractDescription, splitFrontmatter } from "@femtomc/mu-orchestrator";
+import { DEFAULT_ORCHESTRATOR_MD, DEFAULT_REVIEWER_ROLE_MD, DEFAULT_WORKER_ROLE_MD } from "./templates.js";
+function ok(stdout = "", exitCode = 0) {
+    return { stdout, stderr: "", exitCode };
+}
+function jsonText(data, pretty) {
+    return `${JSON.stringify(data, null, pretty ? 2 : 0)}\n`;
+}
+function formatRecovery(recovery) {
+    if (!recovery || recovery.length === 0) {
+        return "";
+    }
+    return ` Recovery: ${recovery.join(" | ")}`;
+}
+function jsonError(msg, opts = {}) {
+    const pretty = opts.pretty ?? false;
+    return { stdout: jsonText({ error: `${msg}${formatRecovery(opts.recovery)}` }, pretty), stderr: "", exitCode: 1 };
+}
+function hasHelpFlag(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
+function popFlag(argv, name) {
+    let present = false;
+    const rest = [];
+    for (const a of argv) {
+        if (a === name) {
+            present = true;
+            continue;
+        }
+        rest.push(a);
+    }
+    return { present, rest };
+}
+function getFlagValue(argv, name) {
+    const rest = [];
+    let value = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === name) {
+            const next = argv[i + 1];
+            if (next == null) {
+                value = "";
+                i += 0;
+                continue;
+            }
+            value = next;
+            i += 1;
+            continue;
+        }
+        if (a.startsWith(`${name}=`)) {
+            value = a.slice(`${name}=`.length);
+            continue;
+        }
+        rest.push(a);
+    }
+    return { value, rest };
+}
+function getRepeatFlagValues(argv, names) {
+    const nameSet = new Set(names);
+    const values = [];
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (nameSet.has(a)) {
+            const next = argv[i + 1];
+            if (next != null) {
+                values.push(next);
+                i += 1;
+            }
+            continue;
+        }
+        let matched = false;
+        for (const name of names) {
+            if (a.startsWith(`${name}=`)) {
+                values.push(a.slice(`${name}=`.length));
+                matched = true;
+                break;
+            }
+        }
+        if (matched) {
+            continue;
+        }
+        rest.push(a);
+    }
+    return { values, rest };
+}
+function ensureInt(value, opts) {
+    const n = Number.parseInt(value, 10);
+    if (!Number.isFinite(n)) {
+        return null;
+    }
+    if (opts.min != null && n < opts.min) {
+        return null;
+    }
+    if (opts.max != null && n > opts.max) {
+        return null;
+    }
+    return n;
+}
+async function ensureCtx(cwd) {
+    const repoRoot = findRepoRoot(cwd);
+    const paths = getStorePaths(repoRoot);
+    const events = fsEventLog(paths.eventsPath);
+    const store = new IssueStore(new FsJsonlStore(paths.issuesPath), { events });
+    const forum = new ForumStore(new FsJsonlStore(paths.forumPath), { events });
+    return { cwd, repoRoot, store, forum, events, paths };
+}
+function findRepoRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".git"))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return resolve(start);
+        }
+        current = parent;
+    }
+}
+async function listRolesJson(repoRoot) {
+    const rolesDir = join(repoRoot, ".mu", "roles");
+    let entries;
+    try {
+        entries = await readdir(rolesDir);
+    }
+    catch {
+        return [];
+    }
+    const mdFiles = entries.filter((e) => e.endsWith(".md")).sort();
+    const out = [];
+    for (const file of mdFiles) {
+        const abs = join(rolesDir, file);
+        const text = await readFile(abs, "utf8");
+        const { meta, body } = splitFrontmatter(text);
+        const { description, source } = extractDescription(meta, body);
+        const name = file.replace(/\.md$/, "");
+        const prompt_path = relative(repoRoot, abs).replaceAll("\\", "/");
+        out.push({
+            name,
+            prompt_path,
+            cli: typeof meta.cli === "string" ? meta.cli : "",
+            model: typeof meta.model === "string" ? meta.model : "",
+            reasoning: typeof meta.reasoning === "string" ? meta.reasoning : "",
+            description,
+            description_source: source,
+        });
+    }
+    return out;
+}
+function issueJson(issue) {
+    return {
+        id: issue.id,
+        title: issue.title,
+        body: issue.body ?? "",
+        status: issue.status,
+        outcome: issue.outcome ?? null,
+        tags: issue.tags ?? [],
+        deps: issue.deps ?? [],
+        execution_spec: issue.execution_spec ?? null,
+        priority: issue.priority ?? 3,
+        created_at: issue.created_at ?? 0,
+        updated_at: issue.updated_at ?? 0,
+    };
+}
+async function resolveIssueId(store, rawId) {
+    const direct = await store.get(rawId);
+    if (direct) {
+        return { issueId: direct.id, error: null };
+    }
+    const all = await store.list();
+    const matches = all.map((i) => i.id).filter((id) => id.startsWith(rawId));
+    if (matches.length === 0) {
+        return {
+            issueId: null,
+            error: `not found: ${rawId}` +
+                formatRecovery(["mu issues list --limit 20", "mu issues ready --root <root-id>", "mu status"]),
+        };
+    }
+    if (matches.length > 1) {
+        const sample = matches.slice(0, 5).join(",");
+        const suffix = matches.length > 5 ? "..." : "";
+        return {
+            issueId: null,
+            error: `ambiguous id prefix: ${rawId} (${sample}${suffix})` +
+                formatRecovery(["use a longer id prefix", "mu issues list --limit 20"]),
+        };
+    }
+    return { issueId: matches[0], error: null };
+}
+function mainHelp() {
+    return [
+        "mu - issue DAG + forum CLI",
+        "",
+        "Usage:",
+        "  mu <command> [args...]",
+        "",
+        "Commands:",
+        "  init [--force]                  Initialize .mu store + templates",
+        "  status [--json] [--pretty]      Show repo + DAG status",
+        "  roles [--json|--table]          List role templates",
+        "  issues <subcmd>                 Issue DAG commands (JSON)",
+        "  forum <subcmd>                  Forum commands (JSON)",
+        "  run <prompt...>                 Create root + run DAG loop",
+        "  resume <root-id>                Resume a DAG loop",
+        "  replay <id|path> [--backend pi] Replay a logged run (pi-only)",
+        "",
+        "Run `mu <command> --help` for details.",
+    ].join("\n");
+}
+export async function run(argv, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        return ok(`${mainHelp()}\n`);
+    }
+    if (argv.includes("--version")) {
+        return ok("mu 0.0.0\n");
+    }
+    const cmd = argv[0];
+    const rest = argv.slice(1);
+    const ctx = await ensureCtx(cwd);
+    switch (cmd) {
+        case "init":
+            return await cmdInit(rest, ctx);
+        case "status":
+            return await cmdStatus(rest, ctx);
+        case "roles":
+            return await cmdRoles(rest, ctx);
+        case "issues":
+            return await cmdIssues(rest, ctx);
+        case "forum":
+            return await cmdForum(rest, ctx);
+        case "run":
+            return await cmdRun(rest, ctx);
+        case "resume":
+            return await cmdResume(rest, ctx);
+        case "replay":
+            return await cmdReplay(rest, ctx);
+        default:
+            return jsonError(`unknown command: ${cmd}`, {
+                recovery: ["mu --help"],
+            });
+    }
+}
+async function cmdInit(argv, ctx) {
+    if (hasHelpFlag(argv)) {
+        return ok(["mu init - initialize .mu state, templates, and logs", "", "Usage:", "  mu init [--force]"].join("\n") + "\n");
+    }
+    const { present: force, rest } = popFlag(argv, "--force");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { recovery: ["mu init --help"] });
+    }
+    await mkdir(ctx.paths.storeDir, { recursive: true });
+    await writeFile(ctx.paths.issuesPath, "", { encoding: "utf8", flag: "a" });
+    await writeFile(ctx.paths.forumPath, "", { encoding: "utf8", flag: "a" });
+    await writeFile(ctx.paths.eventsPath, "", { encoding: "utf8", flag: "a" });
+    await mkdir(ctx.paths.logsDir, { recursive: true });
+    if (force || !existsSync(ctx.paths.orchestratorPath)) {
+        await writeFile(ctx.paths.orchestratorPath, DEFAULT_ORCHESTRATOR_MD, "utf8");
+    }
+    const rolesDir = ctx.paths.rolesDir;
+    await mkdir(rolesDir, { recursive: true });
+    const workerPath = join(rolesDir, "worker.md");
+    if (force || !existsSync(workerPath)) {
+        await writeFile(workerPath, DEFAULT_WORKER_ROLE_MD, "utf8");
+    }
+    const reviewerPath = join(rolesDir, "reviewer.md");
+    if (force || !existsSync(reviewerPath)) {
+        await writeFile(reviewerPath, DEFAULT_REVIEWER_ROLE_MD, "utf8");
+    }
+    const verb = force ? "Reinitialized" : "Initialized";
+    return ok(`${verb} .mu/ in ${ctx.repoRoot}\n`);
+}
+async function cmdStatus(argv, ctx) {
+    if (hasHelpFlag(argv)) {
+        return ok(["mu status - show repo + DAG status", "", "Usage:", "  mu status [--json] [--pretty]"].join("\n") + "\n");
+    }
+    const { present: pretty, rest: argv0 } = popFlag(argv, "--pretty");
+    const { present: jsonMode, rest } = popFlag(argv0, "--json");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { recovery: ["mu status --help"] });
+    }
+    const roots = (await ctx.store.list({ tag: "node:root" })).map(issueJson);
+    const openIssues = await ctx.store.list({ status: "open" });
+    const ready = await ctx.store.ready(null, { tags: ["node:agent"] });
+    const topics = await ctx.forum.topics("issue:");
+    const roles = await listRolesJson(ctx.repoRoot);
+    const payload = {
+        repo_root: ctx.repoRoot,
+        roots,
+        open_count: openIssues.length,
+        ready_count: ready.length,
+        ready: ready.slice(0, 10).map(issueJson),
+        recent_topics: topics.slice(0, 10),
+        roles,
+    };
+    if (jsonMode) {
+        return ok(jsonText(payload, pretty));
+    }
+    let out = `Repo: ${ctx.repoRoot}\n`;
+    out += `Root issues: ${roots.length}\n`;
+    out += `Open issues: ${openIssues.length}\n`;
+    out += `Ready issues: ${ready.length}\n`;
+    out += `Roles: ${roles.length}\n`;
+    if (ready.length > 0) {
+        out += "\nReady:\n";
+        for (const issue of ready.slice(0, 10)) {
+            out += `  ${issue.id} [p=${issue.priority ?? 3}] ${String(issue.title ?? "").slice(0, 80)}\n`;
+        }
+    }
+    if (topics.length > 0) {
+        out += "\nRecent issue topics:\n";
+        for (const topic of topics.slice(0, 10)) {
+            out += `  ${topic.topic} (${topic.messages}) last_at=${topic.last_at}\n`;
+        }
+    }
+    return ok(out);
+}
+async function cmdRoles(argv, ctx) {
+    if (hasHelpFlag(argv)) {
+        return ok([
+            "mu roles - list role templates from .mu/roles/*.md",
+            "",
+            "Usage:",
+            "  mu roles [--json] [--table] [--pretty]",
+            "",
+            "Defaults to JSON output for automation.",
+        ].join("\n") + "\n");
+    }
+    const { present: pretty, rest: argv0 } = popFlag(argv, "--pretty");
+    const { present: tableMode, rest: argv1 } = popFlag(argv0, "--table");
+    const { present: jsonFlag, rest } = popFlag(argv1, "--json");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { recovery: ["mu roles --help"] });
+    }
+    const jsonMode = jsonFlag || !tableMode;
+    const roles = await listRolesJson(ctx.repoRoot);
+    if (jsonMode) {
+        return ok(jsonText(roles, pretty));
+    }
+    // Simple ASCII table.
+    const lines = [];
+    lines.push("Name\tCLI\tModel\tReasoning\tPrompt");
+    for (const role of roles) {
+        lines.push([role.name, role.cli || "-", role.model || "-", role.reasoning || "-", role.prompt_path || "-"].join("\t"));
+    }
+    return ok(`${lines.join("\n")}\n`);
+}
+async function cmdIssues(argv, ctx) {
+    const { present: pretty, rest: argv0 } = popFlag(argv, "--pretty");
+    if (argv0.length === 0 || hasHelpFlag(argv0)) {
+        return ok([
+            "mu issues - issue DAG commands (JSON)",
+            "",
+            "Usage:",
+            "  mu issues <command> [args...] [--pretty]",
+            "",
+            "Commands:",
+            "  list/get/create/update/claim/open/close/dep/undep/children/ready/validate",
+        ].join("\n") + "\n");
+    }
+    const sub = argv0[0];
+    const rest = argv0.slice(1);
+    switch (sub) {
+        case "list":
+            return await issuesList(rest, ctx, pretty);
+        case "get":
+            return await issuesGet(rest, ctx, pretty);
+        case "create":
+            return await issuesCreate(rest, ctx, pretty);
+        case "update":
+            return await issuesUpdate(rest, ctx, pretty);
+        case "claim":
+            return await issuesClaim(rest, ctx, pretty);
+        case "open":
+            return await issuesOpen(rest, ctx, pretty);
+        case "close":
+            return await issuesClose(rest, ctx, pretty);
+        case "dep":
+            return await issuesDep(rest, ctx, pretty);
+        case "undep":
+            return await issuesUndep(rest, ctx, pretty);
+        case "children":
+            return await issuesChildren(rest, ctx, pretty);
+        case "ready":
+            return await issuesReady(rest, ctx, pretty);
+        case "validate":
+            return await issuesValidate(rest, ctx, pretty);
+        default:
+            return jsonError(`unknown subcommand: ${sub}`, { pretty, recovery: ["mu issues --help"] });
+    }
+}
+async function issuesList(argv, ctx, pretty) {
+    if (hasHelpFlag(argv)) {
+        return ok([
+            "mu issues list - list issues with optional filters",
+            "",
+            "Usage:",
+            "  mu issues list [--status STATUS] [--tag TAG] [--root ID] [--limit N] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const { value: statusRaw, rest: argv0 } = getFlagValue(argv, "--status");
+    const { values: tags, rest: argv1 } = getRepeatFlagValues(argv0, ["--tag"]);
+    const { value: rootRaw, rest: argv2 } = getFlagValue(argv1, "--root");
+    const { value: limitRaw, rest } = getFlagValue(argv2, "--limit");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu issues list --help"] });
+    }
+    const status = statusRaw && statusRaw.length > 0 ? statusRaw : null;
+    if (status != null && status !== "open" && status !== "in_progress" && status !== "closed") {
+        return jsonError(`invalid status: ${status}`, { pretty, recovery: ["mu issues list --help"] });
+    }
+    let issues = await ctx.store.list({ status: status ?? undefined });
+    if (tags.length > 0) {
+        issues = issues.filter((i) => tags.every((t) => i.tags.includes(t)));
+    }
+    if (rootRaw) {
+        const resolved = await resolveIssueId(ctx.store, rootRaw);
+        if (resolved.error) {
+            return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+        }
+        const subtree = new Set(await ctx.store.subtree_ids(resolved.issueId));
+        issues = issues.filter((i) => subtree.has(i.id));
+    }
+    let limit = 0;
+    if (limitRaw) {
+        const parsed = ensureInt(limitRaw, { name: "--limit", min: 0 });
+        if (parsed == null) {
+            return jsonError("limit must be an integer >= 0", { pretty, recovery: ["mu issues list --limit 20"] });
+        }
+        limit = parsed;
+    }
+    if (limit > 0) {
+        issues = issues.slice(-limit);
+    }
+    return ok(jsonText(issues.map(issueJson), pretty));
+}
+async function issuesGet(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok(["mu issues get - fetch a single issue", "", "Usage:", "  mu issues get <id-or-prefix> [--pretty]"].join("\n") + "\n");
+    }
+    const resolved = await resolveIssueId(ctx.store, argv[0]);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const issue = await ctx.store.get(resolved.issueId);
+    if (!issue) {
+        return jsonError(`not found: ${argv[0]}`, { pretty, recovery: ["mu issues list --limit 20"] });
+    }
+    return ok(jsonText(issueJson(issue), pretty));
+}
+function buildExecutionSpec(fields) {
+    const spec = {};
+    if (fields.role)
+        spec.role = fields.role;
+    if (fields.cli)
+        spec.cli = fields.cli;
+    if (fields.model)
+        spec.model = fields.model;
+    if (fields.reasoning)
+        spec.reasoning = fields.reasoning;
+    if (fields.prompt_path)
+        spec.prompt_path = fields.prompt_path;
+    return Object.keys(spec).length > 0 ? spec : null;
+}
+async function issuesCreate(argv, ctx, pretty) {
+    if (hasHelpFlag(argv)) {
+        return ok([
+            "mu issues create - create a new issue (adds node:agent tag automatically)",
+            "",
+            "Usage:",
+            "  mu issues create <title> [--body TEXT] [--parent ID] [--tag TAG] [--role ROLE] [--cli NAME] [--model NAME] [--reasoning LEVEL] [--prompt-path PATH] [--priority N] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const title = argv[0];
+    if (!title || title.startsWith("-")) {
+        return jsonError("missing title", {
+            pretty,
+            recovery: ['mu issues create "Title" --body "Details"'],
+        });
+    }
+    const { value: body, rest: argv0 } = getFlagValue(argv.slice(1), "--body");
+    const { value: bodyShort, rest: argv1 } = getFlagValue(argv0, "-b");
+    const resolvedBody = body ?? bodyShort ?? "";
+    const { value: parentRaw, rest: argv2 } = getFlagValue(argv1, "--parent");
+    const { values: tags0, rest: argv3 } = getRepeatFlagValues(argv2, ["--tag", "-t"]);
+    const { value: role, rest: argv4 } = getFlagValue(argv3, "--role");
+    const { value: roleShort, rest: argv5 } = getFlagValue(argv4, "-r");
+    const { value: cli, rest: argv6 } = getFlagValue(argv5, "--cli");
+    const { value: model, rest: argv7 } = getFlagValue(argv6, "--model");
+    const { value: reasoning, rest: argv8 } = getFlagValue(argv7, "--reasoning");
+    const { value: promptPath, rest: argv9 } = getFlagValue(argv8, "--prompt-path");
+    const { value: priorityRaw, rest } = getFlagValue(argv9, "--priority");
+    const { value: priorityShortRaw, rest: rest2 } = getFlagValue(rest, "-p");
+    const restFinal = rest2;
+    const priorityValue = priorityRaw ?? priorityShortRaw ?? "3";
+    if (restFinal.length > 0) {
+        return jsonError(`unknown args: ${restFinal.join(" ")}`, { pretty, recovery: ["mu issues create --help"] });
+    }
+    const priority = ensureInt(priorityValue, { name: "--priority", min: 1, max: 5 });
+    if (priority == null) {
+        return jsonError("priority must be in range 1-5", {
+            pretty,
+            recovery: ['mu issues create "Title" --priority 2'],
+        });
+    }
+    const tags = [...new Set(tags0)];
+    if (!tags.includes("node:agent")) {
+        tags.push("node:agent");
+    }
+    const execution_spec = buildExecutionSpec({
+        role: role ?? roleShort ?? null,
+        cli: cli ?? null,
+        model: model ?? null,
+        reasoning: reasoning ?? null,
+        prompt_path: promptPath ?? null,
+    });
+    let parentId = null;
+    if (parentRaw) {
+        const resolved = await resolveIssueId(ctx.store, parentRaw);
+        if (resolved.error) {
+            return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+        }
+        parentId = resolved.issueId;
+    }
+    let issue = await ctx.store.create(title, {
+        body: resolvedBody,
+        tags,
+        execution_spec,
+        priority,
+    });
+    if (parentId) {
+        await ctx.store.add_dep(issue.id, "parent", parentId);
+        issue = (await ctx.store.get(issue.id)) ?? issue;
+    }
+    return ok(jsonText(issueJson(issue), pretty));
+}
+async function issuesUpdate(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues update - patch fields and routing metadata",
+            "",
+            "Usage:",
+            "  mu issues update <id-or-prefix> [--title TEXT] [--body TEXT] [--status STATUS] [--outcome OUTCOME] [--priority N] [--add-tag TAG] [--remove-tag TAG] [--role ROLE] [--cli NAME] [--model NAME] [--reasoning LEVEL] [--prompt-path PATH] [--clear-execution-spec] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const rawId = argv[0];
+    const resolvedId = await resolveIssueId(ctx.store, rawId);
+    if (resolvedId.error) {
+        return { stdout: jsonText({ error: resolvedId.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const issueId = resolvedId.issueId;
+    const issue = await ctx.store.get(issueId);
+    if (!issue) {
+        return jsonError(`not found: ${rawId}`, { pretty, recovery: ["mu issues list --limit 20"] });
+    }
+    const argvRest = argv.slice(1);
+    const { value: title, rest: argv0 } = getFlagValue(argvRest, "--title");
+    const { value: body, rest: argv1 } = getFlagValue(argv0, "--body");
+    const { value: status, rest: argv2 } = getFlagValue(argv1, "--status");
+    const { value: outcome, rest: argv3 } = getFlagValue(argv2, "--outcome");
+    const { value: priorityRaw, rest: argv4 } = getFlagValue(argv3, "--priority");
+    const { values: addTags, rest: argv5 } = getRepeatFlagValues(argv4, ["--add-tag"]);
+    const { values: removeTags, rest: argv6 } = getRepeatFlagValues(argv5, ["--remove-tag"]);
+    const { value: role, rest: argv7 } = getFlagValue(argv6, "--role");
+    const { value: cli, rest: argv8 } = getFlagValue(argv7, "--cli");
+    const { value: model, rest: argv9 } = getFlagValue(argv8, "--model");
+    const { value: reasoning, rest: argv10 } = getFlagValue(argv9, "--reasoning");
+    const { value: promptPath, rest: argv11 } = getFlagValue(argv10, "--prompt-path");
+    const { present: clearExecutionSpec, rest } = popFlag(argv11, "--clear-execution-spec");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu issues update --help"] });
+    }
+    if (priorityRaw != null) {
+        const pr = ensureInt(priorityRaw, { name: "--priority", min: 1, max: 5 });
+        if (pr == null) {
+            return jsonError("priority must be in range 1-5", {
+                pretty,
+                recovery: [`mu issues update ${issueId} --priority 2`],
+            });
+        }
+    }
+    const fields = {};
+    if (title != null)
+        fields.title = title;
+    if (body != null)
+        fields.body = body;
+    if (status != null)
+        fields.status = status;
+    if (outcome != null)
+        fields.outcome = outcome;
+    if (priorityRaw != null)
+        fields.priority = Number.parseInt(priorityRaw, 10);
+    if (addTags.length > 0 || removeTags.length > 0) {
+        let tags = [...(issue.tags ?? [])];
+        for (const tag of addTags) {
+            if (!tags.includes(tag)) {
+                tags.push(tag);
+            }
+        }
+        if (removeTags.length > 0) {
+            tags = tags.filter((t) => !removeTags.includes(t));
+        }
+        fields.tags = tags;
+    }
+    const routingTouched = [role, cli, model, reasoning, promptPath].some((v) => v != null);
+    if (clearExecutionSpec) {
+        fields.execution_spec = null;
+    }
+    else if (routingTouched) {
+        const spec = { ...(issue.execution_spec ?? {}) };
+        if (role != null)
+            spec.role = role;
+        if (cli != null)
+            spec.cli = cli;
+        if (model != null)
+            spec.model = model;
+        if (reasoning != null)
+            spec.reasoning = reasoning;
+        if (promptPath != null)
+            spec.prompt_path = promptPath;
+        fields.execution_spec = Object.keys(spec).length > 0 ? spec : null;
+    }
+    if (Object.keys(fields).length === 0) {
+        return jsonError("no fields to update", {
+            pretty,
+            recovery: [`mu issues update ${issueId} --status in_progress`],
+        });
+    }
+    const updated = await ctx.store.update(issueId, fields);
+    return ok(jsonText(issueJson(updated), pretty));
+}
+async function issuesClaim(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues claim - mark an open issue as in_progress",
+            "",
+            "Usage:",
+            "  mu issues claim <id-or-prefix> [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const resolved = await resolveIssueId(ctx.store, argv[0]);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const issue = await ctx.store.get(resolved.issueId);
+    if (!issue) {
+        return jsonError(`not found: ${argv[0]}`, { pretty, recovery: ["mu issues list --status open --limit 20"] });
+    }
+    if (issue.status !== "open") {
+        return jsonError(`cannot claim issue in status=${issue.status}`, {
+            pretty,
+            recovery: [`mu issues get ${issue.id}`, `mu issues update ${issue.id} --status open`],
+        });
+    }
+    await ctx.store.claim(issue.id);
+    const claimed = (await ctx.store.get(issue.id)) ?? issue;
+    return ok(jsonText(issueJson(claimed), pretty));
+}
+async function issuesOpen(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues open - reopen an issue and clear outcome",
+            "",
+            "Usage:",
+            "  mu issues open <id-or-prefix> [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const resolved = await resolveIssueId(ctx.store, argv[0]);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const issue = await ctx.store.get(resolved.issueId);
+    if (!issue) {
+        return jsonError(`not found: ${argv[0]}`, { pretty, recovery: ["mu issues list --limit 20"] });
+    }
+    const reopened = await ctx.store.update(issue.id, { status: "open", outcome: null });
+    return ok(jsonText(issueJson(reopened), pretty));
+}
+async function issuesClose(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues close - close an issue with an outcome",
+            "",
+            "Usage:",
+            "  mu issues close <id-or-prefix> [--outcome OUTCOME] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const issueRaw = argv[0];
+    const { value: outcome, rest } = getFlagValue(argv.slice(1), "--outcome");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu issues close --help"] });
+    }
+    const resolved = await resolveIssueId(ctx.store, issueRaw);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const closed = await ctx.store.close(resolved.issueId, outcome ?? "success");
+    return ok(jsonText(issueJson(closed), pretty));
+}
+async function issuesDep(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues dep - add dependency edge",
+            "",
+            "Usage:",
+            "  mu issues dep <src-id> <blocks|parent> <dst-id> [--pretty]",
+        ].join("\n") + "\n");
+    }
+    if (argv.length < 3) {
+        return jsonError("usage: mu issues dep <src> <type> <dst>", {
+            pretty,
+            recovery: ["mu issues dep <src-id> blocks <dst-id>"],
+        });
+    }
+    const [srcRaw, depType, dstRaw] = argv;
+    if (depType !== "blocks" && depType !== "parent") {
+        return jsonError(`invalid dep type: ${depType} (use 'blocks' or 'parent')`, {
+            pretty,
+            recovery: ["mu issues dep <src-id> blocks <dst-id>", "mu issues dep <child-id> parent <parent-id>"],
+        });
+    }
+    const src = await resolveIssueId(ctx.store, srcRaw);
+    if (src.error)
+        return { stdout: jsonText({ error: src.error }, pretty), stderr: "", exitCode: 1 };
+    const dst = await resolveIssueId(ctx.store, dstRaw);
+    if (dst.error)
+        return { stdout: jsonText({ error: dst.error }, pretty), stderr: "", exitCode: 1 };
+    if (src.issueId === dst.issueId) {
+        return jsonError("source and destination must be different", {
+            pretty,
+            recovery: ["mu issues dep <src-id> blocks <dst-id>"],
+        });
+    }
+    await ctx.store.add_dep(src.issueId, depType, dst.issueId);
+    return ok(jsonText({ ok: true, src: src.issueId, type: depType, dst: dst.issueId }, pretty));
+}
+async function issuesUndep(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues undep - remove dependency edge",
+            "",
+            "Usage:",
+            "  mu issues undep <src-id> <blocks|parent> <dst-id> [--pretty]",
+        ].join("\n") + "\n");
+    }
+    if (argv.length < 3) {
+        return jsonError("usage: mu issues undep <src> <type> <dst>", {
+            pretty,
+            recovery: ["mu issues undep <src-id> blocks <dst-id>"],
+        });
+    }
+    const [srcRaw, depType, dstRaw] = argv;
+    if (depType !== "blocks" && depType !== "parent") {
+        return jsonError(`invalid dep type: ${depType} (use 'blocks' or 'parent')`, {
+            pretty,
+            recovery: ["mu issues undep <src-id> blocks <dst-id>"],
+        });
+    }
+    const src = await resolveIssueId(ctx.store, srcRaw);
+    if (src.error)
+        return { stdout: jsonText({ error: src.error }, pretty), stderr: "", exitCode: 1 };
+    const dst = await resolveIssueId(ctx.store, dstRaw);
+    if (dst.error)
+        return { stdout: jsonText({ error: dst.error }, pretty), stderr: "", exitCode: 1 };
+    const removed = await ctx.store.remove_dep(src.issueId, depType, dst.issueId);
+    return ok(jsonText({ ok: removed, src: src.issueId, type: depType, dst: dst.issueId }, pretty));
+}
+async function issuesChildren(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues children - list direct child issues",
+            "",
+            "Usage:",
+            "  mu issues children <id-or-prefix> [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const resolved = await resolveIssueId(ctx.store, argv[0]);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const children = await ctx.store.children(resolved.issueId);
+    children.sort((a, b) => (a.priority ?? 3) - (b.priority ?? 3));
+    return ok(jsonText(children.map(issueJson), pretty));
+}
+async function issuesReady(argv, ctx, pretty) {
+    if (hasHelpFlag(argv)) {
+        return ok([
+            "mu issues ready - list open, unblocked, leaf issues tagged node:agent",
+            "",
+            "Usage:",
+            "  mu issues ready [--root ID] [--tag TAG] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const { value: rootRaw, rest: argv0 } = getFlagValue(argv, "--root");
+    const { values: extraTags, rest } = getRepeatFlagValues(argv0, ["--tag"]);
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu issues ready --help"] });
+    }
+    let rootId = null;
+    if (rootRaw) {
+        const resolved = await resolveIssueId(ctx.store, rootRaw);
+        if (resolved.error) {
+            return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+        }
+        rootId = resolved.issueId;
+    }
+    const tags = ["node:agent", ...extraTags];
+    const issues = await ctx.store.ready(rootId, { tags });
+    return ok(jsonText(issues.map(issueJson), pretty));
+}
+async function issuesValidate(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu issues validate - validate DAG completion state for a root",
+            "",
+            "Usage:",
+            "  mu issues validate <root-id-or-prefix> [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const resolved = await resolveIssueId(ctx.store, argv[0]);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, pretty), stderr: "", exitCode: 1 };
+    }
+    const v = await ctx.store.validate(resolved.issueId);
+    return ok(jsonText({ root_id: resolved.issueId, is_final: v.is_final, reason: v.reason }, pretty));
+}
+async function cmdForum(argv, ctx) {
+    const { present: pretty, rest: argv0 } = popFlag(argv, "--pretty");
+    if (argv0.length === 0 || hasHelpFlag(argv0)) {
+        return ok([
+            "mu forum - forum messages for coordination (JSON)",
+            "",
+            "Usage:",
+            "  mu forum <command> [args...] [--pretty]",
+            "",
+            "Commands:",
+            "  post/read/topics",
+        ].join("\n") + "\n");
+    }
+    const sub = argv0[0];
+    const rest = argv0.slice(1);
+    switch (sub) {
+        case "post":
+            return await forumPost(rest, ctx, pretty);
+        case "read":
+            return await forumRead(rest, ctx, pretty);
+        case "topics":
+            return await forumTopics(rest, ctx, pretty);
+        default:
+            return jsonError(`unknown subcommand: ${sub}`, { pretty, recovery: ["mu forum --help"] });
+    }
+}
+async function forumPost(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu forum post - post a message to a topic",
+            "",
+            "Usage:",
+            "  mu forum post <topic> -m <message> [--author NAME] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const topic = argv[0];
+    const { value: message, rest: argv0 } = getFlagValue(argv.slice(1), "--message");
+    const { value: messageShort, rest: argv1 } = getFlagValue(argv0, "-m");
+    const { value: author, rest } = getFlagValue(argv1, "--author");
+    const msgBody = message ?? messageShort;
+    if (!msgBody) {
+        return jsonError("missing message (-m/--message)", {
+            pretty,
+            recovery: [`mu forum post ${topic} -m "..." --author worker`],
+        });
+    }
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu forum post --help"] });
+    }
+    const msg = await ctx.forum.post(topic, msgBody, author ?? "system");
+    return ok(jsonText(msg, pretty));
+}
+async function forumRead(argv, ctx, pretty) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu forum read - read messages from a topic (chronological)",
+            "",
+            "Usage:",
+            "  mu forum read <topic> [--limit N] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const topic = argv[0];
+    const { value: limitRaw, rest } = getFlagValue(argv.slice(1), "--limit");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu forum read --help"] });
+    }
+    const limit = limitRaw ? ensureInt(limitRaw, { name: "--limit", min: 1 }) : 50;
+    if (limit == null) {
+        return jsonError("limit must be >= 1", { pretty, recovery: [`mu forum read ${topic} --limit 20`] });
+    }
+    const msgs = await ctx.forum.read(topic, limit);
+    return ok(jsonText(msgs, pretty));
+}
+async function forumTopics(argv, ctx, pretty) {
+    if (hasHelpFlag(argv)) {
+        return ok([
+            "mu forum topics - list active topics sorted by most recent message",
+            "",
+            "Usage:",
+            "  mu forum topics [--prefix PREFIX] [--limit N] [--pretty]",
+        ].join("\n") + "\n");
+    }
+    const { value: prefix, rest: argv0 } = getFlagValue(argv, "--prefix");
+    const { value: limitRaw, rest } = getFlagValue(argv0, "--limit");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { pretty, recovery: ["mu forum topics --help"] });
+    }
+    const limit = limitRaw ? ensureInt(limitRaw, { name: "--limit", min: 1 }) : 100;
+    if (limit == null) {
+        return jsonError("limit must be >= 1", { pretty, recovery: ["mu forum topics --limit 20"] });
+    }
+    let topics = await ctx.forum.topics(prefix ?? null);
+    if (limit > 0) {
+        topics = topics.slice(0, limit);
+    }
+    return ok(jsonText(topics, pretty));
+}
+async function cmdRun(argv, ctx) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu run - create a root issue and run the DAG loop",
+            "",
+            "Usage:",
+            "  mu run <prompt...> [--max-steps N] [--review|--no-review] [--json]",
+        ].join("\n") + "\n");
+    }
+    let maxSteps = 20;
+    let review = true;
+    let jsonMode = false;
+    const promptParts = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json") {
+            jsonMode = true;
+            continue;
+        }
+        if (a === "--review") {
+            review = true;
+            continue;
+        }
+        if (a === "--no-review") {
+            review = false;
+            continue;
+        }
+        if (a === "--max-steps") {
+            const next = argv[i + 1];
+            if (!next) {
+                return jsonError("missing value for --max-steps", { recovery: ['mu run --max-steps 20 "..."'] });
+            }
+            const n = ensureInt(next, { name: "--max-steps", min: 1 });
+            if (n == null) {
+                return jsonError("max-steps must be >= 1", { recovery: ['mu run --max-steps 20 "..."'] });
+            }
+            maxSteps = n;
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("--max-steps=")) {
+            const n = ensureInt(a.slice("--max-steps=".length), { name: "--max-steps", min: 1 });
+            if (n == null) {
+                return jsonError("max-steps must be >= 1", { recovery: ['mu run --max-steps 20 "..."'] });
+            }
+            maxSteps = n;
+            continue;
+        }
+        promptParts.push(a);
+    }
+    const promptText = promptParts.join(" ").trim();
+    if (!promptText) {
+        return jsonError("missing prompt", { recovery: ['mu run "Break down and execute this goal"'] });
+    }
+    const runId = newRunId();
+    const { rootIssue, result } = await runContext({ runId }, async () => {
+        const rootIssue = await ctx.store.create(promptText, { tags: ["node:agent", "node:root"] });
+        const runner = new DagRunner(ctx.store, ctx.forum, ctx.repoRoot);
+        const result = await runner.run(rootIssue.id, maxSteps, { review });
+        return { rootIssue, result };
+    });
+    if (jsonMode) {
+        return {
+            stdout: jsonText({ status: result.status, steps: result.steps, error: result.error, root_id: rootIssue.id }, true),
+            stderr: "",
+            exitCode: result.status === "root_final" ? 0 : 1,
+        };
+    }
+    let out = `Root: ${rootIssue.id} ${String(rootIssue.title ?? "").slice(0, 80)}\n`;
+    out += `Runner status: ${result.status}\n`;
+    if (result.error) {
+        out += `Error: ${result.error}\n`;
+    }
+    return { stdout: out, stderr: "", exitCode: result.status === "root_final" ? 0 : 1 };
+}
+async function cmdResume(argv, ctx) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok([
+            "mu resume - resume an interrupted DAG loop",
+            "",
+            "Usage:",
+            "  mu resume <root-id> [--max-steps N] [--review|--no-review] [--json]",
+        ].join("\n") + "\n");
+    }
+    const rawId = argv[0];
+    let maxSteps = 20;
+    let review = true;
+    let jsonMode = false;
+    const rest = argv.slice(1);
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--json") {
+            jsonMode = true;
+            continue;
+        }
+        if (a === "--review") {
+            review = true;
+            continue;
+        }
+        if (a === "--no-review") {
+            review = false;
+            continue;
+        }
+        if (a === "--max-steps") {
+            const next = rest[i + 1];
+            if (!next) {
+                return jsonError("missing value for --max-steps", { recovery: [`mu resume ${rawId} --max-steps 20`] });
+            }
+            const n = ensureInt(next, { name: "--max-steps", min: 1 });
+            if (n == null) {
+                return jsonError("max-steps must be >= 1", { recovery: [`mu resume ${rawId} --max-steps 20`] });
+            }
+            maxSteps = n;
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("--max-steps=")) {
+            const n = ensureInt(a.slice("--max-steps=".length), { name: "--max-steps", min: 1 });
+            if (n == null) {
+                return jsonError("max-steps must be >= 1", { recovery: [`mu resume ${rawId} --max-steps 20`] });
+            }
+            maxSteps = n;
+            continue;
+        }
+        return jsonError(`unknown arg: ${a}`, { recovery: ["mu resume --help"] });
+    }
+    const resolved = await resolveIssueId(ctx.store, rawId);
+    if (resolved.error) {
+        return { stdout: jsonText({ error: resolved.error }, false), stderr: "", exitCode: 1 };
+    }
+    const rootId = resolved.issueId;
+    const reset = await ctx.store.reset_in_progress(rootId);
+    const runId = newRunId();
+    const result = await runContext({ runId }, async () => {
+        const runner = new DagRunner(ctx.store, ctx.forum, ctx.repoRoot);
+        return await runner.run(rootId, maxSteps, { review });
+    });
+    if (jsonMode) {
+        return {
+            stdout: jsonText({ status: result.status, steps: result.steps, error: result.error, root_id: rootId }, true),
+            stderr: "",
+            exitCode: result.status === "root_final" ? 0 : 1,
+        };
+    }
+    let out = "";
+    if (reset.length > 0) {
+        out += `Reset ${reset.length} stale issue(s) to open: ${reset.join(", ")}\n`;
+    }
+    out += `Resuming ${rootId}\n`;
+    out += `Runner status: ${result.status}\n`;
+    if (result.error) {
+        out += `Error: ${result.error}\n`;
+    }
+    return { stdout: out, stderr: "", exitCode: result.status === "root_final" ? 0 : 1 };
+}
+async function cmdReplay(argv, ctx) {
+    if (argv.length === 0 || hasHelpFlag(argv)) {
+        return ok(["mu replay - replay a logged run (pi-only)", "", "Usage:", "  mu replay <issue-id|path> [--backend pi]"].join("\n") + "\n");
+    }
+    const target = argv[0];
+    const { value: backend, rest } = getFlagValue(argv.slice(1), "--backend");
+    if (rest.length > 0) {
+        return jsonError(`unknown args: ${rest.join(" ")}`, { recovery: ["mu replay --help"] });
+    }
+    if (backend && backend !== "pi") {
+        return jsonError(`unsupported backend: ${backend} (only pi is supported)`, {
+            recovery: ["mu replay --backend pi <id>"],
+        });
+    }
+    const logsDir = ctx.paths.logsDir;
+    let path = resolve(ctx.cwd, target);
+    if (!existsSync(path)) {
+        const candidate = join(logsDir, `${target}.jsonl`);
+        if (existsSync(candidate)) {
+            path = candidate;
+        }
+        else {
+            // Prefix match: <target>*.jsonl
+            let entries;
+            try {
+                entries = await readdir(logsDir);
+            }
+            catch {
+                entries = [];
+            }
+            const matches = entries.filter((e) => e.startsWith(target) && e.endsWith(".jsonl"));
+            if (matches.length === 1) {
+                path = join(logsDir, matches[0]);
+            }
+            else if (matches.length > 1) {
+                return jsonError(`ambiguous prefix '${target}'`, {
+                    recovery: matches.slice(0, 10).map((m) => `mu replay ${m.replace(/\\.jsonl$/, "")}`),
+                });
+            }
+            else {
+                return jsonError(`log not found: ${target}`, { recovery: ["mu status", "ls .mu/logs"] });
+            }
+        }
+    }
+    const text = await readFile(path, "utf8");
+    return ok(text.length > 0 && !text.endsWith("\n") ? `${text}\n` : text);
+}

package/dist/templates.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_ORCHESTRATOR_MD: string;
+export declare const DEFAULT_WORKER_ROLE_MD: string;
+export declare const DEFAULT_REVIEWER_ROLE_MD: string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,QAqDzB,CAAC;AAEZ,eAAO,MAAM,sBAAsB,QA2BxB,CAAC;AAEZ,eAAO,MAAM,wBAAwB,QAqC4B,CAAC"}

package/dist/templates.js

@@ -0,0 +1,117 @@
+export const DEFAULT_ORCHESTRATOR_MD = `---\n` +
+    `description: Plan and decompose root goals into atomic issues, assign roles, and manage dependency order.\n` +
+    `cli: pi\n` +
+    `model: gpt-5.3-codex\n` +
+    `reasoning: xhigh\n` +
+    `---\n` +
+    `\n` +
+    `You are the hierarchical orchestrator for the issue DAG.\n` +
+    `\n` +
+    `Assigned issue: \`{{ISSUE_ID}}\`\n` +
+    `\n` +
+    `## Issue Prompt\n` +
+    `\n` +
+    `{{PROMPT}}\n` +
+    `\n` +
+    `## Available Roles\n` +
+    `\n` +
+    `{{ROLES}}\n` +
+    `\n` +
+    `## Responsibilities\n` +
+    `\n` +
+    `You are a planner. You MUST NOT execute work directly (no file edits, no code changes, no git commits).\n` +
+    `Your only job is to decompose issues into children and close the parent with \`outcome=expanded\`.\n` +
+    `\n` +
+    `1. Investigate the assigned issue and its history (issue + forum + children).\n` +
+    `2. Decompose into child issues and close with \`outcome=expanded\`.\n` +
+    `3. Assign a role to each child via \`execution_spec.role\`.\n` +
+    `4. Use \`blocks\` dependencies for sequential ordering.\n` +
+    `5. Keep decomposition deterministic and minimal.\n` +
+    `\n` +
+    `The ONLY valid outcome for you is \`expanded\`. Never close with \`success\`, \`failure\`, or \`needs_work\`.\n` +
+    `\n` +
+    `## CLI Quick Reference\n` +
+    `\n` +
+    `\`\`\`bash\n` +
+    `# Inspect graph state\n` +
+    `mu issues get <id>\n` +
+    `mu issues list --root <root-id>\n` +
+    `mu issues children <id>\n` +
+    `mu issues ready --root <root-id>\n` +
+    `mu issues validate <root-id>\n` +
+    `mu roles --pretty\n` +
+    `\n` +
+    `# Decompose work\n` +
+    `mu issues create "Title" --body "Details" --parent <id> --role worker --priority 2\n` +
+    `mu issues dep <src-id> blocks <dst-id>\n` +
+    `mu issues update <id> --role worker\n` +
+    `mu issues close <id> --outcome expanded\n` +
+    `\n` +
+    `# Collaborate\n` +
+    `mu forum post issue:<id> -m "notes" --author orchestrator\n` +
+    `mu forum read issue:<id> --limit 20\n` +
+    `\`\`\`\n`;
+export const DEFAULT_WORKER_ROLE_MD = `---\n` +
+    `description: Best for concrete execution tasks; implement exactly one atomic issue (code/tests/docs), verify results, then close with a terminal outcome.\n` +
+    `cli: pi\n` +
+    `model: gpt-5.3-codex\n` +
+    `reasoning: xhigh\n` +
+    `---\n` +
+    `\n` +
+    `You are a worker role executing one atomic issue.\n` +
+    `\n` +
+    `User prompt:\n` +
+    `\n` +
+    `{{PROMPT}}\n` +
+    `\n` +
+    `## Responsibilities\n` +
+    `\n` +
+    `1. Execute exactly one selected atomic issue end-to-end.\n` +
+    `2. Keep scope tight to the selected issue.\n` +
+    `3. Close with a terminal outcome: success, failure, or skipped.\n` +
+    `\n` +
+    `## CLI Quick Reference\n` +
+    `\n` +
+    `\`\`\`bash\n` +
+    `mu issues get <id>\n` +
+    `mu issues update <id> --status in_progress\n` +
+    `mu forum post issue:<id> -m "status update" --author worker\n` +
+    `mu issues close <id> --outcome success\n` +
+    `\`\`\`\n`;
+export const DEFAULT_REVIEWER_ROLE_MD = `---\n` +
+    `description: Independently verify completed work and either approve or mark the issue as needs_work.\n` +
+    `cli: pi\n` +
+    `model: gpt-5.3-codex\n` +
+    `reasoning: xhigh\n` +
+    `---\n` +
+    `\n` +
+    `You are a code reviewer evaluating whether a completed issue was properly implemented.\n` +
+    `\n` +
+    `## Issue Under Review\n` +
+    `\n` +
+    `{{PROMPT}}\n` +
+    `\n` +
+    `## Evaluation Criteria\n` +
+    `\n` +
+    `1. **Completeness**: Does the implementation fully address the issue?\n` +
+    `2. **Correctness**: Is the code logically sound? Do tests pass?\n` +
+    `3. **Quality**: Does the code follow existing patterns?\n` +
+    `\n` +
+    `## Actions\n` +
+    `\n` +
+    `### If the work is correct and complete:\n` +
+    `Do nothing. The issue stays closed with outcome=success.\n` +
+    `\n` +
+    `### If the work needs targeted fixes:\n` +
+    `1. Post a concrete explanation of what's wrong and what must change:\n` +
+    `   \`mu forum post issue:{{ISSUE_ID}} -m "<what failed + acceptance criteria>" --author reviewer\`\n` +
+    `2. Mark the issue as needing work:\n` +
+    `   \`mu issues update {{ISSUE_ID}} --outcome needs_work\`\n` +
+    `\n` +
+    `The orchestrator will re-expand the issue into remediation children.\n` +
+    `\n` +
+    `## Rules\n` +
+    `\n` +
+    `- DO NOT create children for style nitpicks.\n` +
+    `- DO NOT modify code yourself. Evaluation only.\n` +
+    `- DO NOT create new issues. Mark needs_work and explain why.\n`;

package/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@femtomc/mu",
+	"version": "0.1.0",
+	"type": "module",
+	"bin": {
+		"mu": "./dist/cli.js"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": ["dist/**"],
+	"dependencies": {
+		"@femtomc/mu-core": "0.1.0",
+		"@femtomc/mu-forum": "0.1.0",
+		"@femtomc/mu-issue": "0.1.0",
+		"@femtomc/mu-orchestrator": "0.1.0"
+	}
+}