maqcli 0.2.0

package/README.md

@@ -0,0 +1,223 @@
+shu# maqcli
+
+The **MAQ master orchestrator** — a token-efficient, agent-agnostic supervisor
+CLI that sits *on top of* any worker CLI (AI or not) and runs every task through
+a **Scout → Plan → Execute → Verify** pipeline. It also runs as a secure
+**daemon** so a phone/app can drive it over one normalized event stream.
+
+It does not replace your coding agent. It organizes, supports, and verifies its
+work — and when no AI is involved, it runs raw commands safely instead.
+
+- **Zero runtime dependencies** — Node built-ins + global `fetch` only.
+- **Runs fully offline** via a deterministic heuristic provider (no API key), and
+  connects to **real providers** (OpenAI / Anthropic / Ollama / Groq / any
+  OpenAI-compatible or LiteLLM proxy) when you configure one.
+- **Safe execution** — every command runs via `spawn` with an argument array and
+  `shell: false`; user/model values are never shell-interpreted.
+- **Secure daemon** — HTTP + SSE, bearer-token auth, loopback-only by default.
+
+## Install / build
+
+```bash
+cd cli
+npm install      # installs the TypeScript toolchain (dev only)
+npm run build    # tsc -> dist/
+npm test         # build + node --test  (60 tests)
+```
+
+Then run it:
+
+```bash
+node dist/index.js <command>
+# or, after `npm link` / global install:
+maq <command>     # (also aliased as `maqcli`)
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `maq detect` | Scan `PATH` + each tool's auth dir for worker CLIs; report installed/authenticated/json-stream and the auto target. |
+| `maq scout "<task>"` | Deterministic, read-only recon (files, README, manifest, git history, complexity). Zero token cost. |
+| `maq plan "<task>"` | Scout + verifier-gated candidate plan (Best-of-N with early exit). |
+| `maq run "<task>" [opts]` | Full pipeline; dispatch the winning plan to a worker CLI (streamed) or run raw (`--target none`). |
+| `maq verify [--cwd <dir>]` | Run the project's tests (or cross-model review) as the completion signal. |
+| `maq serve [opts]` | Start the HTTP+SSE daemon (the app seam). Prints a bearer token. |
+| `maq models` | Show the configured provider, tier models, prices, and availability. |
+| `maq probe` | Probe the connectivity tier (real STUN/UDP + TCP + LAN interfaces). |
+| `maq skills [init\|path] [--tier]` | List/scaffold the tier-aware skills/rules layer injected into planning. |
+| `maq subagent "<task>"` | Run an isolated sub-agent (fresh context) that returns a concise summary. |
+| `maq tools [<name>] [--args JSON]` | List the safe tool registry, or run one (read_file/list_dir/grep_text/…). |
+| `maq sessions [<id>] [pause\|resume\|cancel]` | List/inspect/control daemon sessions (needs `MAQ_TOKEN`). |
+| `maq config [get\|set\|path\|reset]` | Read/update `~/.maqcli/config.json`. |
+| `maq version` / `maq help` | — |
+
+### `run` options
+```
+-t, --target <t>   auto | claude-code | codex | gemini | opencode | aider | amazon-q | none
+    --dry-run      plan and show the commands without executing
+    --json         stream normalized events (one JSON object per line)
+    --cwd <dir>    working directory
+```
+
+### `serve` options
+```
+--host <h>   bind address (default 127.0.0.1; env MAQ_HOST)
+--port <p>   port (default 7717; env MAQ_PORT)
+--token <t>  bearer token (default env MAQ_TOKEN, else generated + printed)
+--cors <o>   allow a browser origin (default off; env MAQ_CORS_ORIGIN)
+```
+
+## Model providers (LiteLLM-style, one interface)
+
+All master-model calls go through one `ModelProvider` interface. Select a
+provider with `maq config set provider <name>`. **API keys come from the
+environment only — never config files.** Missing keys fall back to the offline
+heuristic provider so the pipeline always runs.
+
+| provider | env | notes |
+|---|---|---|
+| `heuristic` | — | offline, deterministic, $0 (default) |
+| `openai` | `OPENAI_API_KEY` (`OPENAI_BASE_URL?`) | `/v1/chat/completions` |
+| `anthropic` | `ANTHROPIC_API_KEY` | Messages API, `anthropic-version: 2023-06-01` |
+| `ollama` | `OLLAMA_HOST?` | local, native `/api/chat`, free |
+| `groq` | `GROQ_API_KEY` | OpenAI-compatible, free tier |
+| `openai-compatible` / `litellm` | `MAQ_PROVIDER_BASE_URL` (`MAQ_PROVIDER_API_KEY?`) | any OpenAI-compatible endpoint / LiteLLM proxy |
+| `cli:<agent>` | — | reuse an authenticated worker CLI (e.g. `cli:gemini`, `cli:codex`) as the master's own model — **$0 marginal** (the user's existing subscription pays) |
+
+### $0 intelligence layer (`maq models auto`)
+
+The master's own thinking (Scout/Plan/Verify) should cost ~$0. `maq models`
+inspects the environment and ranks the cheapest capable master model:
+
+```bash
+maq models list      # ranked catalog with availability + reasons
+maq models cheapest  # the single best $0-or-cheapest option right now
+maq models auto      # write that choice into config (provider + cheapModel)
+```
+
+Ranking (best first): an **authenticated worker CLI** (reuse the user's
+subscription, $0 marginal) → a **free-tier key** (Groq / Gemini Flash) → a
+**local Ollama** model → the **cheapest paid** key (gpt-4o-mini / haiku) → the
+**offline heuristic** ($0 floor). Heavy Worker executions stay BYO-key; only the
+light master loop is auto-optimized. This is the PRODUCTION_GUIDE "$0 daemon
+thinking" strategy, implemented.
+
+Every call has an `AbortController` timeout (`MAQ_MODEL_TIMEOUT_MS`) and bounded
+retries with backoff (`MAQ_MODEL_RETRIES`) on 429/5xx/network errors. Real
+`usage` is used for token/cost accounting when the API returns it; prices come
+from a built-in table (override with `MAQ_PRICES`).
+
+## RouteLLM-style tiering
+
+Cheap work (Scout triage, Verify review, non-complex Plan) routes to a **cheap**
+model; genuinely complex Plans escalate to a **strong** model. Configure both:
+
+```bash
+maq config set provider openai
+maq config set cheapModel  gpt-4o-mini
+maq config set strongModel gpt-4o
+maq config set defaultTarget codex
+```
+
+## Harness features (lift any model toward frontier-level results)
+
+The point of the harness: a cheap model inside a good harness beats a strong
+model with no harness. These supply, externally, the mechanisms a long-horizon
+model does internally (plan → delegate → verify → self-improve):
+
+- **Skills / rules layer** (`maq skills`) — standing instructions injected into
+  planning, loaded from built-in defaults + `~/.maqcli/skills` + project
+  `.maq/skills/*.md` + `AGENTS.md`/`CLAUDE.md`. **Tier-aware**: `scaffolding`
+  rules are dropped for the strong tier (rules written for a weak model hold a
+  strong one back). `maq skills init` scaffolds starter files.
+- **Sub-agent isolation** (`maq subagent`) — run a scoped sub-task in a fresh,
+  minimal context that returns only a concise summary (containment over
+  delegation), so you get the token savings of isolation.
+- **Safe tool registry** (`maq tools`) — `read_file` / `list_dir` / `grep_text`
+  / `headroom_retrieve`, sandboxed to the working dir; opt-in `http_get`
+  (`MAQ_ALLOW_NET=1`). Advertisable as tool-use schemas.
+- **Session control** (`maq sessions <id> pause|resume|cancel`) — pause at phase
+  boundaries, resume, or cancel (kills in-flight worker processes via abort).
+- **Self-learning** — verify failures append a lesson to `AGENTS.md`.
+
+Set `skillsDir` and `thinkingEffort` via `maq config`.
+
+## Daemon + app seam
+
+`maq serve` exposes the orchestrator over one normalized contract so the app
+never speaks any worker CLI's dialect:
+
+```
+GET  /health                     liveness (no auth)
+GET  /v1/agents                  detected worker CLIs
+GET  /v1/connectivity            connectivity tier probe
+GET  /v1/sessions                list session summaries
+POST /v1/sessions                start a session {task,target?,cwd?,dryRun?}
+GET  /v1/sessions/:id            one session (summary + events)
+GET  /v1/sessions/:id/events     SSE stream (replay history, then live)
+POST /v1/sessions/:id/message    deliver a message to a session {text}
+```
+
+Security: every route except `/health` requires `Authorization: Bearer <token>`
+(constant-time compared). Binds to `127.0.0.1` by default; binding to all
+interfaces is allowed but logged loudly. Put a tunnel/tailnet in front for
+remote access rather than opening inbound ports.
+
+Multi-agent coordination uses CAO-style vocabulary in the session registry:
+`assign` (async, fire-and-forget), `handoff` (sync, await completion), and
+`sendMessage` (inbox delivery) — the vocabulary, not the tmux/Bedrock runtime.
+
+## How it works
+
+```
+task ─▶ SCOUT ─▶ PLAN ─▶ EXECUTE ─▶ VERIFY ─▶ result
+        (read-  (branch/  (worker    (tests as   │
+         only,   filter/   CLI, live  ground      └▶ on failure: append a
+         0-tok)  commit)   streamed)  truth)         lesson to AGENTS.md
+```
+
+- **Complexity gating** — trivial tasks skip Scout/Plan; standard/complex tasks
+  get the full pipeline, keeping multi-agent overhead off work that doesn't need it.
+- **Verifier-gated planning** — short candidate approaches scored against
+  *checkable* structure; the first clear winner short-circuits the rest.
+- **Streamed execution** — worker stdout/stderr is parsed line-by-line into
+  normalized events (`agent.stdout`, `agent.stderr`, `tool.call`, `agent.event`)
+  in real time; JSON-line streams (e.g. Claude Code) become structured events.
+- **Headroom-style compression** — worker output is compressed before it would
+  reach a model, with the original retrievable by reference.
+- **Verify-by-default + self-learning** — tests are the ground truth; on failure
+  a structured lesson is appended to `AGENTS.md` so the worker sees corrective
+  guidance next time.
+
+## Configuration
+
+`~/.maqcli/config.json` (override the directory with `MAQ_CONFIG_DIR`):
+
+```json
+{
+  "masterModel": "heuristic-local",
+  "defaultTarget": "auto",
+  "provider": "heuristic",
+  "cheapModel": "heuristic-local",
+  "strongModel": "heuristic-local",
+  "compactionThreshold": 0.6,
+  "projectTargets": {}
+}
+```
+
+## Extending
+
+- **New worker CLIs** — add an entry to `KNOWN_AGENTS` in `src/core/registry.ts`.
+- **New providers** — implement `ModelProvider` (see `src/core/providers.ts`) and
+  register it in `getProvider` (`src/core/model.ts`).
+- **Upstream Headroom** — swap the local `Headroom` class for the
+  `headroomlabs-ai/headroom` engine without changing callers.
+
+## Status
+
+The `cli/` master tier is functional and tested (**72 tests**): offline pipeline,
+real model providers, RouteLLM-style tiering, streamed execution, a secure
+daemon with SSE, session/multi-agent management with pause/resume/cancel, a real
+connectivity probe, a tier-aware skills/rules layer, sub-agent isolation, and a
+safe tool registry.

package/dist/core/audit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Run artifacts + HMAC-chained audit log (Bernstein-inspired).
+ *
+ * When enabled, each run writes structured artifacts and an append-only,
+ * hash-linked audit trail under `<cwd>/.maq/runs/<runId>/`:
+ *   scout.json plan.json execute.json verify.json result.json
+ *   audit.log   — one JSON line per action, each carrying an HMAC over
+ *                 (prevHash + payload), so tampering with any earlier line
+ *                 breaks the chain. This is the replayable trust artifact a
+ *                 "control my machine from my phone" product eventually needs.
+ *
+ * The HMAC key comes from MAQ_AUDIT_KEY (falls back to a fixed dev key with a
+ * marker so verification still works locally; set a real key for real use).
+ */
+export interface AuditEntry {
+    seq: number;
+    ts: string;
+    action: string;
+    data: Record<string, unknown>;
+    prevHash: string;
+    hash: string;
+}
+export declare class AuditLog {
+    readonly dir: string;
+    private seq;
+    private prevHash;
+    private path;
+    constructor(cwd: string, runId: string);
+    /** Append a hash-linked action to the audit log. */
+    record(action: string, data?: Record<string, unknown>): AuditEntry;
+    /** Write a named JSON artifact next to the log. */
+    artifact(name: string, obj: unknown): void;
+}
+/**
+ * Verify an audit.log's hash chain. Returns { ok, entries, brokenAt? }.
+ * A mismatch means a line was altered/removed/reordered after it was written.
+ */
+export declare function verifyAuditLog(dir: string): {
+    ok: boolean;
+    entries: number;
+    brokenAt?: number;
+    reason?: string;
+};

