@dyzsasd/dev-loop 0.22.0

package/dist/shim.js

@@ -0,0 +1,146 @@
+// dev-loop hub — P2 (DL-55): a THIN stdio MCP shim that proxies the 5 core ticket tools to the loopback
+// daemon's DL-43 agent op-API (POST /api/op/<op>) instead of opening hub.db directly. It is an OPT-IN
+// alternative entry to the default `node src/server.ts` (direct-db stdio), documented in config/mcp.example.json.
+//
+// WHY: the Vision's "daemon owns coordination — agents act through one running service". server.ts stays the
+// canonical direct-db transport (DL-43 AC: 100% untouched); this shim is the additive client that routes the
+// core ticket tools through the one running daemon. Identity rides env→header (design Decision #2/#5): the
+// shim reads its OWN DEVLOOP_ACTOR and forwards it as the X-Devloop-Actor header on the loopback HTTP call IT
+// makes — so the CLI never makes an authed HTTP call and the headless `claude -p` Authorization-header drop
+// (HUB-ARCHITECTURE §6) never touches identity.
+//
+// SCOPE: the 5 core ticket tools (list_issues/get_issue/save_issue/save_comment/list_comments) + a LOCAL
+// whoami (DL-55), PLUS (DL-62) the doc/event family — list_events + doc.list/get/history/diff/save/publish,
+// PLUS (DL-64) the discussion-board family — topic.list/get/open + post.add + topic.synthesize/close,
+// PLUS (DL-67) the IM channel family — channel.register/send/poll/ack/status, PLUS (DL-68) P7 mirror +
+// label/project — mirror.push/mirror.status + list_issue_labels/create_issue_label/get_project. That is the
+// FINAL slice: the shim now proxies ALL 29 server.ts tools — a 100% server.ts drop-in.
+// The shim holds NO SoR / NO ticket/doc/topic/channel/mirror logic (Decision #3): a pure thin client over the
+// op-API (which mirrors server.ts 1:1 via agentops.ts + the shared docstore/topicstore/channelstore/mirrorstore/labelstore).
+//
+// DL-85: the tool { name, description, inputSchema } registry is now SHARED from tooldefs.ts (registerTools),
+// so the names/schemas can no longer drift between this shim and server.ts by hand — the old "PARITY TRIPWIRE:
+// keep the copy byte-identical" convention is retired (the single source IS the guarantee). Each entrypoint
+// supplies only its handler factory (server.ts → dispatch; this shim → proxy below).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { request as httpRequest } from "node:http";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { resolveIdentity } from "./resolve-project.js";
+import { ok, err, registerTools } from "./tooldefs.js"; // DL-85: the ONE {name,description,inputSchema} registry + the shared ok()/err() + the McpResult type
+// ─── identity + project ──────────────────────────────────────────────────────
+// DL-85: the DEVLOOP_ACTOR + DEVLOOP_PROJECT/cwd resolution lives ONCE in resolve-project.ts (was re-derived
+// here AND in server.ts) — same rule, so the shim names the same per-project daemon runfile the direct-db
+// server would attribute writes to. (The shim ignores projectFromCwd — only server.ts's not-seeded error uses it.)
+const { actor: ACTOR, projectKey: PROJECT_KEY } = resolveIdentity();
+// ─── DL-41 lifecycle runfile path (REPLICATES daemon.ts lcDbPath/lcRunDir/lcRunfile, :959-961) ──────────────
+// The shim is a standalone thin client and must NOT import the 92KB daemon (DL-55 affected-area: NOT daemon.ts),
+// so it re-derives the stable runfile path convention here — this comment is the drift tripwire against
+// daemon.ts. runDir = DEVLOOP_RUN_DIR ?? dirname(DEVLOOP_HUB_DB ?? ~/.dev-loop/hub.db); file = daemon-<key>.json.
+const DB_PATH = process.env.DEVLOOP_HUB_DB ?? join(homedir(), ".dev-loop", "hub.db");
+const RUN_DIR = process.env.DEVLOOP_RUN_DIR ?? dirname(DB_PATH);
+const RUNFILE = join(RUN_DIR, `daemon-${PROJECT_KEY}.json`);
+// Resolve the daemon's loopback port WITHOUT hardcoding 8787 (folded critique #89): an explicit
+// DEVLOOP_HUB_PORT override wins (a foreground `npm run daemon` writes NO runfile; tests inject the in-process
+// port), else the DL-41 lifecycle runfile's recorded port. null ⇒ neither is available (→ a clear MCP error).
+// Re-read per call ON PURPOSE (not memoized): the DL-41 daemon can restart on a new port mid-session, and the
+// shim must follow the live runfile without itself restarting — a cached port would go stale → false ECONNREFUSED.
+function resolvePort() {
+    const envPort = process.env.DEVLOOP_HUB_PORT?.trim();
+    if (envPort) {
+        const n = Number(envPort);
+        if (Number.isInteger(n) && n > 0 && n < 65536)
+            return n;
+    }
+    try {
+        const info = JSON.parse(readFileSync(RUNFILE, "utf8"));
+        if (typeof info.port === "number" && Number.isInteger(info.port) && info.port > 0)
+            return info.port;
+    }
+    catch { /* no/garbled runfile → the daemon was not lifecycle-started here */ }
+    return null;
+}
+// ─── MCP result helpers + the McpResult type are imported from tooldefs.ts (DL-85 — one definition; a 2xx body ──
+// produces an IDENTICAL tool result to server.ts's stdio path because both use the SAME ok()/err()). ───────────
+// The two "can't reach a working op-API" failure modes get a CLEAR, actionable MCP error (DL-55 AC), never a
+// silent hang or an opaque 500. Loopback only (§16) — the shim only ever talks to 127.0.0.1.
+const daemonDown = (detail) => err(`dev-loop daemon for project '${PROJECT_KEY}' is not reachable on 127.0.0.1${detail}. Start it ` +
+    `(\`cd hub && DEVLOOP_PROJECT=${PROJECT_KEY} npm run daemon\`, or the DL-42 SessionStart hook runs ` +
+    `\`dev-loop-hub daemon up\`), or set DEVLOOP_HUB_PORT. This daemon-transport shim proxies to the loopback ` +
+    `op-API and needs the daemon running; the default \`node hub/src/server.ts\` entry needs no daemon.`);
+const opApiDormant = () => err(`dev-loop daemon is running but its agent op-API is dormant for project '${PROJECT_KEY}'. Opt in by setting ` +
+    `settings_json.hub.transport="daemon" (DL-43), or use the default direct-db entry \`node hub/src/server.ts\`.`);
+// ─── proxy one core op → POST http://127.0.0.1:<port>/api/op/<op> (X-Devloop-Actor: ACTOR), as the MCP shape ──
+// daemon {status,body}: a 2xx → ok(body) (identical to server.ts's ok()); a DORMANT-mount 404 (body
+// {error:"not found: …"}) → the dormant hint; any other non-2xx → err(body.error) (a genuine op result —
+// 400/403/404-not-found/500 forwarded verbatim, parity with the stdio path); a dead/absent daemon (no
+// runfile / ECONNREFUSED / timeout) → the daemon-down hint.
+function proxy(op, args) {
+    const port = resolvePort();
+    if (port === null) {
+        return Promise.resolve(daemonDown(` (no lifecycle runfile at ${RUNFILE}, and DEVLOOP_HUB_PORT is unset)`));
+    }
+    const body = JSON.stringify(args ?? {});
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (r) => { if (!settled) {
+            settled = true;
+            resolve(r);
+        } };
+        const req = httpRequest({
+            hostname: "127.0.0.1", port, method: "POST", path: `/api/op/${op}`,
+            headers: {
+                "content-type": "application/json",
+                "content-length": Buffer.byteLength(body),
+                "x-devloop-actor": ACTOR, // identity env→header (Decision #2/#5) — the only attribution the daemon trusts
+            },
+        }, (res) => {
+            let d = "";
+            res.setEncoding("utf8");
+            res.on("data", (c) => (d += c));
+            res.on("end", () => {
+                const status = res.statusCode ?? 0;
+                let parsed = null;
+                try {
+                    parsed = d ? JSON.parse(d) : null;
+                }
+                catch { /* non-JSON body (a bare daemon error) */ }
+                if (status >= 200 && status < 300) {
+                    finish(ok(parsed));
+                    return;
+                }
+                const emsg = typeof parsed?.error === "string" ? parsed.error : "";
+                // A dormant mount answers EVERY /api/op/* with 404 {error:"not found: <path>"} (daemon.ts:759),
+                // distinct from a genuine op-level 404 ({error:"no such ticket …"}) which is a real result to forward.
+                if (status === 404 && (parsed === null || /^not found:/.test(emsg))) {
+                    finish(opApiDormant());
+                    return;
+                }
+                finish(err(emsg || `op '${op}' failed: HTTP ${status}`));
+            });
+        });
+        req.on("error", (e) => {
+            const why = e.code === "ECONNREFUSED" ? " (connection refused — a stale runfile / a daemon that died?)"
+                : e.message === "timeout" ? " (no response within 30s — the daemon hung?)"
+                    : ` (${e.code ?? e.message})`;
+            finish(daemonDown(why));
+        });
+        req.setTimeout(30000, () => { req.destroy(new Error("timeout")); }); // never a silent hang
+        req.end(body);
+    });
+}
+// ─── the MCP server — the SAME 29 tool names/schemas as server.ts (a 100% drop-in transport, DL-85) ──────────
+const server = new McpServer({ name: "dev-loop-hub", version: "0.1.0" });
+// tooldefs.ts owns every tool's { name, description, inputSchema } (shared with server.ts); the shim supplies
+// ONLY the handler. whoami is answered LOCALLY from env + cwd-resolution (so it works even when the daemon is
+// down) and reports the daemon transport + resolved URL; every other tool proxies to the loopback op-API.
+registerTools(server, (name) => {
+    if (name === "whoami") {
+        return () => { const port = resolvePort(); return ok({ actor: ACTOR, project: PROJECT_KEY, transport: "daemon", url: port ? `http://127.0.0.1:${port}` : null }); };
+    }
+    return (a) => proxy(name, a);
+});
+await server.connect(new StdioServerTransport());
+console.error(`[shim] dev-loop-hub daemon-transport shim ready: actor=${ACTOR} project=${PROJECT_KEY} runfile=${RUNFILE}`);

