@dyzsasd/dev-loop 0.22.0

package/README.md

@@ -0,0 +1,55 @@
+# dev-loop
+
+The standalone local **coordination hub** for the [dev-loop](https://github.com/dyzsasd/dev-loop)
+agents — a **zero-build, zero-native-dependency** MCP system-of-record over `node:sqlite` with
+**per-agent identity**, a localhost **web-UI daemon**, an opt-in agent **op-API + thin stdio shim**,
+and a **CLI-portable** transport (Claude Code · Codex · opencode).
+
+> One trusted host, localhost-only. Identity is **cooperative attribution** (not anti-spoof). Secrets
+> live in env by **name** only. See the security envelope in
+> [`docs/HUB-ARCHITECTURE.md`](https://github.com/dyzsasd/dev-loop/blob/main/docs/HUB-ARCHITECTURE.md).
+
+## Install
+
+```bash
+npm install -g @dyzsasd/dev-loop   # requires Node >= 23.6 (built-in node:sqlite + .ts type-stripping; zero build); installs the `dev-loop` + `dev-loop-hub` bins
+```
+
+This puts two bins on `PATH`: **`dev-loop`** (the CLI) and **`dev-loop-hub`** (the MCP server entry).
+
+## CLI
+
+```
+dev-loop serve                       run the stdio MCP server (the agent transport)
+dev-loop shim                        the thin stdio MCP shim → the loopback daemon op-API
+dev-loop daemon up|down|status       per-project daemon lifecycle — idempotent, auto web UI
+dev-loop init-service <key> <name> <PREFIX>   turnkey-bootstrap a service-backend project
+dev-loop mcp-merge <args>            merge dev-loop-hub into a product .mcp.json (never clobbers)
+dev-loop seed <key> <name> [PREFIX]  seed a project + actors + labels
+dev-loop doctor                      health-check the system-of-record (DOCTOR_OK)
+dev-loop identity-check [--expect <actor>[/<project>]]   the portability gate
+dev-loop version | help
+```
+
+## Identity & project (the env contract)
+
+Every launcher sets, **per pane**, the identity the write is attributed to:
+
+| Env var | Meaning |
+|---|---|
+| `DEVLOOP_ACTOR` | the per-agent identity (`pm`/`qa`/`dev`/…) — the attribution |
+| `DEVLOOP_PROJECT` | the pinned project key (or resolved from the cwd) |
+| `DEVLOOP_HUB_DB` | the SQLite system-of-record (default `~/.dev-loop/hub.db`) |
+
+Register it as an MCP server for your CLI — `{ "command": "dev-loop", "args": ["serve"] }` (or
+`["shim"]` for the daemon transport). Per-CLI recipes + the identity gate:
+[`docs/PORTABILITY.md`](https://github.com/dyzsasd/dev-loop/blob/main/docs/PORTABILITY.md).
+
+## Docs
+
+- [Architecture + safety envelope](https://github.com/dyzsasd/dev-loop/blob/main/docs/HUB-ARCHITECTURE.md)
+- [Running the loop](https://github.com/dyzsasd/dev-loop/blob/main/docs/RUNNING.md) ·
+  [The daemon](https://github.com/dyzsasd/dev-loop/blob/main/docs/DAEMON.md) ·
+  [Portability (Codex / opencode)](https://github.com/dyzsasd/dev-loop/blob/main/docs/PORTABILITY.md)
+
+MIT © Shuai

package/dist/agentops.js

@@ -0,0 +1,551 @@
+// dev-loop hub — the agent op-API ops as plain functions: the SINGLE definition of every ticket/read policy
+// the hub exposes. BOTH transports dispatch through these: the DL-43 daemon agent op-API (/api/op/*) and —
+// since DL-69 (the dispatch-sharing refactor) — the stdio MCP server (server.ts), whose 27 op-backed tool
+// handlers are now thin call-throughs to agentOp() (server.ts's toMcp() maps {status,body}→MCP ok()/err()).
+// So each policy — the read SELECTs, the save_issue/save_comment orchestration (the DL-24 per-transition
+// assignTo + the DL-32 prod-promotion gate + the REPLACE-labels/APPEND-relatedTo merge), and the doc/topic/
+// channel/mirror/label families (which also reuse the shared ticketwrite/docstore/topicstore/channelstore/
+// mirrorstore/labelstore) — has EXACTLY ONE definition. The old "edit both files" drift tripwire is RETIRED:
+// a change to any policy now lands in ONE place, and the differential-parity suite (test/shim.ts +
+// test/agent-api.ts, shim ≡ stdio for all 29 tools) is the structural guard against a future re-divergence.
+//
+// Each function takes a hub connection + the caller's already-resolved+validated actor (server.ts resolves it
+// from DEVLOOP_ACTOR + the G1 phantom-actor guard; the daemon from the X-Devloop-Actor header) and returns an
+// HTTP-shaped { status, body }: the daemon serializes it as JSON; server.ts's toMcp() maps it to ok()/err()
+// (a 200 → ok(body); a non-200 → err(body.error)). NO env read, NO mode gate, NO transport here — each
+// transport owns its own pipeline (server.ts the stdio identity; the daemon op-API writeOriginOk → actor →
+// mode-honoring) AROUND these pure-policy ops. (whoami + create_issue_label stay native in server.ts: whoami
+// is transport-specific identity, not an op; create_issue_label's policy already lives once in labelstore, and
+// the op logs an op-API-only label.create attribution event server.ts deliberately does not — DL-69 kept it
+// native so the stdio path stays byte-identical.)
+import { DatabaseSync } from "node:sqlite";
+import { TOOL_NAMES } from "./tooldefs.js"; // DL-85: the ONE tool/op name source; AGENT_OPS derives from it
+import { actorExists, listActorHandles, logEvent, unifiedDiff, STATES } from "./db.js";
+import { insertTicket, updateTicketRow, insertComment, loadRelease } from "./ticketwrite.js";
+// DL-62 doc/event family — the doc WRITES (docSave/docPublish, incl. the CAS + the single operator-publish
+// gate) + the docstore-error→HTTP-status map are reused VERBATIM from the shared, side-effect-free docstore
+// (exactly as the 5 ticket ops reuse ticketwrite.ts), so both transports share one publish gate + one CAS.
+// The doc READS (doc.list/get/history/diff) + list_events are the SINGLE definition of those SELECTs — since
+// DL-69 server.ts's handlers dispatch through them (no longer a 1:1 duplicate of a server.ts copy).
+import { resolveDoc, latestVersion, docSave, docPublish, statusForDocErr, DOC_KINDS } from "./docstore.js";
+// DL-64 discussion-board family — the topic/post reads + writes (incl. the §25 chair/invited role gates +
+// the round/append rules) + the error→HTTP-status map are reused VERBATIM from the shared, side-effect-free
+// topicstore (exactly as the doc family reuses docstore.ts), so the op-API and the stdio server.ts can never
+// drift on a gate or a response shape. The op-API parses raw JSON, so each handler hand-validates the input
+// shapes server.ts gets from zod (the DL-63 read-handler lesson — a non-string id/body must 400, never a 500).
+import { topicList, topicGet, topicOpen, postAdd, topicSynthesize, topicClose, statusForTopicErr } from "./topicstore.js";
+// DL-67 channel family — the channel register/send/poll/ack/status HANDLER logic + the DL-4 roadmap bridge are
+// reused VERBATIM from the shared, side-effect-free channelstore (exactly as the doc/topic families reuse
+// docstore/topicstore), so the op-API and the stdio server.ts can never drift. channel.send/poll are ASYNC
+// (network/dryrun), so agentOp returns OpResult|Promise<OpResult> and the daemon awaits it. The op-API parses
+// raw JSON → each handler hand-validates the shapes server.ts gets from zod (DL-63: a non-string arg → 400, never a 500).
+import { channelRegister, channelSend, channelPoll, channelAck, channelStatus, statusForChannelErr } from "./channelstore.js";
+// DL-68 P7 mirror + label/project — the FINAL slice. mirror.push's handler (reusing linear.ts's transport AS-IS)
+// + mirror.status are reused VERBATIM from the shared mirrorstore (so the op-API + server.ts can't drift on the
+// DL-11 DRYRUN invariant / reconcile-by-marker idempotency), and the label/project ops + the SINGLE LABEL_KINDS /
+// DL-22 reject from labelstore. mirror.push is ASYNC (Linear network / dryrun build) → agentOp returns a Promise.
+import { mirrorPush, mirrorStatus } from "./mirrorstore.js";
+import { createLabel, listLabels, getProject } from "./labelstore.js";
+const okR = (body) => ({ status: 200, body });
+const errR = (status, error) => ({ status, body: { error } });
+export const AGENT_OPS = TOOL_NAMES.filter((n) => n !== "whoami");
+// The MUTATING subset — the daemon applies writeOriginOk + the dry-run mode gate to exactly these (reads
+// never mutate, so they bypass both). Kept here next to AGENT_OPS so the two lists can't drift. doc.save /
+// doc.publish join the ticket writes; the doc/event reads stay read-only (parity with the read ticket ops).
+export const AGENT_WRITE_OPS = new Set(["save_issue", "save_comment", "doc.save", "doc.publish",
+    "topic.open", "post.add", "topic.synthesize", "topic.close", // DL-64: the 4 board writes
+    "channel.register", "channel.send", "channel.poll", "channel.ack", // DL-67: the 4 channel writes (register/send/poll/ack mutate the channels/channel_messages tables); channel.status stays a read (query_only)
+    "mirror.push", "create_issue_label"]); // DL-68: the 2 writes (mirror.push → mirror_map + the one-way Linear network write; create_issue_label → labels). mirror.status/list_issue_labels/get_project stay reads (query_only)
+export const isAgentOp = (s) => AGENT_OPS.includes(s);
+const toTicket = (r) => ({
+    id: r.id, project_id: r.project_id, title: r.title, description: r.description, type: r.type,
+    state: r.state, assignee: r.assignee, priority: r.priority,
+    labels: JSON.parse(r.labels),
+    duplicateOf: r.duplicate_of, relatedTo: JSON.parse(r.related_to),
+    created_by: r.created_by, created_at: r.created_at, updated_at: r.updated_at,
+});
+const getRow = (db, projectId, id) => db.prepare("SELECT * FROM tickets WHERE id=? AND project_id=?").get(id, projectId);
+// "me" → the caller's actor (the per-agent attribution win); empty/whitespace → unassigned; else verbatim.
+const resolveAssignee = (actor, a) => a === undefined || a === null ? null
+    : a === "me" ? actor
+        : a.trim() === "" ? null
+            : a;
+// ─── DL-24 per-transition assignTo directive (mirror of server.ts) ─────────────
+const ownerHandleOf = (labels) => labels.includes("pm") ? "pm" : labels.includes("qa") ? "qa" : null;
+function loadTransitions(db, projectId) {
+    try {
+        const row = db.prepare("SELECT settings_json FROM projects WHERE id=?").get(projectId);
+        const tr = (row?.settings_json ? JSON.parse(row.settings_json) : {})?.workflow?.transitions;
+        return tr && typeof tr === "object" ? tr : {};
+    }
+    catch {
+        return {};
+    } // malformed config ⇒ absent (fail-open), never bricks a write
+}
+function resolveAssignTo(db, projectId, actor, from, to, labels) {
+    const dir = loadTransitions(db, projectId)[`${from}->${to}`];
+    if (!dir || dir.assignTo === undefined || dir.assignTo === null)
+        return null;
+    const v = dir.assignTo;
+    if (v === "owner") {
+        const o = ownerHandleOf(labels);
+        if (!o)
+            console.error(`[assignTo] ${from}->${to}: owner directive but ticket has no pm/qa label — assignee left untouched`);
+        return o;
+    }
+    if (v === "self")
+        return actor;
+    if (actorExists(db, v))
+        return v;
+    console.error(`[assignTo] ${from}->${to}: unknown handle '${v}' — assignee left untouched`);
+    return null;
+}
+// ─── DL-32 prod-promotion gate (mirror of server.ts) ───────────────────────────
+const ENV_LABELS = ["env:dev", "env:prod"];
+const envLabelsOf = (labels) => labels.filter((l) => ENV_LABELS.includes(l)).sort();
+function prodPromotionRejection(db, projectId, actor, oldLabels, newLabels) {
+    if (loadRelease(db, projectId).prodPromotionGate !== "human")
+        return null;
+    const adding = newLabels.includes("env:prod") && !oldLabels.includes("env:prod");
+    return adding && actor !== "operator"
+        ? `env:prod promotion is human-gated (prodPromotionGate:"human"): only the operator may add env:prod`
+        : null;
+}
+// ─── the 5 ops ─────────────────────────────────────────────────────────────────
+// Shared input-shape guard: a JSON array whose every element is a string — mirrors zod's z.array(z.string()).
+// The op-API parses raw JSON (no zod), so list_issues + save_issue both re-check `labels` by hand with this
+// (a non-array would crash a `[...]` spread or be JSON.stringify'd into the column → a 500); one definition the
+// two ops share so they can't drift (DL-65 hoisted opSaveIssue's original local helper to module scope).
+const isStrArr = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+function opListIssues(db, projectId, actor, a) {
+    // Re-validate the raw-JSON arg shapes the stdio path gets from zod (server.ts: query/assignee
+    // z.string().optional(), labels z.array(z.string()).optional()). Without this a non-string `query`
+    // (.toLowerCase() below), a non-array `labels` (the [...] spread below), or a non-string truthy `assignee`
+    // (resolveAssignee → .trim()) throws a TypeError → the daemon's catch → an HTTP 500 echoing the raw JS error,
+    // where the zod path returns a clean 400. Same guard class as opSaveIssue's labels / the doc-READ selectors
+    // (docSelectorErr, DL-63) — the last unguarded read op (DL-65). state/type/label are compared (never bound or
+    // method-called), so they keep today's behavior and need no guard.
+    if (a.query !== undefined && typeof a.query !== "string")
+        return errR(400, "query must be a string");
+    if (a.labels !== undefined && !isStrArr(a.labels))
+        return errR(400, "labels must be an array of strings");
+    if (a.assignee !== undefined && typeof a.assignee !== "string")
+        return errR(400, "assignee must be a string");
+    let out = db.prepare("SELECT * FROM tickets WHERE project_id=? ORDER BY updated_at DESC").all(projectId).map(toTicket);
+    if (a.state)
+        out = out.filter((t) => t.state === a.state);
+    if (a.assignee)
+        out = out.filter((t) => t.assignee === resolveAssignee(actor, a.assignee));
+    if (a.type)
+        out = out.filter((t) => t.type === a.type);
+    const want = [...(a.labels ?? []), ...(a.label ? [a.label] : [])];
+    if (want.length)
+        out = out.filter((t) => want.every((l) => t.labels.includes(l)));
+    if (a.query) {
+        const q = a.query.toLowerCase();
+        out = out.filter((t) => t.title.toLowerCase().includes(q) || t.description.toLowerCase().includes(q));
+    }
+    return okR(a.limit ? out.slice(0, a.limit) : out);
+}
+function opGetIssue(db, projectId, projectKey, a) {
+    if (a.id === undefined)
+        return errR(400, "id required"); // === undefined, NOT falsy: a zod-valid empty-string id ("" passes the bare z.string()) must fall through to the not-found lookup, byte-identical to the pre-DL-69 native handler; this guard exists only to stop an undefined → node:sqlite bind-crash
+    const r = getRow(db, projectId, a.id);
+    if (!r)
+        return errR(404, `no such ticket ${a.id} in ${projectKey}`);
+    const comments = db.prepare("SELECT id,author,body,created_at FROM comments WHERE ticket_id=? ORDER BY created_at").all(a.id);
+    return okR({ ...toTicket(r), comments });
+}
+// MIRRORS server.ts save_issue exactly: validate → create (insertTicket) OR update (atomic read-merge-write
+// under BEGIN IMMEDIATE: REPLACE labels, APPEND-only relatedTo union, DL-24 assignTo, DL-32 promo gate, the
+// DL-38 staging gate inside updateTicketRow, the issue.promote env event). `db` MUST be a WRITABLE connection.
+function opSaveIssue(db, projectId, projectKey, actor, a) {
+    // Input validation the stdio path gets from its zod schema (server.ts) — the op-API parses raw JSON, so it
+    // re-checks the SAME shapes by hand. The array fields are load-bearing: a non-array labels/relatedTo would
+    // be JSON.stringify'd into the column and later crash a `t.labels.includes()` / `[...]` spread (a 500
+    // poison-pill on every subsequent list_issues), so reject them up front — matching zod's array-of-strings.
+    if (a.labels !== undefined && !isStrArr(a.labels))
+        return errR(400, "labels must be an array of strings");
+    if (a.relatedTo !== undefined && !isStrArr(a.relatedTo))
+        return errR(400, "relatedTo must be an array of strings");
+    if (a.priority !== undefined && (typeof a.priority !== "number" || !Number.isInteger(a.priority) || a.priority < 0 || a.priority > 4))
+        return errR(400, `invalid priority; an integer 0..4`);
+    if (a.state && !STATES.includes(a.state))
+        return errR(400, `invalid state '${a.state}'; one of ${STATES.join(", ")}`);
+    if (a.assignee && a.assignee !== "me" && !actorExists(db, a.assignee))
+        return errR(400, `unknown assignee '${a.assignee}'; one of ${listActorHandles(db).join(", ")} (or "me"/null)`); // DL-69: the message is byte-identical to server.ts's (the single source) — agent-api.ts asserts only status 400
+    if (!a.id) {
+        if (!a.title)
+            return errR(400, "title required to create a ticket");
+        const promoReject = prodPromotionRejection(db, projectId, actor, [], a.labels ?? []);
+        if (promoReject)
+            return errR(403, promoReject);
+        const id = insertTicket(db, projectId, actor, { title: a.title, description: a.description ?? "", type: a.type ?? "Feature", state: a.state ?? "Todo",
+            assignee: resolveAssignee(actor, a.assignee), priority: a.priority ?? 0, labels: a.labels ?? [],
+            duplicateOf: a.duplicateOf ?? null, relatedTo: a.relatedTo ?? [] }, { title: a.title, type: a.type });
+        return okR(toTicket(getRow(db, projectId, id)));
+    }
+    // update — atomic read-merge-write (the APPEND-only relatedTo union must not lose a concurrent link).
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const cur = getRow(db, projectId, a.id);
+        if (!cur) {
+            db.exec("ROLLBACK");
+            return errR(404, `no such ticket ${a.id} in ${projectKey}`);
+        }
+        const next = {
+            title: a.title ?? cur.title, description: a.description ?? cur.description, type: a.type ?? cur.type,
+            state: a.state ?? cur.state,
+            assignee: a.assignee === undefined ? cur.assignee : resolveAssignee(actor, a.assignee),
+            priority: a.priority ?? cur.priority,
+            labels: a.labels ? JSON.stringify(a.labels) : cur.labels, // REPLACE-style (§10#1)
+            duplicate_of: a.duplicateOf === undefined ? cur.duplicate_of : a.duplicateOf, // scalar; undefined=keep
+            related_to: a.relatedTo // APPEND-only union (§18)
+                ? JSON.stringify([...new Set([...JSON.parse(cur.related_to), ...a.relatedTo])])
+                : cur.related_to,
+        };
+        if (next.state !== cur.state && a.assignee === undefined) { // DL-24 assignTo (implicit assignee only)
+            const resolved = resolveAssignTo(db, projectId, actor, cur.state, next.state, JSON.parse(next.labels));
+            if (resolved !== null)
+                next.assignee = resolved;
+        }
+        const oldLabels = JSON.parse(cur.labels), newLabels = JSON.parse(next.labels);
+        const promoReject = prodPromotionRejection(db, projectId, actor, oldLabels, newLabels); // DL-32 prod gate
+        if (promoReject) {
+            db.exec("ROLLBACK");
+            return errR(403, promoReject);
+        }
+        const wr = updateTicketRow(db, projectId, actor, a.id, cur.state, next); // DL-38 staging gate inside ⇒ may reject
+        if (!wr.ok) {
+            db.exec("ROLLBACK");
+            return errR(wr.status, wr.error);
+        }
+        const fromEnv = envLabelsOf(oldLabels).join(","), toEnv = envLabelsOf(newLabels).join(","); // DL-32 issue.promote on env change
+        if (fromEnv !== toEnv)
+            logEvent(db, { project_id: projectId, ticket_id: a.id, actor, kind: "issue.promote", data: { from: fromEnv, to: toEnv } });
+        db.exec("COMMIT");
+    }
+    catch (e) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* */ }
+        throw e;
+    }
+    return okR(toTicket(getRow(db, projectId, a.id)));
+}
+// `db` MUST be a WRITABLE connection (the comment INSERT + comment.add event go through insertComment).
+function opSaveComment(db, projectId, actor, a) {
+    if (a.issueId === undefined)
+        return errR(400, "issueId required"); // === undefined, NOT falsy (DL-69): a zod-valid empty-string issueId must fall through to the not-found lookup, byte-identical to the pre-refactor native handler
+    if (typeof a.body !== "string")
+        return errR(400, "body required");
+    if (!getRow(db, projectId, a.issueId))
+        return errR(404, `no such ticket ${a.issueId}`);
+    const { id, createdAt } = insertComment(db, projectId, actor, a.issueId, a.body);
+    return okR({ id, ticket_id: a.issueId, author: actor, body: a.body, created_at: createdAt });
+}
+function opListComments(db, projectId, projectKey, a) {
+    if (a.issueId === undefined)
+        return errR(400, "issueId required"); // === undefined, NOT falsy (DL-69): a zod-valid empty-string issueId must fall through to the not-found lookup, byte-identical to the pre-refactor native handler
+    if (!getRow(db, projectId, a.issueId))
+        return errR(404, `no such ticket ${a.issueId} in ${projectKey}`);
+    return okR(db.prepare("SELECT id,author,body,created_at FROM comments WHERE ticket_id=? ORDER BY created_at").all(a.issueId));
+}
+// ─── DL-62: the doc/event family (verbatim mirror of server.ts list_events + doc.* handlers) ──────
+// The doc READS + list_events are the SAME SELECTs server.ts runs (a JSON round-trip → byte-identical
+// to the stdio ok() body — the differential-parity tripwire). The doc WRITES delegate to the shared
+// docstore (docSave/docPublish), so the CAS + the single operator-publish gate live in ONE place.
+function opListEvents(db, projectId, a) {
+    // mirror server.ts's zod (limit: int 1..500) — the op-API parses raw JSON, so a bad limit must be a clean
+    // 400 here, never bound into LIMIT (a non-int bind throws in node:sqlite → a 500; an uncapped limit drifts).
+    if (a.limit !== undefined && (!Number.isInteger(a.limit) || a.limit <= 0 || a.limit > 500))
+        return errR(400, "limit must be an integer 1..500");
+    return okR(db.prepare("SELECT actor,kind,ticket_id,data,created_at FROM events WHERE project_id=? ORDER BY id DESC LIMIT ?").all(projectId, a.limit ?? 50));
+}
+// Mirror server.ts's zod (the doc tools' `slug`/`kind` are OPTIONAL STRINGS). The op-API parses raw JSON
+// with no zod, so a present-but-non-string slug/kind must 400 HERE — otherwise it binds into resolveDoc's
+// parameterized query and node:sqlite throws "Provided value cannot be bound" → an HTTP 500 echoing the raw
+// driver string (same class as opSaveIssue's non-array / opDocDiff's non-int guards, extended to the doc-READ
+// selectors — DL-63). Absent (undefined) is fine: a read selects by slug OR kind, and doc.list by neither.
+const docSelectorErr = (a) => a.slug !== undefined && typeof a.slug !== "string" ? "slug must be a string"
+    : a.kind !== undefined && typeof a.kind !== "string" ? "kind must be a string"
+        : null;
+function opDocList(db, projectId, a) {
+    const bad = docSelectorErr(a);
+    if (bad)
+        return errR(400, bad);
+    return okR(a.kind
+        ? db.prepare("SELECT id,kind,slug,title,status,current_version,created_by,updated_at FROM documents WHERE project_id=? AND kind=? ORDER BY kind").all(projectId, a.kind)
+        : db.prepare("SELECT id,kind,slug,title,status,current_version,created_by,updated_at FROM documents WHERE project_id=? ORDER BY kind").all(projectId));
+}
+function opDocGet(db, projectId, projectKey, a) {
+    const bad = docSelectorErr(a);
+    if (bad)
+        return errR(400, bad);
+    // mirror server.ts's zod (version: int>0, optional). Re-check by hand (no zod on the op-API path): an
+    // out-of-range version must 400 like the stdio path, not fall through to the version===0 empty-doc branch.
+    if (a.version !== undefined && (!Number.isInteger(a.version) || a.version <= 0))
+        return errR(400, "version must be a positive integer");
+    const d = resolveDoc(db, projectId, a.slug, a.kind);
+    if (!d)
+        return errR(404, `no document ${a.slug ?? a.kind} in ${projectKey}`);
+    const ver = a.version ?? (d.current_version > 0 ? d.current_version : latestVersion(db, d.id));
+    if (ver === 0)
+        return okR({ ...d, version: 0, body: "", unpublished: true, empty: true });
+    const v = db.prepare("SELECT version,body,status,summary,base_version,author,created_at FROM document_versions WHERE doc_id=? AND version=?").get(d.id, ver);
+    if (!v)
+        return errR(404, `no version ${ver} of ${d.slug}`);
+    return okR({ id: d.id, kind: d.kind, slug: d.slug, title: d.title, status: d.status, current_version: d.current_version, ...v, ...(d.current_version === 0 ? { unpublished: true } : {}) });
+}
+function opDocHistory(db, projectId, a) {
+    const bad = docSelectorErr(a);
+    if (bad)
+        return errR(400, bad);
+    const d = resolveDoc(db, projectId, a.slug, a.kind);
+    if (!d)
+        return errR(404, `no document ${a.slug ?? a.kind}`);
+    return okR(db.prepare("SELECT version,status,author,summary,base_version,created_at FROM document_versions WHERE doc_id=? ORDER BY version DESC").all(d.id));
+}
+function opDocDiff(db, projectId, a) {
+    const bad = docSelectorErr(a);
+    if (bad)
+        return errR(400, bad);
+    // from/to come from zod (int>0) on the stdio/shim path; the op-API parses raw JSON, so re-check by hand —
+    // a non-int bind would otherwise throw inside node:sqlite → a 500 instead of a clean 400 (opSaveIssue precedent).
+    if (!Number.isInteger(a.from) || a.from <= 0)
+        return errR(400, "from must be a positive integer");
+    if (!Number.isInteger(a.to) || a.to <= 0)
+        return errR(400, "to must be a positive integer");
+    const d = resolveDoc(db, projectId, a.slug, a.kind);
+    if (!d)
+        return errR(404, `no document ${a.slug ?? a.kind}`);
+    const body = (n) => db.prepare("SELECT body FROM document_versions WHERE doc_id=? AND version=?").get(d.id, n)?.body;
+    const fromBody = body(a.from), toBody = body(a.to);
+    if (fromBody === undefined || toBody === undefined)
+        return errR(404, `missing version (have up to ${latestVersion(db, d.id)})`);
+    return okR({ from: a.from, to: a.to, fromBody, toBody, unified: unifiedDiff(fromBody, toBody) });
+}
+// `db` MUST be a WRITABLE connection (docSave does BEGIN IMMEDIATE + INSERTs + a doc.save event). The CAS
+// (a stale baseVersion → CONFLICT, never last-write-wins) lives inside docSave, shared with server.ts.
+function opDocSave(db, projectId, actor, a) {
+    // re-validate the zod shapes the stdio/shim path enforces (slug/body required, kind ∈ DOC_KINDS, baseVersion int≥0)
+    if (typeof a.slug !== "string")
+        return errR(400, "slug required (a string)"); // type-only, NOT non-empty (DL-69): a zod-valid empty-string slug must reach docSave (which creates/handles it), byte-identical to the pre-refactor native handler; only undefined/non-string is rejected (the INSERT-bind guard)
+    if (typeof a.body !== "string")
+        return errR(400, "body required (a string)");
+    if (a.title !== undefined && typeof a.title !== "string")
+        return errR(400, "title must be a string"); // server.ts zod: title/summary optional strings — a non-string would bind into the INSERT → a 500
+    if (a.summary !== undefined && typeof a.summary !== "string")
+        return errR(400, "summary must be a string");
+    if (!Number.isInteger(a.baseVersion) || a.baseVersion < 0)
+        return errR(400, "baseVersion must be a non-negative integer");
+    if (!DOC_KINDS.includes(a.kind))
+        return errR(400, `invalid kind '${a.kind}'; one of ${DOC_KINDS.join(", ")}`);
+    const r = docSave(db, projectId, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForDocErr(r.error), r.error);
+}
+// `db` MUST be a WRITABLE connection (docPublish does BEGIN IMMEDIATE + UPDATEs + a doc.publish event). The
+// OPERATOR-only gate lives inside docPublish (shared with server.ts) — cooperative role-attribution, not
+// anti-spoof on one host (§18): only the actor the daemon resolved from X-Devloop-Actor as "operator" passes.
+function opDocPublish(db, projectId, actor, a) {
+    if (!Number.isInteger(a.version) || a.version <= 0)
+        return errR(400, "version must be a positive integer");
+    const r = docPublish(db, projectId, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForDocErr(r.error), r.error);
+}
+// ─── DL-64: the discussion-board family (topic.*/post.add) — thin op-API wrappers over the shared topicstore ──
+// Mirror the doc-family pattern: hand-validate the raw-JSON inputs to a clean 400 (server.ts gets these from
+// zod), then delegate to topicstore (which owns the §25 role gates + round/append rules); a TopicResult error
+// maps to its HTTP status via statusForTopicErr. The reads (topic.list/topic.get) take the query_only db; the
+// writes (topic.open/post.add/topic.synthesize/topic.close ∈ AGENT_WRITE_OPS) take writeDb — the daemon routes.
+function opTopicList(db, projectId, actor, a) {
+    if (a.status !== undefined && a.status !== "open" && a.status !== "closed")
+        return errR(400, `status must be "open" or "closed"`);
+    return okR(topicList(db, projectId, actor, a.status));
+}
+function opTopicGet(db, projectId, projectKey, a) {
+    if (typeof a.id !== "string")
+        return errR(400, "id must be a string");
+    const r = topicGet(db, projectId, projectKey, a.id);
+    return r.ok ? okR(r.data) : errR(statusForTopicErr(r.error), r.error);
+}
+function opTopicOpen(db, projectId, actor, a) {
+    if (typeof a.question !== "string" || !a.question)
+        return errR(400, "question required (a non-empty string)");
+    if (!isStrArr(a.invited) || a.invited.length === 0)
+        return errR(400, "invited required (a non-empty array of strings)");
+    const r = topicOpen(db, projectId, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForTopicErr(r.error), r.error);
+}
+function opPostAdd(db, projectId, projectKey, actor, a) {
+    if (typeof a.topicId !== "string")
+        return errR(400, "topicId must be a string");
+    if (typeof a.body !== "string" || !a.body)
+        return errR(400, "body required (a non-empty string)");
+    const r = postAdd(db, projectId, projectKey, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForTopicErr(r.error), r.error);
+}
+function opTopicSynthesize(db, projectId, projectKey, actor, a) {
+    if (typeof a.topicId !== "string")
+        return errR(400, "topicId must be a string");
+    if (typeof a.body !== "string" || !a.body)
+        return errR(400, "body required (a non-empty string)");
+    if (a.nextRound !== undefined && typeof a.nextRound !== "boolean")
+        return errR(400, "nextRound must be a boolean");
+    const r = topicSynthesize(db, projectId, projectKey, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForTopicErr(r.error), r.error);
+}
+function opTopicClose(db, projectId, projectKey, actor, a) {
+    if (typeof a.topicId !== "string")
+        return errR(400, "topicId must be a string");
+    if (typeof a.decision !== "string" || !a.decision)
+        return errR(400, "decision required (a non-empty string)");
+    const r = topicClose(db, projectId, projectKey, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForTopicErr(r.error), r.error);
+}
+// ─── DL-67: the IM channel family (channel.*) — thin op-API wrappers over the shared channelstore ──
+// Mirror the doc/topic pattern: hand-validate the raw-JSON inputs to a clean 400 (server.ts gets these from
+// zod — the DL-63 lesson), then delegate to channelstore (which owns the §16 line-build, the DL-4 roadmap
+// bridge, the per-process send cap, and the channels/channel_messages writes); a ChannelResult error maps to
+// its HTTP status via statusForChannelErr. channel.send/poll are ASYNC (network/dryrun) → they return Promises.
+// channel.status is the only READ (query_only db, not in AGENT_WRITE_OPS); the 4 writes take writeDb.
+function opChannelRegister(db, projectId, actor, a) {
+    if (a.provider !== "slack" && a.provider !== "lark")
+        return errR(400, `provider must be "slack" or "lark"`);
+    if (typeof a.configRef !== "string" || !a.configRef)
+        return errR(400, "configRef required (a non-empty string)");
+    if (a.secretRef !== undefined && typeof a.secretRef !== "string")
+        return errR(400, "secretRef must be a string");
+    if (typeof a.channelRef !== "string" || !a.channelRef)
+        return errR(400, "channelRef required (a non-empty string)");
+    const r = channelRegister(db, projectId, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForChannelErr(r.error), r.error);
+}
+// ASYNC (channelSend awaits sendVia / the DRYRUN build). Hand-validate the fields channelSend method-calls or
+// binds (a wrong type would 500): ticketId (a SELECT bind), text + digest.headline (cleanLine→.replace),
+// digest.openProposals (.slice/.map + cleanLine each). The numeric digest fields only feed template strings
+// (coerced), so they need no guard — parity with the doc-family numeric handling.
+async function opChannelSend(db, projectId, projectKey, actor, a) {
+    if (a.kind !== "notify" && a.kind !== "digest" && a.kind !== "reply")
+        return errR(400, `kind must be one of notify, digest, reply`);
+    if (a.ticketId !== undefined && typeof a.ticketId !== "string")
+        return errR(400, "ticketId must be a string");
+    if (a.text !== undefined && typeof a.text !== "string")
+        return errR(400, "text must be a string");
+    if (a.bailShape !== undefined && typeof a.bailShape !== "string")
+        return errR(400, "bailShape must be a string");
+    if (a.digest !== undefined) {
+        if (typeof a.digest !== "object" || a.digest === null || Array.isArray(a.digest))
+            return errR(400, "digest must be an object");
+        const d = a.digest;
+        if (d.headline !== undefined && typeof d.headline !== "string")
+            return errR(400, "digest.headline must be a string");
+        if (d.openProposals !== undefined && !isStrArr(d.openProposals))
+            return errR(400, "digest.openProposals must be an array of strings");
+    }
+    const r = await channelSend(db, projectId, projectKey, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForChannelErr(r.error), r.error);
+}
+// ASYNC (channelPoll awaits pollVia / the DRYRUN build + the DL-4 bridge). No input (the fixture rides env).
+async function opChannelPoll(db, projectId, projectKey, actor) {
+    const r = await channelPoll(db, projectId, projectKey, actor);
+    return r.ok ? okR(r.data) : errR(statusForChannelErr(r.error), r.error);
+}
+function opChannelAck(db, projectId, projectKey, actor, a) {
+    if (typeof a.messageId !== "string")
+        return errR(400, "messageId must be a string");
+    if (a.actedInto !== undefined && typeof a.actedInto !== "string")
+        return errR(400, "actedInto must be a string");
+    const r = channelAck(db, projectId, projectKey, actor, a);
+    return r.ok ? okR(r.data) : errR(statusForChannelErr(r.error), r.error);
+}
+function opChannelStatus(db, projectId) {
+    return okR(channelStatus(db, projectId)); // read; never origin/actor-gated upstream (parity with the read ticket/doc/topic ops)
+}
+// ─── DL-68: P7 mirror (mirror.push/mirror.status) + label/project (list_issue_labels/create_issue_label/
+//     get_project) — thin op-API wrappers over the shared mirrorstore/labelstore ──
+// Mirror the doc/topic/channel pattern: hand-validate the raw-JSON inputs to a clean 400 (server.ts gets these
+// from zod — the DL-63/DL-65 lesson), then delegate to the shared store. mirror.push / create_issue_label errors
+// are all client 400s (bad input / unset-or-literal token / DL-22 empty-name / bad-kind) — no 404/409 here, and
+// a failed Linear network call is counted in `failed`, never an op error. mirror.push is ASYNC (Linear network /
+// dryrun build) → it returns a Promise. The 3 reads take the query_only db (not in AGENT_WRITE_OPS).
+// ASYNC (mirrorPush awaits the Linear transport / the DRYRUN build). Hand-validate the shapes server.ts gets
+// from zod (teamId/tokenEnv non-empty strings, projectId optional string, stateMap an object, limit int 1..500)
+// so a bad type is a clean 400, never a node:sqlite bind-throw 500 or a crash inside mirrorPush.
+async function opMirrorPush(db, projectId, actor, a) {
+    if (typeof a.teamId !== "string" || !a.teamId)
+        return errR(400, "teamId required (a non-empty string)");
+    if (typeof a.tokenEnv !== "string" || !a.tokenEnv)
+        return errR(400, "tokenEnv required (a non-empty string)");
+    if (a.projectId !== undefined && typeof a.projectId !== "string")
+        return errR(400, "projectId must be a string");
+    if (a.stateMap !== undefined && (typeof a.stateMap !== "object" || a.stateMap === null || Array.isArray(a.stateMap)))
+        return errR(400, "stateMap must be an object");
+    if (a.limit !== undefined && (!Number.isInteger(a.limit) || a.limit < 1 || a.limit > 500))
+        return errR(400, "limit must be an integer 1..500");
+    const r = await mirrorPush(db, projectId, actor, a);
+    return r.ok ? okR(r.data) : errR(400, r.error); // §16-safe error (isEnvName / scrubErr inside mirrorstore); the token never appears
+}
+function opMirrorStatus(db, projectId) {
+    return okR(mirrorStatus(db, projectId)); // read; coverage counts, no secret, no Linear read
+}
+function opListLabels(db, projectId) {
+    return okR(listLabels(db, projectId)); // read
+}
+// `db` MUST be a WRITABLE connection. Validation (DL-22 empty-name + LABEL_KINDS) lives in the shared createLabel
+// so server.ts + the op-API can't drift. The attributed `label.create` event is logged HERE (the identity win).
+// DL-69 note: this is the ONE op server.ts does NOT dispatch through — its create_issue_label stays a native
+// createLabel call that logs NO event, so the stdio path stays byte-identical (routing it here would ADD that
+// event to stdio = new behavior, out of scope for a behavior-preserving refactor). Unifying that attribution
+// onto the stdio path is a deliberate behavior change for a follow-up; both paths return {name,kind} identically.
+function opCreateLabel(db, projectId, actor, a) {
+    if (typeof a.name !== "string")
+        return errR(400, "name required (a string)"); // server.ts zod: name z.string() — a non-string would crash createLabel's .trim()
+    if (a.kind !== undefined && typeof a.kind !== "string")
+        return errR(400, "kind must be a string");
+    const r = createLabel(db, projectId, a);
+    if (!r.ok)
+        return errR(400, r.error); // DL-22: empty-name / bad-kind → a clean 400, never a fake success with a dropped row
+    logEvent(db, { project_id: projectId, actor, kind: "label.create", data: { name: r.data.name, kind: r.data.kind } });
+    return okR(r.data);
+}
+function opGetProject(db, projectId) {
+    return okR(getProject(db, projectId)); // read
+}
+// Dispatch one op. `db` is the WRITABLE connection for the write ops (save_issue/save_comment) and may be
+// the daemon's query_only read connection for the read ops — the daemon passes the right one per op. `actor`
+// is already resolved+validated by the daemon (the G1 guard). `args` is the parsed JSON body (a non-object
+// body is normalized to {} by the caller). Throws only on a genuine DB fault (→ the daemon's 500 catch).
+export function agentOp(op, db, projectId, projectKey, actor, args) {
+    switch (op) {
+        case "list_issues": return opListIssues(db, projectId, actor, args);
+        case "get_issue": return opGetIssue(db, projectId, projectKey, args);
+        case "save_issue": return opSaveIssue(db, projectId, projectKey, actor, args);
+        case "save_comment": return opSaveComment(db, projectId, actor, args);
+        case "list_comments": return opListComments(db, projectId, projectKey, args);
+        case "list_events": return opListEvents(db, projectId, args);
+        case "doc.list": return opDocList(db, projectId, args);
+        case "doc.get": return opDocGet(db, projectId, projectKey, args);
+        case "doc.history": return opDocHistory(db, projectId, args);
+        case "doc.diff": return opDocDiff(db, projectId, args);
+        case "doc.save": return opDocSave(db, projectId, actor, args);
+        case "doc.publish": return opDocPublish(db, projectId, actor, args);
+        case "topic.list": return opTopicList(db, projectId, actor, args);
+        case "topic.get": return opTopicGet(db, projectId, projectKey, args);
+        case "topic.open": return opTopicOpen(db, projectId, actor, args);
+        case "post.add": return opPostAdd(db, projectId, projectKey, actor, args);
+        case "topic.synthesize": return opTopicSynthesize(db, projectId, projectKey, actor, args);
+        case "topic.close": return opTopicClose(db, projectId, projectKey, actor, args);
+        case "channel.register": return opChannelRegister(db, projectId, actor, args);
+        case "channel.send": return opChannelSend(db, projectId, projectKey, actor, args);
+        case "channel.poll": return opChannelPoll(db, projectId, projectKey, actor);
+        case "channel.ack": return opChannelAck(db, projectId, projectKey, actor, args);
+        case "channel.status": return opChannelStatus(db, projectId);
+        case "mirror.push": return opMirrorPush(db, projectId, actor, args);
+        case "mirror.status": return opMirrorStatus(db, projectId);
+        case "list_issue_labels": return opListLabels(db, projectId);
+        case "create_issue_label": return opCreateLabel(db, projectId, actor, args);
+        case "get_project": return opGetProject(db, projectId);
+    }
+}