package/dist/core/audit.js

@@ -0,0 +1,77 @@
+/**
+ * Run artifacts + HMAC-chained audit log (Bernstein-inspired).
+ *
+ * When enabled, each run writes structured artifacts and an append-only,
+ * hash-linked audit trail under `<cwd>/.maq/runs/<runId>/`:
+ *   scout.json plan.json execute.json verify.json result.json
+ *   audit.log   — one JSON line per action, each carrying an HMAC over
+ *                 (prevHash + payload), so tampering with any earlier line
+ *                 breaks the chain. This is the replayable trust artifact a
+ *                 "control my machine from my phone" product eventually needs.
+ *
+ * The HMAC key comes from MAQ_AUDIT_KEY (falls back to a fixed dev key with a
+ * marker so verification still works locally; set a real key for real use).
+ */
+import { createHmac } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync, appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const DEV_KEY = "maq-dev-audit-key-set-MAQ_AUDIT_KEY";
+function auditKey() {
+    return process.env.MAQ_AUDIT_KEY ?? DEV_KEY;
+}
+export class AuditLog {
+    dir;
+    seq = 0;
+    prevHash = "genesis";
+    path;
+    constructor(cwd, runId) {
+        this.dir = join(cwd, ".maq", "runs", runId);
+        this.path = join(this.dir, "audit.log");
+        mkdirSync(this.dir, { recursive: true });
+    }
+    /** Append a hash-linked action to the audit log. */
+    record(action, data = {}) {
+        const seq = this.seq++;
+        const ts = new Date().toISOString();
+        const payload = JSON.stringify({ seq, ts, action, data });
+        const hash = createHmac("sha256", auditKey()).update(this.prevHash + payload).digest("hex");
+        const entry = { seq, ts, action, data, prevHash: this.prevHash, hash };
+        this.prevHash = hash;
+        appendFileSync(this.path, JSON.stringify(entry) + "\n", "utf8");
+        return entry;
+    }
+    /** Write a named JSON artifact next to the log. */
+    artifact(name, obj) {
+        writeFileSync(join(this.dir, name), JSON.stringify(obj, null, 2), "utf8");
+    }
+}
+/**
+ * Verify an audit.log's hash chain. Returns { ok, entries, brokenAt? }.
+ * A mismatch means a line was altered/removed/reordered after it was written.
+ */
+export function verifyAuditLog(dir) {
+    const path = join(dir, "audit.log");
+    if (!existsSync(path))
+        return { ok: false, entries: 0, reason: "no audit.log" };
+    const lines = readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean);
+    let prevHash = "genesis";
+    for (let i = 0; i < lines.length; i++) {
+        let e;
+        try {
+            e = JSON.parse(lines[i]);
+        }
+        catch {
+            return { ok: false, entries: lines.length, brokenAt: i, reason: "invalid JSON" };
+        }
+        if (e.prevHash !== prevHash) {
+            return { ok: false, entries: lines.length, brokenAt: i, reason: "prevHash mismatch (reordered/removed)" };
+        }
+        const payload = JSON.stringify({ seq: e.seq, ts: e.ts, action: e.action, data: e.data });
+        const expect = createHmac("sha256", auditKey()).update(prevHash + payload).digest("hex");
+        if (expect !== e.hash) {
+            return { ok: false, entries: lines.length, brokenAt: i, reason: "hash mismatch (tampered)" };
+        }
+        prevHash = e.hash;
+    }
+    return { ok: true, entries: lines.length };
+}