package/dist/ticketwrite.js

@@ -0,0 +1,147 @@
+// dev-loop hub — the single home for ticket/comment writes (DL-29 daemon routes + DL-35 server.ts convergence).
+// EVERY ticket INSERT/UPDATE and comment INSERT in the hub lives here (grep: no other src file writes the
+// tickets/comments tables). Two callers share these:
+//   • the MCP server (server.ts save_issue/save_comment) — the agent write path; it computes its own merge
+//     (REPLACE labels, APPEND-only relatedTo, DL-24 assignTo) inside its own BEGIN IMMEDIATE txn, then calls
+//     the raw mechanics below to do the write + log the event.
+//   • the daemon's opt-in human web-write routes (create/comment/move/assign) — the board write path; the
+//     narrow primitives (createTicket/addComment/moveTicket/assignTicket) wrap the same mechanics.
+// The mechanics take a WRITABLE connection (NEVER the daemon's query_only read connection) and the caller's
+// resolved actor. Attribution + the event-log discipline (logEvent) + the unknown-assignee guard
+// (actorExists) + the state set (STATES) are uniform across both paths by construction.
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { nowIso, nextTicketId, logEvent, actorExists, STATES } from "./db.js";
+const exists = (db, projectId, id) => !!db.prepare("SELECT 1 FROM tickets WHERE id=? AND project_id=?").get(id, projectId);
+const rowFor = (db, projectId, id) => db.prepare("SELECT title,description,type,state,assignee,priority,labels,duplicate_of,related_to FROM tickets WHERE id=? AND project_id=?")
+    .get(id, projectId);
+// Read settings_json.workflow.release fresh (a live, operator-set, opt-in config). Malformed ⇒ {} (fail-open).
+export function loadRelease(db, projectId) {
+    try {
+        const row = db.prepare("SELECT settings_json FROM projects WHERE id=?").get(projectId);
+        const r = (row?.settings_json ? JSON.parse(row.settings_json) : {})?.workflow?.release;
+        return r && typeof r === "object" ? r : {};
+    }
+    catch {
+        return {};
+    } // never brick a write on malformed config
+}
+// DL-38 staging-deploy gate (design §7). Enforced in updateTicketRow below — the shared write path — so it
+// covers BOTH the MCP save_issue transition AND the daemon board-move automatically. The In Progress → In
+// Review transition is REJECTED when requireDeployBeforeReview is on AND the ticket's repo deploys (its
+// repo:<name> ∈ deployRepos, or single-repo hasDeploy) AND it lacks env:dev. A non-deploying repo bypasses
+// (carve-out — else docs-only/no-deploy work could never earn env:dev and would deadlock). No ACTOR context.
+function stagingDeployRejection(db, projectId, fromState, next) {
+    if (!(fromState === "In Progress" && next.state === "In Review"))
+        return null; // only this edge is gated
+    const rel = loadRelease(db, projectId);
+    if (rel.requireDeployBeforeReview !== true)
+        return null; // default off ⇒ unchanged behavior
+    const labels = JSON.parse(next.labels);
+    const repoLabel = labels.find((l) => l.startsWith("repo:"));
+    const repoDeploys = repoLabel
+        ? Array.isArray(rel.deployRepos) && rel.deployRepos.includes(repoLabel.slice(5))
+        : rel.hasDeploy === true; // single-repo (no repo:<name> label)
+    if (!repoDeploys)
+        return null; // carve-out: a non-deploying repo never needs env:dev (no deadlock)
+    if (labels.includes("env:dev"))
+        return null; // gate satisfied — staged
+    return `staging-deploy gate: In Progress → In Review requires env:dev (this repo deploys and requireDeployBeforeReview is on)`;
+}
+// DL-77 verify gate (the Ralph-Wiggum guard). Enforced in updateTicketRow below — the SAME single-choke-point
+// placement as stagingDeployRejection — so it covers BOTH the MCP save_issue transition AND the daemon board-move
+// automatically. The maker-self-accept edge In Progress → Done is REJECTED: Done is the OWNER's verdict and must
+// be reached via In Review (owner verification). Every OTHER path to Done stays legal — In Review → Done (the
+// verified close), Todo → Done / Backlog → Done (the §9a intake parent-close, which MUST stay legal or it breaks
+// PM's grooming), and In Progress → Canceled/Duplicate (terminal, NOT Done). Unlike the DL-38 gate this is
+// UNCONDITIONAL (no opt-in config): "Done means verified" is a §3 loop invariant, not an operator preference.
+function verifyGateRejection(fromState, next) {
+    if (fromState === "In Progress" && next.state === "Done")
+        return `verify gate: In Progress → Done is not allowed — Done must be reached via In Review (owner verification); move to In Review first`;
+    return null; // every other transition is the caller's concern
+}
+// ─── the raw mechanics: the ONLY tickets/comments writers in the hub ──────────
+// THE ticket INSERT. Allocates the id, writes all 14 columns, logs issue.create. `createEventData` is passed
+// in so each caller logs exactly what it logged before this convergence (the MCP path logs the RAW {title,type}
+// — type possibly undefined when omitted — which differs from the resolved type written to the row).
+export function insertTicket(db, projectId, actor, f, createEventData) {
+    const id = nextTicketId(db, projectId);
+    const t = nowIso();
+    db.prepare(`INSERT INTO tickets(id,project_id,title,description,type,state,assignee,priority,labels,duplicate_of,related_to,created_by,created_at,updated_at)
+              VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+        .run(id, projectId, f.title, f.description, f.type, f.state, f.assignee, f.priority, JSON.stringify(f.labels), f.duplicateOf, JSON.stringify(f.relatedTo), actor, t, t);
+    logEvent(db, { project_id: projectId, ticket_id: id, actor, kind: "issue.create", data: createEventData });
+    return id;
+}
+// THE ticket UPDATE — the post-DL-35 converged "applyTicketWrite" path. Enforces the transition gates FIRST
+// (the DL-38 staging-deploy gate + the DL-77 verify gate — so both the MCP save_issue transition and the daemon
+// board-move are covered automatically), then writes the caller-merged `next` row and logs issue.transition (with the resolved assignee) on a real
+// state change else issue.update. TXN-AGNOSTIC: it never BEGINs/COMMITs — the MCP's atomic read-merge-write
+// txn (and the daemon's single-op writes) stay the caller's concern; a gate rejection writes NOTHING.
+export function updateTicketRow(db, projectId, actor, id, fromState, next) {
+    const gate = stagingDeployRejection(db, projectId, fromState, next) ?? verifyGateRejection(fromState, next);
+    if (gate)
+        return { ok: false, status: 400, error: gate };
+    const t = nowIso();
+    db.prepare(`UPDATE tickets SET title=?,description=?,type=?,state=?,assignee=?,priority=?,labels=?,duplicate_of=?,related_to=?,updated_at=? WHERE id=? AND project_id=?`)
+        .run(next.title, next.description, next.type, next.state, next.assignee, next.priority, next.labels, next.duplicate_of, next.related_to, t, id, projectId);
+    logEvent(db, next.state !== fromState
+        ? { project_id: projectId, ticket_id: id, actor, kind: "issue.transition", data: { from: fromState, to: next.state, assignee: next.assignee } }
+        : { project_id: projectId, ticket_id: id, actor, kind: "issue.update", data: {} });
+    return { ok: true, id };
+}
+// THE comment INSERT. Mechanic only — existence/body policy is the caller's. Returns the new id + timestamp
+// (the MCP echoes them back to the caller). Body is operator/agent DATA — stored verbatim, esc()'d at render
+// (never a command-verb parser, never a channel scrub).
+export function insertComment(db, projectId, actor, ticketId, body) {
+    const id = randomUUID();
+    const t = nowIso();
+    db.prepare("INSERT INTO comments(id,ticket_id,author,body,created_at) VALUES (?,?,?,?,?)").run(id, ticketId, actor, body, t);
+    logEvent(db, { project_id: projectId, ticket_id: ticketId, actor, kind: "comment.add", data: {} });
+    return { id, createdAt: t };
+}
+// ─── daemon human-write primitives: narrow wrappers over the mechanics above ──
+// Create a Todo ticket (no labels/assignee by default — a human can move/assign/label it after).
+export function createTicket(db, projectId, actor, a) {
+    const title = (a.title ?? "").trim();
+    if (!title)
+        return { ok: false, status: 400, error: "title required" };
+    const type = a.type ?? "Feature";
+    const id = insertTicket(db, projectId, actor, { title, description: a.description ?? "", type, state: "Todo", assignee: null, priority: 0, labels: [], duplicateOf: null, relatedTo: [] }, { title, type });
+    return { ok: true, id };
+}
+// Add a comment (author = actor). A web form must not post an empty body → 400 (the MCP agent path does not
+// enforce this; the guard is the daemon's policy, the INSERT mechanic is shared).
+export function addComment(db, projectId, actor, id, body) {
+    if (!exists(db, projectId, id))
+        return { ok: false, status: 404, error: `no such ticket ${id}` };
+    if (!(body ?? "").trim())
+        return { ok: false, status: 400, error: "comment body required" };
+    insertComment(db, projectId, actor, id, body);
+    return { ok: true, id };
+}
+// Move a ticket to a new state. Honors the STATES set (the tickets.state CHECK's mirror) — an unknown state is
+// rejected, never written. A deliberate single-field intent: it reads the row and rewrites it with only `state`
+// changed (so the shared UPDATE mechanic does the write). Does NOT apply the DL-24 assignTo directive — a human
+// board move is an explicit state set (that directive is the agent save_issue path's).
+export function moveTicket(db, projectId, actor, id, toState) {
+    if (!STATES.includes(toState))
+        return { ok: false, status: 400, error: `invalid state '${toState}'; one of ${STATES.join(", ")}` };
+    const cur = rowFor(db, projectId, id);
+    if (!cur)
+        return { ok: false, status: 404, error: `no such ticket ${id}` };
+    return updateTicketRow(db, projectId, actor, id, cur.state, { ...cur, state: toState }); // propagates the DL-38 gate
+}
+// Assign (or unassign) a ticket. Empty/whitespace → unassigned (null); a non-empty handle must be a known actor
+// (mirrors the MCP unknown-assignee guard) — no "me" alias here (a web form names a handle). Reads the row and
+// rewrites it with only `assignee` changed (state unchanged ⇒ the shared mechanic logs issue.update).
+export function assignTicket(db, projectId, actor, id, assignee) {
+    const cur = rowFor(db, projectId, id);
+    if (!cur)
+        return { ok: false, status: 404, error: `no such ticket ${id}` };
+    const raw = (assignee ?? "").trim();
+    const resolved = raw === "" ? null : raw;
+    if (resolved !== null && !actorExists(db, resolved))
+        return { ok: false, status: 400, error: `unknown assignee '${resolved}'` };
+    return updateTicketRow(db, projectId, actor, id, cur.state, { ...cur, assignee: resolved }); // assignee-only ⇒ no transition ⇒ gate never fires
+}

package/dist/tooldefs.js

@@ -0,0 +1,147 @@
+// dev-loop hub — the SINGLE source of the MCP tool surface (DL-85). Before this, server.ts (direct-db) and
+// shim.ts (daemon-transport) each copy-pasted all 29 `registerTool(name, {description, inputSchema}, handler)`
+// triples byte-identically; the only per-file difference is the handler (dispatch vs proxy). Here the 29
+// {name, description, inputSchema} triples live ONCE; each entrypoint calls registerTools() and supplies only
+// its per-name handler factory. The ok()/err() MCP-result helpers are shared from here too.
+//
+// THIN-CLIENT BOUNDARY: this is a LEAF — it imports only `zod` + the DOC_KINDS enum (docstore.ts, already in
+// the shim's graph). It must NEVER import agentops.ts / the SoR (that would drag the whole system of record into
+// the thin shim). The op-name list is OWNED here (TOOL_NAMES); agentops.ts DERIVES AGENT_OPS from it (reuse,
+// not a 2nd copy) — so the name list lives in exactly one place AND the shim stays thin.
+import { z } from "zod";
+import { DOC_KINDS } from "./docstore.js"; // the doc-kind enum for doc.save's zod schema (a shared schema constant, not SoR/doc logic)
+export const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data) }] });
+export const err = (message) => ({ isError: true, content: [{ type: "text", text: JSON.stringify({ error: message }) }] });
+// ─── the canonical tool-name list — whoami (answered locally per transport) + the 28 op-backed tools ────────
+// agentops.ts derives AGENT_OPS = TOOL_NAMES minus "whoami" (the only tool that is NOT an op-API op), so this
+// is the ONE source of the tool/op names. Order matches the historical AGENT_OPS order (registration order is
+// irrelevant to MCP — tools resolve by name — but keeping it stable keeps diffs/feeds readable).
+export const TOOL_NAMES = [
+    "whoami",
+    "list_issues", "get_issue", "save_issue", "save_comment", "list_comments",
+    "list_events", "doc.list", "doc.get", "doc.history", "doc.diff", "doc.save", "doc.publish",
+    "topic.list", "topic.get", "topic.open", "post.add", "topic.synthesize", "topic.close",
+    "channel.register", "channel.send", "channel.poll", "channel.ack", "channel.status",
+    "mirror.push", "mirror.status", "list_issue_labels", "create_issue_label", "get_project",
+];
+// ─── the {description, inputSchema} for every tool — the ONE definition (was copy-pasted in BOTH entrypoints) ──
+const DEFS = {
+    whoami: { description: "The identity this session is acting as, and the active project.", inputSchema: {} },
+    list_issues: {
+        description: "List tickets in the active project. Filter by state, assignee, type, label(s), or a title query.",
+        inputSchema: {
+            state: z.string().optional(), assignee: z.string().optional(), type: z.string().optional(),
+            label: z.string().optional(), labels: z.array(z.string()).optional(), query: z.string().optional(),
+            limit: z.number().int().positive().max(250).optional(),
+        },
+    },
+    get_issue: { description: "Get one ticket with its comments.", inputSchema: { id: z.string() } },
+    save_issue: {
+        description: "Create (omit id) or update (with id) a ticket. labels REPLACE the full set (re-pass all). assignee 'me' = you, null clears.",
+        inputSchema: {
+            id: z.string().optional(), title: z.string().optional(), description: z.string().optional(),
+            type: z.string().optional(), state: z.string().optional(),
+            assignee: z.string().nullable().optional(), priority: z.number().int().min(0).max(4).optional(),
+            labels: z.array(z.string()).optional(),
+            duplicateOf: z.string().nullable().optional(), // §8 dedupe scalar (pair with state Duplicate); undefined=keep
+            relatedTo: z.array(z.string()).optional(), // §4 splits / §15 coverage; APPEND-ONLY union (§18 line 965)
+        },
+    },
+    save_comment: { description: "Add a comment to a ticket (authored as you).", inputSchema: { issueId: z.string(), body: z.string() } },
+    list_comments: { description: "List a ticket's comments (chronological; the tail is the latest).", inputSchema: { issueId: z.string() } },
+    list_issue_labels: { description: "List the project's labels.", inputSchema: {} },
+    create_issue_label: { description: "Create a label if missing (idempotent).", inputSchema: { name: z.string(), kind: z.string().optional() } },
+    get_project: { description: "The active project.", inputSchema: {} },
+    list_events: { description: "Recent attribution/audit events (who did what).", inputSchema: { limit: z.number().int().positive().max(500).optional() } },
+    "doc.list": { description: "List this project's documents (no bodies).", inputSchema: { kind: z.string().optional() } },
+    "doc.get": {
+        description: "Get a document by slug or kind. Omit version → the published (current) version; if never published, the latest DRAFT with unpublished:true. version=N → that historical version.",
+        inputSchema: { slug: z.string().optional(), kind: z.string().optional(), version: z.number().int().positive().optional() },
+    },
+    "doc.save": {
+        description: "Create (baseVersion 0) or append a new DRAFT version. Optimistic CAS: baseVersion MUST equal the doc's latest version, else CONFLICT (never last-write-wins). NEVER publishes — only the operator can (doc.publish).",
+        inputSchema: { slug: z.string(), kind: z.enum(DOC_KINDS), title: z.string().optional(), body: z.string(), baseVersion: z.number().int().min(0), summary: z.string().optional() },
+    },
+    "doc.history": { description: "A document's version ledger (no bodies; newest first).", inputSchema: { slug: z.string().optional(), kind: z.string().optional() } },
+    "doc.diff": { description: "Line diff between two versions of a document.", inputSchema: { slug: z.string().optional(), kind: z.string().optional(), from: z.number().int().positive(), to: z.number().int().positive() } },
+    "doc.publish": {
+        description: "OPERATOR-ONLY: publish a draft version → current (the live doc). Cooperative role-gate (DEVLOOP_ACTOR=operator), not anti-spoof — see §18/HUB-ARCHITECTURE §16.",
+        inputSchema: { slug: z.string().optional(), kind: z.string().optional(), version: z.number().int().positive() },
+    },
+    "topic.open": {
+        description: "Open a discussion topic (the caller becomes the chair = opened_by). invited = actor handles asked to post a perspective. Director-style use; any actor may chair its own topics.",
+        inputSchema: { question: z.string().min(1), invited: z.array(z.string()).min(1) },
+    },
+    "topic.list": {
+        description: "List discussion topics (no post bodies). Each row carries the current round, round_opened_at, and YOUR/the invited set's `pending` for this round (who still owes a perspective).",
+        inputSchema: { status: z.enum(["open", "closed"]).optional() },
+    },
+    "topic.get": { description: "A topic + all its posts (perspectives + the chair's synthesis), oldest first.", inputSchema: { id: z.string() } },
+    "post.add": {
+        description: "Post YOUR perspective to an OPEN topic you're invited to — once per round, your lane only (attributed to DEVLOOP_ACTOR). Append-only; you never edit/synthesize/close.",
+        inputSchema: { topicId: z.string(), body: z.string().min(1) },
+    },
+    "topic.synthesize": {
+        description: "CHAIR-ONLY (ACTOR === opened_by): write a synthesis post at the current round, optionally bumping to the next round (resets the round clock). Does NOT close — use topic.close to record the decision.",
+        inputSchema: { topicId: z.string(), body: z.string().min(1), nextRound: z.boolean().optional() },
+    },
+    "topic.close": {
+        description: "CHAIR-ONLY (ACTOR === opened_by): close the topic with a terminal decision. The decision is DATA (a recorded conclusion) — it NEVER auto-applies a code/SKILL/conventions change (§17).",
+        inputSchema: { topicId: z.string(), decision: z.string().min(1) },
+    },
+    "channel.register": {
+        description: "Idempotently register/update this project's IM channel from config. Stores ONLY the ENV-VAR NAMES (configRef = bot token / lark app_id; secretRef = lark app_secret) + the room id — NEVER a token/secret.",
+        inputSchema: { provider: z.enum(["slack", "lark"]), configRef: z.string().min(1), secretRef: z.string().optional(), channelRef: z.string().min(1) },
+    },
+    "channel.send": {
+        description: "Send a §16 allow-listed message to the project's IM channel. STRUCTURED only — never free-form. notify/digest are fully allow-listed (ids + counts); reply.text / digest.headline are bounded + control-stripped (cooperative §16). The token NEVER crosses this boundary.",
+        inputSchema: {
+            kind: z.enum(["notify", "digest", "reply"]),
+            ticketId: z.string().optional(),
+            bailShape: z.enum(["info-needed", "decision-needed", "scope-design", "external-prereq", "fix-exhausted"]).optional(),
+            digest: z.object({
+                topicsChaired: z.number().int().min(0).max(99).optional(),
+                decisionsClosed: z.number().int().min(0).max(99).optional(),
+                roadmapDraftVersion: z.number().int().min(0).nullable().optional(),
+                openProposals: z.array(z.string()).max(20).optional(),
+                throughput: z.object({ done: z.number().int().min(0), inReview: z.number().int().min(0), todo: z.number().int().min(0) }).partial().optional(),
+                headline: z.string().max(200).optional(),
+            }).optional(),
+            replyTo: z.string().optional(),
+            text: z.string().max(800).optional(),
+        },
+    },
+    "channel.poll": {
+        description: "Read NEW operator messages since the hub cursor (the no-daemon inbound), ingest them, AUTO-HANDLE roadmap commands (a §16-safe summary reply, or an edit → a roadmap DRAFT via doc.save; never published — DL-4), and return the remaining pending inbox (acted=0). TWO-PHASE: the provider fetch holds NO db lock; only the dedup-insert + cursor-advance is in BEGIN IMMEDIATE (roadmap handling runs AFTER, outside the lock). Inbound text is DATA — author is an UNVERIFIED provider id, NEVER operator authority (§16). GCs acted inbox rows >14d.",
+        inputSchema: {},
+    },
+    "channel.ack": {
+        description: "Mark an inbound operator message CONSUMED (the Director acted — opened a topic / filed a ticket / answered). actedInto = the hub artifact id (topic/ticket) for provenance.",
+        inputSchema: { messageId: z.string(), actedInto: z.string().optional() },
+    },
+    "channel.status": {
+        description: "Channel config + cursor + inbox depth. Returns the ENV-VAR NAMES and whether they are SET (boolean), NEVER the secret values.",
+        inputSchema: {},
+    },
+    "mirror.push": {
+        description: "ONE-WAY push: project hub tickets → Linear issues (create-or-update, idempotent + incremental — an unchanged ticket is skipped by content hash). The hub NEVER reads Linear as truth; a human Linear edit is overwritten. `tokenEnv` is the env-var NAME (the §16 secret is read server-side). A missing stateMap entry ⇒ no stateId (state stays in the body; never fails the push). DRYRUN returns the would-push ops, no network.",
+        inputSchema: {
+            teamId: z.string().min(1),
+            tokenEnv: z.string().min(1),
+            projectId: z.string().optional(),
+            stateMap: z.record(z.string(), z.string()).optional(), // hub State → Linear state id
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+    },
+    "mirror.status": { description: "Mirror coverage: mapped tickets, total tickets, last push time. No secret, no Linear read.", inputSchema: {} },
+};
+export function registerTools(server, makeHandler) {
+    for (const name of TOOL_NAMES) {
+        const def = DEFS[name];
+        if (!def)
+            throw new Error(`tooldefs: missing definition for tool '${name}'`); // can't happen (DEFS is keyed by ToolName) — a boot tripwire if a name is ever added without a def
+        // `as never` bridges our concrete ToolHandler to registerTool's per-schema ToolCallback generic (the parsed
+        // args are forwarded verbatim to the handler, exactly as the pre-refactor inline handlers received them).
+        server.registerTool(name, { description: def.description, inputSchema: def.inputSchema }, makeHandler(name));
+    }
+}

package/dist/topicstore.js

@@ -0,0 +1,174 @@
+// Shared discussion-board (P5/§25) store — the topic/post read+write logic + the two cooperative role
+// gates, used by BOTH the MCP server (server.ts) and the read+write daemon op-API (agentops.ts, DL-64).
+// SIDE-EFFECT-FREE (no env read, no transport, no top-level db) so either entrypoint can import it; identity
+// (actor) and scope (projectId/projectKey) are passed in by the caller — exactly the docstore.ts precedent
+// that lets the stdio server and the daemon op-API share ONE implementation and never drift.
+//
+// §17 firewall (structural): every write here is an INSERT/UPDATE on the `topics` / `posts` tables (a CHECKed
+// `kind` enum {perspective,synthesis}, db.ts) — there is NO filesystem path anywhere in this module, so a
+// board write can never target a SKILL / conventions / code file. A discussion DECISION (topic.close) is DATA,
+// never an auto-applied change. The two role gates live here ONCE so the two callers can't diverge on them:
+//   • chair-gate   = actor === topic.opened_by  (only the chair synthesizes/closes)
+//   • invited-gate = actor ∈ topic.invited      (your-lane: post only AS yourself, once per round)
+// Both are cooperative single-host attribution (§18 / HUB-ARCHITECTURE §16), not anti-spoof.
+import { randomUUID } from "node:crypto";
+import { nowIso, logEvent, actorExists, listActorHandles } from "./db.js";
+// Map a topicstore error message (prose, not codes) to an HTTP status, mirroring statusForDocErr: the role
+// gate → 403, a missing topic → 404, a state/dup conflict (closed / already posted / already synthesized /
+// stale) → 409, else a create-precondition (an unknown invited handle) → 400.
+export const statusForTopicErr = (msg) => msg.startsWith("FORBIDDEN") ? 403
+    : /^no topic\b/.test(msg) ? 404
+        : (msg.startsWith("CONFLICT") || /^already /.test(msg)) ? 409
+            : 400;
+const getTopic = (db, projectId, id) => db.prepare("SELECT * FROM topics WHERE id=? AND project_id=?").get(id, projectId);
+const pendingFor = (db, t) => {
+    const invited = JSON.parse(t.invited);
+    const answered = new Set(db.prepare("SELECT author FROM posts WHERE topic_id=? AND round=? AND kind='perspective'").all(t.id, t.round)
+        .map((r) => r.author));
+    return invited.filter((h) => !answered.has(h));
+};
+// ── reads (shaped HERE so server.ts and the op-API return byte-identical bodies — the parity tripwire) ──
+// topic.list row: …invited, pending, youArePending (per-actor). topic.get adds posts and omits youArePending.
+export function topicList(db, projectId, actor, status) {
+    const rows = (status
+        ? db.prepare("SELECT * FROM topics WHERE project_id=? AND status=? ORDER BY opened_at DESC").all(projectId, status)
+        : db.prepare("SELECT * FROM topics WHERE project_id=? ORDER BY opened_at DESC").all(projectId));
+    return rows.map((t) => {
+        const pending = t.status === "open" ? pendingFor(db, t) : [];
+        return {
+            id: t.id, question: t.question, status: t.status, round: t.round, round_opened_at: t.round_opened_at,
+            opened_by: t.opened_by, opened_at: t.opened_at, closed_at: t.closed_at, decision: t.decision,
+            invited: JSON.parse(t.invited), pending, youArePending: pending.includes(actor),
+        };
+    });
+}
+export function topicGet(db, projectId, projectKey, id) {
+    const t = getTopic(db, projectId, id);
+    if (!t)
+        return { ok: false, error: `no topic ${id} in ${projectKey}` };
+    const posts = db.prepare("SELECT round,author,kind,body,created_at FROM posts WHERE topic_id=? ORDER BY round, created_at").all(id);
+    return { ok: true, data: {
+            id: t.id, question: t.question, status: t.status, round: t.round, round_opened_at: t.round_opened_at,
+            opened_by: t.opened_by, opened_at: t.opened_at, closed_at: t.closed_at, decision: t.decision,
+            invited: JSON.parse(t.invited), pending: t.status === "open" ? pendingFor(db, t) : [], posts,
+        } };
+}
+export function topicOpen(db, projectId, actor, a) {
+    const bad = a.invited.filter((h) => !actorExists(db, h));
+    if (bad.length)
+        return { ok: false, error: `unknown invited actor(s): ${bad.join(", ")} — valid: ${listActorHandles(db).join(", ")}` };
+    const id = randomUUID();
+    const t = nowIso();
+    db.prepare("INSERT INTO topics(id,project_id,question,invited,status,round,round_opened_at,opened_by,opened_at) VALUES (?,?,?,?,'open',1,?,?,?)")
+        .run(id, projectId, a.question, JSON.stringify([...new Set(a.invited)]), t, actor, t);
+    logEvent(db, { project_id: projectId, actor, kind: "topic.open", data: { id, invited: a.invited } });
+    return { ok: true, data: { id, question: a.question, invited: [...new Set(a.invited)], status: "open", round: 1, opened_by: actor } };
+}
+export function postAdd(db, projectId, projectKey, actor, a) {
+    const ts = nowIso();
+    db.exec("BEGIN IMMEDIATE"); // read round+status then insert atomically vs a concurrent synthesize round-bump (§7)
+    try {
+        const t = db.prepare("SELECT * FROM topics WHERE id=? AND project_id=?").get(a.topicId, projectId);
+        if (!t) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `no topic ${a.topicId} in ${projectKey}` };
+        }
+        if (t.status !== "open") {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `CONFLICT: topic ${a.topicId} is closed` };
+        }
+        if (!JSON.parse(t.invited).includes(actor)) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `FORBIDDEN: '${actor}' is not invited to topic ${a.topicId}` };
+        }
+        const dup = db.prepare("SELECT 1 FROM posts WHERE topic_id=? AND round=? AND author=? AND kind='perspective'").get(a.topicId, t.round, actor);
+        if (dup) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `already posted in round ${t.round} — append-only, one perspective per round` };
+        }
+        db.prepare("INSERT INTO posts(id,topic_id,round,author,kind,body,created_at) VALUES (?,?,?,?,'perspective',?,?)")
+            .run(randomUUID(), a.topicId, t.round, actor, a.body, ts);
+        logEvent(db, { project_id: projectId, actor, kind: "post.add", data: { topicId: a.topicId, round: t.round } });
+        db.exec("COMMIT");
+        return { ok: true, data: { topicId: a.topicId, round: t.round, author: actor, kind: "perspective", created_at: ts } };
+    }
+    catch (e) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* */ }
+        throw e;
+    }
+}
+export function topicSynthesize(db, projectId, projectKey, actor, a) {
+    const ts = nowIso();
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const t = db.prepare("SELECT * FROM topics WHERE id=? AND project_id=?").get(a.topicId, projectId);
+        if (!t) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `no topic ${a.topicId} in ${projectKey}` };
+        }
+        if (t.status !== "open") {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `CONFLICT: topic ${a.topicId} is closed` };
+        }
+        if (t.opened_by !== actor) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `FORBIDDEN: only the chair '${t.opened_by}' may synthesize topic ${a.topicId}` };
+        }
+        // pre-check the once-per-round synthesis (Codex review): a clean CONFLICT, not a raw UNIQUE error
+        const dupSyn = db.prepare("SELECT 1 FROM posts WHERE topic_id=? AND round=? AND author=? AND kind='synthesis'").get(a.topicId, t.round, actor);
+        if (dupSyn) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `CONFLICT: already synthesized round ${t.round} — bump with nextRound:true or close` };
+        }
+        db.prepare("INSERT INTO posts(id,topic_id,round,author,kind,body,created_at) VALUES (?,?,?,?,'synthesis',?,?)")
+            .run(randomUUID(), a.topicId, t.round, actor, a.body, ts);
+        let round = t.round;
+        if (a.nextRound) {
+            round = t.round + 1;
+            db.prepare("UPDATE topics SET round=?, round_opened_at=? WHERE id=?").run(round, ts, t.id);
+        }
+        logEvent(db, { project_id: projectId, actor, kind: "topic.synthesize", data: { topicId: a.topicId, round: t.round, nextRound: !!a.nextRound } });
+        db.exec("COMMIT");
+        return { ok: true, data: { topicId: a.topicId, synthesizedRound: t.round, round, status: "open" } };
+    }
+    catch (e) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* */ }
+        throw e;
+    }
+}
+export function topicClose(db, projectId, projectKey, actor, a) {
+    const ts = nowIso();
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const t = db.prepare("SELECT * FROM topics WHERE id=? AND project_id=?").get(a.topicId, projectId);
+        if (!t) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `no topic ${a.topicId} in ${projectKey}` };
+        }
+        if (t.status !== "open") {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `CONFLICT: topic ${a.topicId} is already closed` };
+        }
+        if (t.opened_by !== actor) {
+            db.exec("ROLLBACK");
+            return { ok: false, error: `FORBIDDEN: only the chair '${t.opened_by}' may close topic ${a.topicId}` };
+        }
+        db.prepare("UPDATE topics SET status='closed', decision=?, closed_at=? WHERE id=?").run(a.decision, ts, t.id);
+        logEvent(db, { project_id: projectId, actor, kind: "topic.close", data: { topicId: a.topicId, round: t.round } });
+        db.exec("COMMIT");
+        return { ok: true, data: { topicId: a.topicId, status: "closed", decision: a.decision, closed_at: ts } };
+    }
+    catch (e) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* */ }
+        throw e;
+    }
+}