maqcli 0.2.0

package/dist/index.js

@@ -0,0 +1,1032 @@
+#!/usr/bin/env node
+/**
+ * maqcli entry point.
+ *
+ * MAQ master orchestrator: a token-efficient, agent-agnostic supervisor that
+ * sits on top of any worker CLI (AI or not) via a Scout -> Plan -> Execute ->
+ * Verify pipeline. Zero runtime dependencies; uses only Node built-ins.
+ *
+ * Commands: detect | config | scout | plan | run | verify | help | version
+ */
+import { parseArgs } from "node:util";
+import { logger } from "./core/logger.js";
+import { detectAgents, resolveTarget } from "./core/registry.js";
+import { loadConfig, saveConfig, setConfigKey, configPath } from "./core/config-store.js";
+import { runScout } from "./phases/scout.js";
+import { getProvider } from "./core/model.js";
+import { runPlan } from "./phases/plan.js";
+import { detectTestCommand, runVerify } from "./phases/verify.js";
+import { runPipeline } from "./core/pipeline.js";
+import { createDaemon } from "./server/daemon.js";
+import { RelayBridge } from "./server/relay-bridge.js";
+import { probeConnectivity } from "./core/probe.js";
+import { priceFor } from "./core/cost.js";
+import { SkillsManager, initSkills } from "./core/skills.js";
+import { runSubagent } from "./core/subagent.js";
+import { createToolRegistry } from "./core/tools.js";
+import { Router } from "./core/router.js";
+import { masterOptions, cheapestMaster } from "./core/catalog.js";
+import { verifyAuditLog } from "./core/audit.js";
+import { ProfileManager } from "./core/profiles.js";
+import { RecallMemory } from "./core/recall.js";
+import { runSwarm } from "./core/supervisor.js";
+import { SessionRegistry } from "./core/session.js";
+import { InteractiveWorker } from "./core/interactive.js";
+import { loadFlows, addFlow, removeFlow, scheduleMs, Scheduler } from "./core/flows.js";
+import { attachWebhook } from "./core/plugins.js";
+import { agentSpec } from "./core/registry.js";
+import { authAdvisory } from "./core/registry.js";
+import { Board } from "./core/board.js";
+import { getTopic, listTopics, renderTopic } from "./core/help-topics.js";
+import { generateCompletion, detectShell } from "./core/completion.js";
+import { runInit } from "./core/init-wizard.js";
+import { CostTracker } from "./core/cost-tracker.js";
+const VERSION = "0.2.0";
+async function main(argv) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case undefined:
+        case "-h":
+        case "--help":
+            printHelp();
+            return 0;
+        case "help":
+            return cmdHelp(rest);
+        case "version":
+        case "-v":
+        case "--version":
+            logger.out(VERSION);
+            return 0;
+        case "detect":
+            return cmdDetect(rest);
+        case "config":
+            return cmdConfig(rest);
+        case "scout":
+            return cmdScout(rest);
+        case "plan":
+            return cmdPlan(rest);
+        case "run":
+            return cmdRun(rest);
+        case "verify":
+            return cmdVerify(rest);
+        case "serve":
+            return cmdServe(rest);
+        case "sessions":
+            return cmdSessions(rest);
+        case "models":
+            return cmdModels(rest);
+        case "probe":
+            return cmdProbe(rest);
+        case "skills":
+            return cmdSkills(rest);
+        case "subagent":
+            return cmdSubagent(rest);
+        case "tools":
+            return cmdTools(rest);
+        case "doctor":
+            return cmdDoctor(rest);
+        case "audit":
+            return cmdAudit(rest);
+        case "agents":
+            return cmdAgents(rest);
+        case "memory":
+            return cmdMemory(rest);
+        case "swarm":
+            return cmdSwarm(rest);
+        case "interactive":
+            return cmdInteractive(rest);
+        case "flow":
+            return cmdFlow(rest);
+        case "board":
+            return cmdBoard(rest);
+        case "init":
+            return cmdInit(rest);
+        case "logs":
+            return cmdLogs(rest);
+        case "stop":
+            return cmdStop(rest);
+        case "cost":
+            return cmdCost(rest);
+        case "completion":
+            return cmdCompletion(rest);
+        default:
+            logger.error(`unknown command: ${command}`);
+            printHelp();
+            return 1;
+    }
+}
+function commonFlags() {
+    return {
+        json: { type: "boolean", default: false },
+        cwd: { type: "string" },
+    };
+}
+function cmdDetect(args) {
+    const { values } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const agents = detectAgents();
+    if (values.json) {
+        logger.out(JSON.stringify(agents, null, 2));
+        return 0;
+    }
+    logger.out("Detected worker CLIs:");
+    for (const a of agents) {
+        const status = a.installed
+            ? `installed${a.authenticated ? ", authenticated" : ""}${a.stableJsonStream ? ", json-stream" : ""}`
+            : "not found";
+        logger.out(`  ${a.name.padEnd(14)} ${status}${a.binPath ? "  (" + a.binPath + ")" : ""}`);
+    }
+    const { target, ambiguous } = resolveTarget("auto", agents);
+    logger.out(`\nauto target -> ${target}${ambiguous.length > 1 ? " (ambiguous: " + ambiguous.join(", ") + ")" : ""}`);
+    const advisory = authAdvisory(agents);
+    if (advisory)
+        logger.out(`\n! ${advisory}`);
+    return 0;
+}
+function cmdConfig(args) {
+    const sub = args[0];
+    if (sub === "get" || sub === undefined) {
+        logger.out(JSON.stringify(loadConfig(), null, 2));
+        logger.out(`\n(config file: ${configPath()})`);
+        return 0;
+    }
+    if (sub === "set") {
+        const key = args[1];
+        const value = args[2];
+        if (!key || value === undefined) {
+            logger.error("usage: maq config set <key> <value>");
+            return 1;
+        }
+        try {
+            const cfg = setConfigKey(key, value);
+            logger.out(`set ${key} = ${String(cfg[key])}`);
+            return 0;
+        }
+        catch (e) {
+            logger.error(e.message);
+            return 1;
+        }
+    }
+    if (sub === "path") {
+        logger.out(configPath());
+        return 0;
+    }
+    if (sub === "reset") {
+        saveConfig(loadConfig());
+        logger.out("config written with defaults merged");
+        return 0;
+    }
+    logger.error(`unknown config subcommand: ${sub}`);
+    return 1;
+}
+async function cmdScout(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const task = positionals.join(" ").trim();
+    if (!task) {
+        logger.error('usage: maq scout "<task>"');
+        return 1;
+    }
+    const cwd = values.cwd ?? process.cwd();
+    const findings = await runScout(task, cwd);
+    logger.out(JSON.stringify(findings, null, values.json ? 0 : 2));
+    return 0;
+}
+async function cmdPlan(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const task = positionals.join(" ").trim();
+    if (!task) {
+        logger.error('usage: maq plan "<task>"');
+        return 1;
+    }
+    const cwd = values.cwd ?? process.cwd();
+    const cfg = loadConfig();
+    const findings = await runScout(task, cwd);
+    const plan = await runPlan(findings, getProvider(cfg.provider), cfg.masterModel);
+    logger.out(JSON.stringify(plan, null, values.json ? 0 : 2));
+    return 0;
+}
+async function cmdRun(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            ...commonFlags(),
+            target: { type: "string", short: "t" },
+            "dry-run": { type: "boolean", default: false },
+            provider: { type: "string" },
+            model: { type: "string" },
+            audit: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+    });
+    const task = positionals.join(" ").trim();
+    if (!task) {
+        logger.error('usage: maq run "<task>" [--target auto|claude|codex|gemini|none] [--dry-run] [--provider p] [--model m] [--audit]');
+        return 1;
+    }
+    const cwd = values.cwd ?? process.cwd();
+    const streamJson = values.json;
+    const onEvent = (e) => {
+        if (streamJson) {
+            logger.out(JSON.stringify(e));
+        }
+        else {
+            renderEvent(e);
+        }
+    };
+    const result = await runPipeline(task, {
+        cwd,
+        target: values.target,
+        dryRun: values["dry-run"],
+        provider: values.provider,
+        model: values.model,
+        audit: values.audit,
+        onEvent,
+    });
+    if (!streamJson) {
+        logger.out("");
+        logger.out(`result: ${result.execute.status}, verified: ${result.verify.verified} (${result.verify.method})`);
+        if (result.cost) {
+            logger.out(`master cost: ${result.cost.calls} calls, ${result.cost.totalTokens} tok, $${result.cost.usd.toFixed(4)}`);
+        }
+        if (result.runId) {
+            logger.out(`audit: .maq/runs/${result.runId}/ (verify with: maq audit verify .maq/runs/${result.runId})`);
+        }
+    }
+    return result.verify.verified && result.execute.status !== "failed" ? 0 : 3;
+}
+async function cmdVerify(args) {
+    const { values } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const cwd = values.cwd ?? process.cwd();
+    const testCmd = detectTestCommand(cwd);
+    const cfg = loadConfig();
+    const result = await runVerify({ status: "success", target: "none", command: null, exitCode: 0, stdout: "", stderr: "", filesChanged: [], errors: [] }, { cwd, provider: getProvider(cfg.provider), model: cfg.masterModel });
+    logger.out(JSON.stringify({ detectedTestCommand: testCmd, verify: result }, null, values.json ? 0 : 2));
+    return result.verified ? 0 : 3;
+}
+async function cmdServe(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            host: { type: "string" },
+            port: { type: "string" },
+            token: { type: "string" },
+            cors: { type: "string" },
+            relay: { type: "string" },
+            device: { type: "string" },
+            "relay-token": { type: "string" },
+        },
+        allowPositionals: true,
+    });
+    const daemon = createDaemon({
+        host: values.host,
+        port: values.port ? Number(values.port) : undefined,
+        token: values.token,
+        corsOrigin: values.cors,
+        version: VERSION,
+    });
+    try {
+        const { host, port } = await daemon.listen();
+        logger.out(`maq daemon listening on http://${host}:${port}`);
+        logger.out(`auth token: ${daemon.token}`);
+        logger.out(`  export MAQ_TOKEN=${daemon.token}   # for 'maq sessions'`);
+        if (host === "0.0.0.0" || host === "::") {
+            logger.error("! SECURITY: bound to all interfaces — this exposes device control to the network. Prefer 127.0.0.1 + a tunnel/tailnet.");
+        }
+        else {
+            logger.out("(loopback only; put a tunnel/tailnet in front for remote access)");
+        }
+        logger.out("endpoints: GET /health  GET /v1/agents  GET /v1/connectivity  GET|POST /v1/sessions  GET /v1/sessions/:id/events (SSE)");
+        // Optional: dial OUT to a relay so a phone can reach this daemon with no
+        // inbound ports (Tier 2). Pairing string for the app:
+        //   maq://relay?url=<relay>&device=<id>&token=<relay-token>
+        let bridge;
+        const relayUrl = values.relay ?? process.env.MAQ_RELAY_URL;
+        if (relayUrl) {
+            const deviceId = values.device ?? process.env.MAQ_DEVICE_ID ?? daemon.token.slice(0, 12);
+            bridge = new RelayBridge({
+                url: relayUrl,
+                deviceId,
+                token: values["relay-token"] ?? process.env.RELAY_TOKEN,
+                registry: daemon.registry,
+                log: (m) => logger.out(m),
+            });
+            bridge.start();
+            logger.out(`relay bridge: dialing ${relayUrl} as device '${deviceId}'`);
+            logger.out(`  app pairing: maq://relay?url=${encodeURIComponent(relayUrl)}&device=${deviceId}&token=<relay-token>`);
+        }
+        // Optional: outbound webhook forwarding (plugins).
+        const cfg = loadConfig();
+        if (cfg.webhookUrl) {
+            attachWebhook(daemon.registry, { url: cfg.webhookUrl, log: (m) => logger.error(m) });
+            logger.out(`webhook: forwarding lifecycle events to ${cfg.webhookUrl}`);
+        }
+        // Optional: scheduled flows (cron-style) run against this daemon.
+        let scheduler;
+        const flows = loadFlows().filter((f) => f.enabled);
+        if (flows.length) {
+            scheduler = new Scheduler((flow) => {
+                logger.out(`flow '${flow.name}' firing: ${flow.task}`);
+                daemon.registry.assign(flow.task, { target: flow.target, profile: flow.profile, cwd: flow.cwd });
+            }, (m) => logger.out(m));
+            scheduler.start(flows);
+        }
+        // Keep the process alive until interrupted.
+        await new Promise((resolve) => {
+            const stop = () => {
+                logger.out("\nshutting down...");
+                bridge?.stop();
+                scheduler?.stop();
+                daemon.close().then(resolve);
+            };
+            process.on("SIGINT", stop);
+            process.on("SIGTERM", stop);
+        });
+        return 0;
+    }
+    catch (e) {
+        logger.error(`failed to start daemon: ${e.message}`);
+        return 1;
+    }
+}
+function daemonBase(values) {
+    const host = values.host ?? process.env.MAQ_HOST ?? "127.0.0.1";
+    const port = values.port ? Number(values.port) : Number(process.env.MAQ_PORT ?? 7717);
+    const token = values.token ?? process.env.MAQ_TOKEN ?? "";
+    return { base: `http://${host}:${port}`, token };
+}
+async function cmdSessions(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), host: { type: "string" }, port: { type: "string" }, token: { type: "string" } },
+        allowPositionals: true,
+    });
+    const { base, token } = daemonBase(values);
+    if (!token) {
+        logger.error("no token: set MAQ_TOKEN (printed by 'maq serve') or pass --token");
+        return 1;
+    }
+    const id = positionals[0];
+    const action = positionals[1];
+    if (id && action) {
+        if (!["pause", "resume", "cancel"].includes(action)) {
+            logger.error("action must be pause|resume|cancel");
+            return 1;
+        }
+        try {
+            const res = await fetch(`${base}/v1/sessions/${encodeURIComponent(id)}/control`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                body: JSON.stringify({ action }),
+            });
+            const body = await res.json();
+            logger.out(JSON.stringify(body, null, values.json ? 0 : 2));
+            return res.ok ? 0 : 1;
+        }
+        catch (e) {
+            logger.error(`cannot reach daemon at ${base}: ${e.message} (is 'maq serve' running?)`);
+            return 1;
+        }
+    }
+    const path = id ? `/v1/sessions/${encodeURIComponent(id)}` : "/v1/sessions";
+    try {
+        const res = await fetch(base + path, { headers: { authorization: `Bearer ${token}` } });
+        const body = await res.json();
+        if (!res.ok) {
+            logger.error(`daemon ${res.status}: ${JSON.stringify(body)}`);
+            return 1;
+        }
+        logger.out(JSON.stringify(body, null, values.json ? 0 : 2));
+        return 0;
+    }
+    catch (e) {
+        logger.error(`cannot reach daemon at ${base}: ${e.message} (is 'maq serve' running?)`);
+        return 1;
+    }
+}
+function cmdModels(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const sub = positionals[0];
+    const pretty = values.json ? 0 : 2;
+    if (sub === "list") {
+        logger.out(JSON.stringify(masterOptions(), null, pretty));
+        return 0;
+    }
+    if (sub === "cheapest") {
+        const best = cheapestMaster();
+        logger.out(JSON.stringify(best, null, pretty));
+        return 0;
+    }
+    if (sub === "auto") {
+        const best = cheapestMaster();
+        setConfigKey("provider", best.provider);
+        setConfigKey("cheapModel", best.model);
+        setConfigKey("masterModel", best.model);
+        const cfg = loadConfig();
+        // Only overwrite the strong tier if it's still the default placeholder.
+        if (cfg.strongModel === "heuristic-local")
+            setConfigKey("strongModel", best.model);
+        logger.out(`master auto-configured for lowest cost:`);
+        logger.out(`  provider   = ${best.provider}`);
+        logger.out(`  cheapModel = ${best.model}   (${best.label}, ${best.costClass})`);
+        logger.out(`  reason: ${best.reason}`);
+        logger.out(`\ntip: set a stronger 'strongModel' for the hardest Plan steps: maq config set strongModel <model>`);
+        return 0;
+    }
+    const cfg = loadConfig();
+    const info = {
+        provider: cfg.provider,
+        tiers: {
+            cheap: { model: cfg.cheapModel, price: priceFor(cfg.cheapModel) },
+            strong: { model: cfg.strongModel, price: priceFor(cfg.strongModel) },
+        },
+        masterModel: cfg.masterModel,
+        available: providerAvailable(cfg.provider),
+        envHints: providerEnvHint(cfg.provider),
+        cheapestAvailable: cheapestMaster().label,
+    };
+    logger.out(JSON.stringify(info, null, pretty));
+    return 0;
+}
+function providerAvailable(name) {
+    try {
+        getProvider(name, { strict: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function providerEnvHint(name) {
+    if (name.toLowerCase().startsWith("cli"))
+        return "reuses an authenticated worker CLI as the master ($0 marginal)";
+    switch (name.toLowerCase()) {
+        case "openai":
+            return "set OPENAI_API_KEY (optional OPENAI_BASE_URL)";
+        case "anthropic":
+            return "set ANTHROPIC_API_KEY";
+        case "groq":
+            return "set GROQ_API_KEY";
+        case "ollama":
+            return "run Ollama locally (optional OLLAMA_HOST)";
+        case "openai-compatible":
+        case "litellm":
+            return "set MAQ_PROVIDER_BASE_URL (+ MAQ_PROVIDER_API_KEY)";
+        default:
+            return "offline; no key required";
+    }
+}
+async function cmdProbe(args) {
+    const { values } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const result = await probeConnectivity();
+    logger.out(JSON.stringify(result, null, values.json ? 0 : 2));
+    return result.decision.tier === "blocked" ? 2 : 0;
+}
+function cmdSkills(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), tier: { type: "string" } },
+        allowPositionals: true,
+    });
+    const cwd = values.cwd ?? process.cwd();
+    const cfg = loadConfig();
+    const sub = positionals[0];
+    const mgr = new SkillsManager(cwd, { skillsDir: cfg.skillsDir });
+    if (sub === "init") {
+        const written = initSkills(cwd, cfg.skillsDir);
+        logger.out(written.length ? `wrote:\n  ${written.join("\n  ")}` : "nothing to write (files already exist)");
+        return 0;
+    }
+    if (sub === "path") {
+        logger.out(`${cwd}/${cfg.skillsDir}`);
+        return 0;
+    }
+    const tier = values.tier === "strong" ? "strong" : "cheap";
+    const skills = mgr.forTier(tier);
+    const out = {
+        tier,
+        skillsDir: cfg.skillsDir,
+        count: skills.length,
+        skills: skills.map((s) => ({ name: s.name, tier: s.tier, kind: s.kind, source: s.path ?? "built-in" })),
+        contextBlockChars: mgr.contextBlock(tier).length,
+    };
+    logger.out(JSON.stringify(out, null, values.json ? 0 : 2));
+    return 0;
+}
+async function cmdSubagent(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), context: { type: "string" }, tokens: { type: "string" } },
+        allowPositionals: true,
+    });
+    const task = positionals.join(" ").trim();
+    if (!task) {
+        logger.error('usage: maq subagent "<task>" [--context <text>] [--tokens 1500]');
+        return 1;
+    }
+    const cfg = loadConfig();
+    const route = new Router(cfg).route("cheap");
+    const result = await runSubagent({ task, context: values.context, summaryTokens: values.tokens ? Number(values.tokens) : undefined }, route.provider, route.model);
+    logger.out(JSON.stringify(result, null, values.json ? 0 : 2));
+    return 0;
+}
+async function cmdTools(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), args: { type: "string" } },
+        allowPositionals: true,
+    });
+    const cwd = values.cwd ?? process.cwd();
+    const registry = createToolRegistry({ cwd });
+    const name = positionals[0];
+    if (!name) {
+        logger.out(JSON.stringify({ netEnabled: registry.netEnabled, tools: registry.schemas() }, null, values.json ? 0 : 2));
+        return 0;
+    }
+    let toolArgs = {};
+    if (values.args) {
+        try {
+            toolArgs = JSON.parse(values.args);
+        }
+        catch {
+            logger.error("--args must be JSON");
+            return 1;
+        }
+    }
+    try {
+        const result = await registry.run(name, toolArgs);
+        logger.out(typeof result === "string" ? result : JSON.stringify(result, null, values.json ? 0 : 2));
+        return 0;
+    }
+    catch (e) {
+        logger.error(e.message);
+        return 1;
+    }
+}
+async function cmdDoctor(args) {
+    const { values } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const cfg = loadConfig();
+    const agents = detectAgents();
+    const best = cheapestMaster();
+    const probe = await probeConnectivity();
+    const report = {
+        config: {
+            provider: cfg.provider,
+            cheapModel: cfg.cheapModel,
+            strongModel: cfg.strongModel,
+            providerAvailable: providerAvailable(cfg.provider),
+        },
+        workerAgents: agents.filter((a) => a.installed).map((a) => ({ name: a.name, authenticated: a.authenticated })),
+        masterAuto: { pick: best.label, provider: best.provider, model: best.model, costClass: best.costClass },
+        connectivity: { tier: probe.decision.tier, reason: probe.decision.reason, stun: probe.details.stun.ok, relay: probe.details.relay.ok },
+        skills: new SkillsManager(process.cwd(), { skillsDir: cfg.skillsDir }).load().length,
+        aiAdvisory: authAdvisory(agents),
+    };
+    const healthy = report.config.providerAvailable || best.available;
+    if (values.json) {
+        logger.out(JSON.stringify({ healthy, ...report }, null, 0));
+        return healthy ? 0 : 1;
+    }
+    logger.out("MAQ doctor");
+    logger.out(`  provider:     ${report.config.provider} (${report.config.providerAvailable ? "available" : "unavailable"})`);
+    logger.out(`  tiers:        cheap=${report.config.cheapModel}  strong=${report.config.strongModel}`);
+    logger.out(`  master auto:  ${report.masterAuto.pick} [${report.masterAuto.costClass}]`);
+    logger.out(`  worker CLIs:  ${report.workerAgents.map((a) => a.name + (a.authenticated ? "*" : "")).join(", ") || "none"} (*=authenticated)`);
+    logger.out(`  connectivity: tier=${report.connectivity.tier} stun=${report.connectivity.stun} relay=${report.connectivity.relay}`);
+    logger.out(`  skills:       ${report.skills} loaded`);
+    if (report.aiAdvisory)
+        logger.out(`  ! AI:         ${report.aiAdvisory}`);
+    logger.out(`  status:       ${healthy ? "OK" : "no usable master provider — run 'maq models auto'"}`);
+    return healthy ? 0 : 1;
+}
+function cmdAudit(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const sub = positionals[0];
+    if (sub !== "verify") {
+        logger.error("usage: maq audit verify <run-dir>");
+        return 1;
+    }
+    const dir = positionals[1];
+    if (!dir) {
+        logger.error("usage: maq audit verify <run-dir>   (e.g. .maq/runs/<id>)");
+        return 1;
+    }
+    const res = verifyAuditLog(dir);
+    logger.out(JSON.stringify(res, null, values.json ? 0 : 2));
+    return res.ok ? 0 : 2;
+}
+function cmdAgents(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const cwd = values.cwd ?? process.cwd();
+    const mgr = new ProfileManager(cwd);
+    if (positionals[0] === "init") {
+        const written = mgr.init();
+        logger.out(written.length ? `wrote:\n  ${written.join("\n  ")}` : "nothing to write (files already exist)");
+        return 0;
+    }
+    const profiles = mgr.load();
+    if (positionals[0] === "show" && positionals[1]) {
+        const p = mgr.get(positionals[1]);
+        if (!p) {
+            logger.error(`no such profile: ${positionals[1]}`);
+            return 1;
+        }
+        logger.out(JSON.stringify(p, null, values.json ? 0 : 2));
+        return 0;
+    }
+    logger.out(JSON.stringify(profiles.map((p) => ({ name: p.name, role: p.role, target: p.target, provider: p.provider, allowedTools: p.allowedTools, source: p.path ?? "built-in" })), null, values.json ? 0 : 2));
+    return 0;
+}
+function cmdMemory(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), tags: { type: "string" }, limit: { type: "string" } },
+        allowPositionals: true,
+    });
+    const cwd = values.cwd ?? process.cwd();
+    const mem = new RecallMemory(cwd);
+    const sub = positionals[0];
+    if (sub === "store") {
+        const key = positionals[1];
+        const text = positionals.slice(2).join(" ");
+        if (!key || !text) {
+            logger.error('usage: maq memory store <key> "<text>" [--tags a,b]');
+            return 1;
+        }
+        const tags = values.tags?.split(/[,\s]+/).filter(Boolean) ?? [];
+        const note = mem.store(key, text, tags);
+        logger.out(`stored: ${note.key}`);
+        return 0;
+    }
+    if (sub === "recall") {
+        const q = positionals.slice(1).join(" ");
+        const limit = values.limit ? Number(values.limit) : 5;
+        logger.out(JSON.stringify(mem.recall(q, limit), null, values.json ? 0 : 2));
+        return 0;
+    }
+    if (sub === "list") {
+        logger.out(JSON.stringify(mem.all(), null, values.json ? 0 : 2));
+        return 0;
+    }
+    logger.error("usage: maq memory [store <key> \"<text>\" | recall <query> | list]");
+    return 1;
+}
+async function cmdSwarm(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), target: { type: "string", short: "t" }, concurrency: { type: "string" }, "dry-run": { type: "boolean", default: false } },
+        allowPositionals: true,
+    });
+    const tasks = positionals.map((t) => t.trim()).filter(Boolean);
+    if (tasks.length === 0) {
+        logger.error('usage: maq swarm "<task1>" "<task2>" ... [--target none] [--concurrency N] [--dry-run]');
+        return 1;
+    }
+    const cwd = values.cwd ?? process.cwd();
+    const registry = new SessionRegistry();
+    const result = await runSwarm(registry, tasks.map((task) => ({ task, target: values.target, cwd, dryRun: values["dry-run"] })), { maxConcurrency: values.concurrency ? Number(values.concurrency) : undefined });
+    logger.out(JSON.stringify(result, null, values.json ? 0 : 2));
+    return result.allVerified ? 0 : 3;
+}
+async function cmdInteractive(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), target: { type: "string", short: "t" } },
+        allowPositionals: true,
+    });
+    const task = positionals.join(" ").trim();
+    const requested = values.target ?? "auto";
+    const agents = detectAgents();
+    const { target } = resolveTarget(requested, agents);
+    const spec = agentSpec(target);
+    const binPath = agents.find((a) => a.name === target)?.binPath ?? null;
+    if (!spec || !spec.headless || !binPath) {
+        logger.error(`interactive needs a runnable agent CLI; '${target}' is not available. Try: maq detect`);
+        return 1;
+    }
+    const cwd = values.cwd ?? process.cwd();
+    const argv = spec.headless.map((a) => (a === "{task}" ? task : a));
+    const worker = new InteractiveWorker(binPath, argv, {
+        cwd,
+        onEvent: (e) => renderEvent(e),
+        onStatus: (s) => logger.out(`    [status: ${s}]`),
+    });
+    worker.start();
+    logger.out(`interactive ${target} started; type to steer, Ctrl-D to end.`);
+    // Forward this terminal's stdin to the worker (inbox → stdin steering).
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => worker.write(String(chunk).replace(/\r?\n$/, "")));
+    process.stdin.on("end", () => worker.end());
+    const code = await worker.wait();
+    return code === 0 ? 0 : 2;
+}
+function cmdFlow(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), schedule: { type: "string" }, target: { type: "string", short: "t" }, profile: { type: "string" } },
+        allowPositionals: true,
+    });
+    const sub = positionals[0];
+    if (sub === "list") {
+        logger.out(JSON.stringify(loadFlows(), null, values.json ? 0 : 2));
+        return 0;
+    }
+    if (sub === "add") {
+        const name = positionals[1];
+        const task = positionals.slice(2).join(" ");
+        const schedule = values.schedule;
+        if (!name || !task || !schedule) {
+            logger.error('usage: maq flow add <name> "<task>" --schedule "@daily|every 30m" [--target t] [--profile p]');
+            return 1;
+        }
+        if (scheduleMs(schedule) === null) {
+            logger.error(`invalid schedule '${schedule}'. Use @hourly|@daily|@weekly or "every 30m|2h|45s".`);
+            return 1;
+        }
+        addFlow({ name, task, schedule, target: values.target, profile: values.profile, enabled: true });
+        logger.out(`flow '${name}' added (${schedule}). Runs when 'maq serve' is active.`);
+        return 0;
+    }
+    if (sub === "remove" || sub === "rm") {
+        const name = positionals[1];
+        if (!name) {
+            logger.error("usage: maq flow remove <name>");
+            return 1;
+        }
+        removeFlow(name);
+        logger.out(`flow '${name}' removed`);
+        return 0;
+    }
+    logger.error("usage: maq flow [list | add <name> \"<task>\" --schedule <s> | remove <name>]");
+    return 1;
+}
+function cmdHelp(args) {
+    const topic = args[0];
+    if (!topic) {
+        printHelp();
+        const all = listTopics();
+        logger.out(`\ntopics: ${all.map((t) => t.name).join(", ")}`);
+        logger.out("  run: maq help <topic>");
+        return 0;
+    }
+    const found = getTopic(topic);
+    if (!found) {
+        const all = listTopics();
+        logger.error(`unknown topic: ${topic}`);
+        logger.out(`\navailable topics: ${all.map((t) => t.name).join(", ")}`);
+        return 2;
+    }
+    logger.out(renderTopic(found));
+    return 0;
+}
+function cmdBoard(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const cwd = values.cwd ?? process.cwd();
+    const board = new Board(cwd);
+    const sub = positionals[0];
+    if (sub === "show") {
+        const taskId = positionals[1];
+        if (!taskId) {
+            logger.error("usage: maq board show <task-id>");
+            return 2;
+        }
+        const result = board.showTask(taskId);
+        if (!result) {
+            logger.error(`no task found: ${taskId}`);
+            return 1;
+        }
+        logger.out(JSON.stringify(result, null, values.json ? 0 : 2));
+        return 0;
+    }
+    if (sub === "tail") {
+        const limit = positionals[1] ? Number(positionals[1]) : 5;
+        const tasks = board.listTasks(limit);
+        if (values.json) {
+            logger.out(JSON.stringify(tasks, null, 0));
+            return 0;
+        }
+        if (tasks.length === 0) {
+            logger.out("no tasks recorded yet");
+            return 0;
+        }
+        for (const t of tasks) {
+            const phases = t.phases.map((p) => `${p.phase}:${p.status}`).join(" \u2192 ");
+            logger.out(`  ${t.taskId}  ${t.status.padEnd(7)}  ${phases}  "${t.task.slice(0, 60)}"`);
+        }
+        return 0;
+    }
+    // Default: list
+    const limit = positionals[1] ? Number(positionals[1]) : 20;
+    const tasks = board.listTasks(limit);
+    logger.out(JSON.stringify(tasks, null, values.json ? 0 : 2));
+    return 0;
+}
+async function cmdInit(args) {
+    const { values } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const cwd = values.cwd ?? process.cwd();
+    const result = await runInit(cwd);
+    return result.configured ? 0 : 1;
+}
+function cmdLogs(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { ...commonFlags(), limit: { type: "string" } },
+        allowPositionals: true,
+    });
+    const cwd = values.cwd ?? process.cwd();
+    const board = new Board(cwd);
+    const taskId = positionals[0];
+    if (taskId) {
+        const entries = board.getEntries(taskId);
+        if (entries.length === 0) {
+            logger.error(`no log entries for task: ${taskId}`);
+            return 1;
+        }
+        if (values.json) {
+            logger.out(JSON.stringify(entries, null, 0));
+        }
+        else {
+            for (const e of entries) {
+                const phase = e.phase ? ` [${e.phase}]` : "";
+                logger.out(`  ${e.ts}  ${e.type}${phase}  ${JSON.stringify(e.data)}`);
+            }
+        }
+        return 0;
+    }
+    const limit = values.limit ? Number(values.limit) : 10;
+    const tasks = board.listTasks(limit);
+    if (values.json) {
+        logger.out(JSON.stringify(tasks, null, 0));
+    }
+    else {
+        if (tasks.length === 0) {
+            logger.out("no tasks recorded yet. run: maq run \"<task>\"");
+            return 0;
+        }
+        logger.out("Recent tasks (use 'maq logs <task-id>' for details):\n");
+        for (const t of tasks) {
+            const dur = t.finishedAt ? ` (${timeDiff(t.startedAt, t.finishedAt)})` : "";
+            logger.out(`  ${t.taskId}  ${t.status.padEnd(7)}${dur}  "${t.task.slice(0, 60)}"`);
+        }
+    }
+    return 0;
+}
+function timeDiff(a, b) {
+    const ms = new Date(b).getTime() - new Date(a).getTime();
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    return `${m}m ${s % 60}s`;
+}
+function cmdStop(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: commonFlags(),
+        allowPositionals: true,
+    });
+    const taskId = positionals[0];
+    if (!taskId) {
+        logger.error("usage: maq stop <task-id>");
+        return 2;
+    }
+    const cwd = values.cwd ?? process.cwd();
+    const board = new Board(cwd);
+    board.taskAbort(taskId, "stopped by user (maq stop)");
+    logger.out(`task ${taskId} marked as aborted`);
+    return 0;
+}
+function cmdCost(args) {
+    const { values, positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const cwd = values.cwd ?? process.cwd();
+    const tracker = new CostTracker(cwd);
+    const sub = positionals[0];
+    if (sub === "reset") {
+        tracker.reset();
+        logger.out("cost history cleared");
+        return 0;
+    }
+    const report = tracker.report();
+    if (values.json) {
+        logger.out(JSON.stringify(report, null, 0));
+    }
+    else {
+        logger.out(CostTracker.renderReport(report));
+    }
+    return 0;
+}
+function cmdCompletion(args) {
+    const { positionals } = parseArgs({ args, options: commonFlags(), allowPositionals: true });
+    const shell = positionals[0] ?? detectShell();
+    if (!shell || !["bash", "zsh", "fish", "powershell"].includes(shell)) {
+        logger.error("usage: maq completion <bash|zsh|fish|powershell>");
+        logger.out("\nadd to your shell profile:");
+        logger.out('  bash:       eval "$(maq completion bash)"');
+        logger.out('  zsh:        eval "$(maq completion zsh)"');
+        logger.out("  fish:       maq completion fish | source");
+        logger.out("  powershell: maq completion powershell | Invoke-Expression");
+        return 2;
+    }
+    logger.out(generateCompletion(shell));
+    return 0;
+}
+function renderEvent(e) {
+    switch (e.type) {
+        case "task.started":
+            logger.out(`> task: ${String(e.data.task)}  [provider=${String(e.data.provider)} cheap=${String(e.data.cheapModel)} strong=${String(e.data.strongModel)}]`);
+            break;
+        case "phase.started":
+            logger.out(`  - ${String(e.data.phase)} ...`);
+            break;
+        case "phase.done":
+            logger.out(`  = ${String(e.data.phase)} done ${summarize(e.data)}`);
+            break;
+        case "task.done":
+            logger.out(`> done (verified=${String(e.data.verified)}, status=${String(e.data.status)})`);
+            break;
+        case "agent.stdout":
+            logger.out(`    | ${String(e.data.text)}`);
+            break;
+        case "agent.stderr":
+            logger.out(`    ! ${String(e.data.text)}`);
+            break;
+        case "tool.call":
+            logger.out(`    · tool: ${e.data.tool ? String(e.data.tool) : JSON.stringify(e.data.command ?? e.data.raw ?? {})}`);
+            break;
+        case "task.paused":
+            logger.out("> paused");
+            break;
+        case "task.resumed":
+            logger.out("> resumed");
+            break;
+        case "task.cancelled":
+            logger.out("> cancelled");
+            break;
+        case "task.error":
+            logger.out(`> error: ${String(e.data.message)}`);
+            break;
+        default:
+            break;
+    }
+}
+function summarize(data) {
+    const drop = new Set(["phase"]);
+    const parts = Object.entries(data)
+        .filter(([k]) => !drop.has(k))
+        .map(([k, v]) => `${k}=${typeof v === "object" ? JSON.stringify(v) : String(v)}`);
+    return parts.length ? `(${parts.join(", ")})` : "";
+}
+function printHelp() {
+    logger.out([
+        "maqcli — MAQ master orchestrator (Scout -> Plan -> Execute -> Verify)",
+        "",
+        "Usage: maq <command> [options]",
+        "",
+        "Commands:",
+        "  detect                       Scan PATH + auth dirs for worker CLIs",
+        '  scout "<task>"               Read-only recon; prints structured findings',
+        '  plan "<task>"                Verifier-gated candidate plan (scout + plan)',
+        '  run "<task>" [opts]          Full pipeline; dispatch to a worker or raw',
+        "  verify [--cwd <dir>]         Run project tests / cross-model review",
+        "  serve [--host --port --token] Start the HTTP+SSE daemon (app seam)",
+        "  sessions [<id>] [pause|resume|cancel]  List/inspect/control daemon sessions (needs MAQ_TOKEN)",
+        "  models [list|cheapest|auto] Show/optimize the master model ($0 intelligence layer)",
+        "  probe                        Probe connectivity tier (STUN/UDP + TCP + LAN)",
+        "  skills [init|path] [--tier]  List/scaffold the skills/rules layer (tier-aware)",
+        '  subagent "<task>" [--context] Run an isolated sub-agent; returns a concise summary',
+        "  tools [<name>] [--args JSON] List safe tools, or run one (read_file/list_dir/grep_text/...)",
+        "  doctor                       One-shot health check (provider, agents, connectivity, skills)",
+        "  agents [list|init|show <n>]  Named agent profiles + tool restrictions",
+        '  memory [store|recall|list]   Recall memory store (injected into planning)',
+        '  swarm "<t1>" "<t2>" …        Run tasks across parallel workers (supervisor join)',
+        '  interactive [-t <agent>]     Attach a steerable interactive worker (stdin steering)',
+        '  flow [list|add|remove]       Scheduled agent sessions (run under maq serve)',
+        "  board [show|list|tail]       Inspect the shared state board",
+        "  init                         First-time setup wizard",
+        "  logs [<task-id>]             View structured run logs",
+        "  stop <task-id>               Abort a running task (kill switch)",
+        "  cost [report|reset]          Aggregated cost tracking",
+        '  completion <shell>           Shell completions (bash/zsh/fish/powershell)',
+        "  audit verify <run-dir>       Verify a run's hash-chained audit log",
+        "  config [get|set|path|reset]  Read or update ~/.maqcli/config.json",
+        "  version | help [<topic>]",
+        "",
+        "run options:",
+        "  -t, --target <t>   auto | claude-code | codex | gemini | none",
+        "      --dry-run      plan and show commands without executing",
+        "      --provider <p> override provider for this run (openai|anthropic|ollama|groq|cli:<agent>|…)",
+        "      --model <m>    override the tier model(s) for this run",
+        "      --audit        write run artifacts + a hash-chained audit log under .maq/runs/",
+        "      --json         stream normalized events / emit JSON",
+        "      --cwd <dir>    working directory",
+        "",
+        "providers (set 'provider' via config; keys from env only):",
+        "  heuristic (offline, $0) | openai | anthropic | ollama | groq | openai-compatible/litellm",
+    ].join("\n"));
+}
+main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    logger.error(err instanceof Error ? err.stack ?? err.message : String(err));
+    process.exit(1);
+});