package/dist/core/board.d.ts

@@ -0,0 +1,78 @@
+/**
+ * board.ts — Stigmergy shared-state layer for maqcli.
+ *
+ * Replaces passing large context blobs between pipeline phases with an
+ * append-only JSONL board stored at `<cwd>/.maq/board.jsonl`.
+ *
+ * Design properties:
+ *  - **Crash-safe**: Every mutation is a single `appendFileSync` call.
+ *    The worst-case failure is a partial last JSON line, which readers
+ *    skip gracefully.
+ *  - **Zero npm runtime deps**: Uses only `node:fs`, `node:path`,
+ *    and `node:crypto`.
+ *  - **Append-only**: Entries are never mutated or deleted; state is
+ *    derived by replaying the log.
+ */
+export type BoardPhase = "scout" | "plan" | "execute" | "verify";
+export type BoardEntryType = "task.created" | "phase.start" | "phase.done" | "phase.data" | "task.done" | "task.error" | "task.aborted";
+export interface BoardEntry {
+    id: string;
+    taskId: string;
+    ts: string;
+    type: BoardEntryType;
+    phase?: BoardPhase;
+    data: Record<string, unknown>;
+}
+export interface TaskSummary {
+    taskId: string;
+    task: string;
+    status: "running" | "done" | "failed" | "aborted";
+    startedAt: string;
+    finishedAt?: string;
+    phases: {
+        phase: BoardPhase;
+        status: string;
+    }[];
+    verified?: boolean;
+}
+/** Canonical path to the board file for a given working directory. */
+export declare function boardPath(cwd: string): string;
+export declare class Board {
+    private readonly filePath;
+    private dirEnsured;
+    constructor(cwd: string);
+    createTask(task: string): string;
+    phaseStart(taskId: string, phase: BoardPhase, data?: Record<string, unknown>): void;
+    phaseData(taskId: string, phase: BoardPhase, data: Record<string, unknown>): void;
+    phaseDone(taskId: string, phase: BoardPhase, data?: Record<string, unknown>): void;
+    taskDone(taskId: string, data?: Record<string, unknown>): void;
+    taskError(taskId: string, error: string): void;
+    taskAbort(taskId: string, reason?: string): void;
+    /** Return every entry for a given task, in append order. */
+    getEntries(taskId: string): BoardEntry[];
+    /**
+     * Merge all `phase.data` payloads for a task+phase into a single object.
+     * Returns `null` if no data entries exist for that combination.
+     */
+    getPhaseData(taskId: string, phase: BoardPhase): Record<string, unknown> | null;
+    /** Derive a summary for one task. Returns `null` if the task doesn't exist. */
+    getTask(taskId: string): TaskSummary | null;
+    /** List all tasks, newest first. */
+    listTasks(limit?: number): TaskSummary[];
+    /** Full detail view: summary + raw entries. */
+    showTask(taskId: string): {
+        summary: TaskSummary;
+        entries: BoardEntry[];
+    } | null;
+    /** Ensure `.maq/` directory exists (idempotent, cached). */
+    private ensureDir;
+    /** Append one entry as a JSON line. */
+    private append;
+    /**
+     * Read and parse the entire JSONL file.
+     * Gracefully skips blank or corrupt lines.
+     */
+    private readAll;
+    /** Derive a TaskSummary from a pre-filtered list of entries for one task. */
+    private static buildSummary;
+}

package/dist/core/board.js

@@ -0,0 +1,256 @@
+/**
+ * board.ts — Stigmergy shared-state layer for maqcli.
+ *
+ * Replaces passing large context blobs between pipeline phases with an
+ * append-only JSONL board stored at `<cwd>/.maq/board.jsonl`.
+ *
+ * Design properties:
+ *  - **Crash-safe**: Every mutation is a single `appendFileSync` call.
+ *    The worst-case failure is a partial last JSON line, which readers
+ *    skip gracefully.
+ *  - **Zero npm runtime deps**: Uses only `node:fs`, `node:path`,
+ *    and `node:crypto`.
+ *  - **Append-only**: Entries are never mutated or deleted; state is
+ *    derived by replaying the log.
+ */
+import { appendFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Canonical path to the board file for a given working directory. */
+export function boardPath(cwd) {
+    return join(cwd, ".maq", "board.jsonl");
+}
+function entryId() {
+    return randomUUID().replace(/-/g, "").slice(0, 12);
+}
+function taskIdFromUUID() {
+    return randomUUID().slice(0, 8);
+}
+function nowISO() {
+    return new Date().toISOString();
+}
+// ---------------------------------------------------------------------------
+// Board
+// ---------------------------------------------------------------------------
+export class Board {
+    filePath;
+    dirEnsured = false;
+    constructor(cwd) {
+        this.filePath = boardPath(cwd);
+    }
+    // ---- Writes -------------------------------------------------------------
+    createTask(task) {
+        const taskId = taskIdFromUUID();
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "task.created",
+            data: { task },
+        });
+        return taskId;
+    }
+    phaseStart(taskId, phase, data = {}) {
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "phase.start",
+            phase,
+            data,
+        });
+    }
+    phaseData(taskId, phase, data) {
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "phase.data",
+            phase,
+            data,
+        });
+    }
+    phaseDone(taskId, phase, data = {}) {
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "phase.done",
+            phase,
+            data,
+        });
+    }
+    taskDone(taskId, data = {}) {
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "task.done",
+            data,
+        });
+    }
+    taskError(taskId, error) {
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "task.error",
+            data: { error },
+        });
+    }
+    taskAbort(taskId, reason) {
+        this.append({
+            id: entryId(),
+            taskId,
+            ts: nowISO(),
+            type: "task.aborted",
+            data: { reason: reason ?? "aborted by user" },
+        });
+    }
+    // ---- Reads --------------------------------------------------------------
+    /** Return every entry for a given task, in append order. */
+    getEntries(taskId) {
+        return this.readAll().filter((e) => e.taskId === taskId);
+    }
+    /**
+     * Merge all `phase.data` payloads for a task+phase into a single object.
+     * Returns `null` if no data entries exist for that combination.
+     */
+    getPhaseData(taskId, phase) {
+        const entries = this.readAll().filter((e) => e.taskId === taskId &&
+            e.phase === phase &&
+            e.type === "phase.data");
+        if (entries.length === 0)
+            return null;
+        const merged = {};
+        for (const e of entries) {
+            Object.assign(merged, e.data);
+        }
+        return merged;
+    }
+    /** Derive a summary for one task. Returns `null` if the task doesn't exist. */
+    getTask(taskId) {
+        const entries = this.getEntries(taskId);
+        if (entries.length === 0)
+            return null;
+        return Board.buildSummary(taskId, entries);
+    }
+    /** List all tasks, newest first. */
+    listTasks(limit) {
+        const all = this.readAll();
+        const grouped = new Map();
+        for (const e of all) {
+            let arr = grouped.get(e.taskId);
+            if (!arr) {
+                arr = [];
+                grouped.set(e.taskId, arr);
+            }
+            arr.push(e);
+        }
+        const summaries = [];
+        grouped.forEach((entries, taskId) => {
+            summaries.push(Board.buildSummary(taskId, entries));
+        });
+        // Newest first (by startedAt descending)
+        summaries.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+        if (limit !== undefined && limit > 0) {
+            return summaries.slice(0, limit);
+        }
+        return summaries;
+    }
+    /** Full detail view: summary + raw entries. */
+    showTask(taskId) {
+        const entries = this.getEntries(taskId);
+        if (entries.length === 0)
+            return null;
+        return { summary: Board.buildSummary(taskId, entries), entries };
+    }
+    // ---- Internals ----------------------------------------------------------
+    /** Ensure `.maq/` directory exists (idempotent, cached). */
+    ensureDir() {
+        if (this.dirEnsured)
+            return;
+        mkdirSync(dirname(this.filePath), { recursive: true });
+        this.dirEnsured = true;
+    }
+    /** Append one entry as a JSON line. */
+    append(entry) {
+        this.ensureDir();
+        appendFileSync(this.filePath, JSON.stringify(entry) + "\n", "utf-8");
+    }
+    /**
+     * Read and parse the entire JSONL file.
+     * Gracefully skips blank or corrupt lines.
+     */
+    readAll() {
+        if (!existsSync(this.filePath))
+            return [];
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, "utf-8");
+        }
+        catch {
+            return [];
+        }
+        const entries = [];
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                entries.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Partial / corrupt line — skip gracefully
+            }
+        }
+        return entries;
+    }
+    /** Derive a TaskSummary from a pre-filtered list of entries for one task. */
+    static buildSummary(taskId, entries) {
+        const created = entries.find((e) => e.type === "task.created");
+        const task = created?.data?.task ?? "";
+        const startedAt = created?.ts ?? entries[0].ts;
+        // Determine status from the last entry's type
+        const last = entries[entries.length - 1];
+        let status = "running";
+        if (last.type === "task.done")
+            status = "done";
+        else if (last.type === "task.error")
+            status = "failed";
+        else if (last.type === "task.aborted")
+            status = "aborted";
+        const finishedAt = status !== "running" ? last.ts : undefined;
+        // Build phase list
+        const phaseOrder = ["scout", "plan", "execute", "verify"];
+        const phaseMap = new Map();
+        for (const e of entries) {
+            if (!e.phase)
+                continue;
+            if (e.type === "phase.start")
+                phaseMap.set(e.phase, "running");
+            if (e.type === "phase.done")
+                phaseMap.set(e.phase, "done");
+        }
+        const phases = [];
+        for (const p of phaseOrder) {
+            const s = phaseMap.get(p);
+            if (s)
+                phases.push({ phase: p, status: s });
+        }
+        // Verified if the verify phase completed
+        const verified = phaseMap.get("verify") === "done";
+        return {
+            taskId,
+            task,
+            status,
+            startedAt,
+            finishedAt,
+            phases,
+            verified: verified || undefined,
+        };
+    }
+}