@dyzsasd/dev-loop 0.22.0

package/dist/channel.js

@@ -0,0 +1,226 @@
+import { createHmac } from "node:crypto";
+// ── Shared channel helpers (DL-26): extracted so the MCP server (server.ts) and the daemon
+// (daemon.ts) drive ONE implementation of channel selection / cred resolution / gating and cannot
+// drift. All are pure (db/projectId passed in); resolveCreds reads ONLY env-var NAMES (§16). ──
+export const CHANNEL_DRYRUN = process.env.DEVLOOP_CHANNEL_DRYRUN === "1"; // test/offline: build, no network
+export const CHANNEL_SEND_CAP = 60; // per-process loop-safety throttle
+export const getEnabledChannel = (db, projectId) => db.prepare("SELECT * FROM channels WHERE project_id=? AND enabled=1 ORDER BY created_at LIMIT 1").get(projectId);
+// Resolve creds from env-var NAMES (§16). DL-52: a 'webhook' channel reads its incoming-webhook URL from
+// process.env[config_ref] and the optional Lark sign-secret from process.env[secret_ref] — still NAMES, the
+// DB never holds the URL/secret. A 'bot' channel (default / absent) is byte-for-byte the prior behavior.
+export const resolveCreds = (c) => c.transport === "webhook"
+    ? { webhookUrl: process.env[c.config_ref], signSecret: c.secret_ref ? process.env[c.secret_ref] : undefined }
+    : c.provider === "slack"
+        ? { token: process.env[c.config_ref] }
+        : { appId: process.env[c.config_ref], appSecret: c.secret_ref ? process.env[c.secret_ref] : undefined };
+export function resolveNotifyWebhook(notify) {
+    if (!notify || typeof notify !== "object")
+        return null;
+    const n = notify;
+    const provider = n.type === "slack" ? "slack" : n.type === "lark" ? "lark" : null;
+    if (!provider)
+        return null; // only slack/lark webhooks
+    if (Array.isArray(n.events) && !n.events.includes("human-parked"))
+        return null; // operator scoped this event out (§9 events)
+    if (typeof n.webhook !== "string" && typeof n.webhookEnv !== "string")
+        return null; // no webhook configured ⇒ not a target
+    const webhookUrl = typeof n.webhook === "string" ? n.webhook
+        : typeof n.webhookEnv === "string" ? process.env[n.webhookEnv] : undefined; // env unset ⇒ undefined ⇒ fail closed at send
+    const signSecret = typeof n.secret === "string" ? n.secret
+        : typeof n.secretEnv === "string" ? process.env[n.secretEnv] : undefined;
+    return { provider, creds: { webhookUrl, signSecret } };
+}
+// redact anything token-shaped + bound the length before any provider error is persisted/returned/logged.
+export const scrubErr = (m) => m.replace(/\b(xox[abp]-[\w-]+|lin_(?:api|oauth)_[\w-]+|sk-[\w-]+|ghp_[\w-]+|eyJ[\w.-]{20,})\b/g, "***").slice(0, 120);
+// strip control chars + truncate — outbound text never carries raw bytes that could break a payload (§16/§9).
+export const cleanLine = (s, max) => s.replace(/[\x00-\x1f\x7f]+/g, " ").trim().slice(0, max);
+// mirror §9 notify's `curl --max-time 10`; overridable for tests (the timeout path must be fast to assert)
+const timeoutMs = () => Number(process.env.DEVLOOP_CHANNEL_TIMEOUT_MS) || 10_000;
+// ── timeout-wrapped JSON fetch ───────────────────────────────────────────────
+async function httpJson(fetchImpl, url, init) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs());
+    try {
+        const res = await fetchImpl(url, { ...init, signal: ctl.signal });
+        const body = (await res.json().catch(() => ({})));
+        return { status: res.status, body };
+    }
+    catch (e) {
+        // AbortError (timeout) / network error → a clean, secret-free message
+        throw new Error(`network error: ${e.name === "AbortError" ? "timeout" : e.name}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ── Lark tenant_access_token (internal app): exchange app_id+app_secret, cache in-memory only ──
+// §16: the token is held ONLY in this process map, never persisted/logged/returned. ~2h expiry.
+const larkTokenCache = new Map();
+async function larkToken(fetchImpl, appId, appSecret) {
+    const cached = larkTokenCache.get(appId);
+    if (cached && cached.expiresAt > Date.now() + 60_000)
+        return cached.token;
+    const { status, body } = await httpJson(fetchImpl, "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+    });
+    if (status !== 200 || body.code !== 0 || typeof body.tenant_access_token !== "string") {
+        throw new Error(`lark auth failed: code ${body.code ?? status}`); // code is Lark's error number, not the secret
+    }
+    const expire = typeof body.expire === "number" ? body.expire : 7200;
+    larkTokenCache.set(appId, { token: body.tenant_access_token, expiresAt: Date.now() + (expire - 120) * 1000 });
+    return body.tenant_access_token;
+}
+// ── OUTBOUND ─────────────────────────────────────────────────────────────────
+// `transport` (DL-52) defaults to 'bot' so every existing caller (server.ts channel.send) is byte-for-byte
+// unchanged; the DL-26 daemon notifier passes the channel's transport so a 'webhook' channel pings a pasted
+// incoming-webhook URL (no bot app). The webhook send is one-way (no inbound poll over a webhook).
+export async function sendVia(provider, creds, channelRef, msg, fetchImpl, transport = "bot") {
+    const text = msg.lines.join("\n");
+    if (transport === "webhook")
+        return sendWebhook(provider, creds, text, fetchImpl);
+    if (provider === "slack") {
+        if (!creds.token)
+            throw new Error("slack token unset");
+        const { status, body } = await httpJson(fetchImpl, "https://slack.com/api/chat.postMessage", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${creds.token}` },
+            body: JSON.stringify({ channel: channelRef, text }),
+        });
+        if (status !== 200 || body.ok !== true)
+            throw new Error(`slack send failed: ${body.error ?? status}`);
+        return;
+    }
+    // lark
+    if (!creds.appId || !creds.appSecret)
+        throw new Error("lark app_id/app_secret unset");
+    const token = await larkToken(fetchImpl, creds.appId, creds.appSecret);
+    const { status, body } = await httpJson(fetchImpl, "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ receive_id: channelRef, msg_type: "text", content: JSON.stringify({ text }) }),
+    });
+    if (status !== 200 || body.code !== 0)
+        throw new Error(`lark send failed: ${body.code ?? status}`);
+}
+// ── DL-52: one-way incoming-webhook send (no bot app, no token exchange) ─────
+// Slack: POST {text} → success = HTTP 2xx (the classic incoming webhook returns the literal text "ok", not
+// JSON — httpJson's res.json() fails → body {}, so we gate on STATUS only). Lark custom-bot: POST
+// {msg_type,content} (+ a {timestamp,sign} when a sign-secret is set) → success = HTTP 2xx AND body code==0.
+// §16: webhookUrl + signSecret are creds (resolved from env NAMES by resolveCreds, never in the DB); a thrown
+// error carries ONLY the status/code, never the URL/secret. The message is JSON-encoded — never shell-spliced.
+const ok2xx = (s) => s >= 200 && s < 300; // incoming-webhook success gate (shared by both branches)
+async function sendWebhook(provider, creds, text, fetchImpl) {
+    if (!creds.webhookUrl)
+        throw new Error(`${provider} webhook url unset`); // env NAME resolved to nothing ⇒ fail closed
+    if (provider === "slack") {
+        const { status } = await httpJson(fetchImpl, creds.webhookUrl, {
+            method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text }),
+        });
+        if (!ok2xx(status))
+            throw new Error(`slack webhook failed: ${status}`);
+        return;
+    }
+    // lark custom-bot incoming webhook
+    const payload = { msg_type: "text", content: { text } };
+    if (creds.signSecret) {
+        const ts = Math.floor(Date.now() / 1000);
+        payload.timestamp = String(ts);
+        payload.sign = larkSign(ts, creds.signSecret);
+    }
+    const { status, body } = await httpJson(fetchImpl, creds.webhookUrl, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload),
+    });
+    if (!ok2xx(status) || body.code !== 0)
+        throw new Error(`lark webhook failed: ${body.code ?? status}`);
+}
+// Lark custom-bot signature: base64(HMAC-SHA256(key="<ts>\n<secret>", data="")) — the "<ts>\n<secret>" is the
+// HMAC KEY and the signed message is EMPTY (Lark's scheme; mirrors conventions §9's notify sign helper).
+function larkSign(timestamp, secret) {
+    return createHmac("sha256", `${timestamp}\n${secret}`).update("").digest("base64");
+}
+// ── INBOUND (history read; cursor = provider monotonic marker) ───────────────
+// Returns normalized human-operator messages strictly AFTER `cursor`, plus the new cursor. The
+// bot's OWN messages are dropped (SECURITY: never ingest our own digest/reply as "operator
+// direction" — a self-echo/injection loop vector). authorRef is the OPAQUE provider sender id —
+// it is NEVER equated with operator authority (the instruction-source boundary, §16).
+// PAGINATED (Codex review): a single 50-item page would SKIP older messages when >1 page arrived
+// since the cursor (advancing to the page max past unfetched older ones). We page until the provider
+// reports no more, with a runaway guard that THROWS (cursor unadvanced, surfaced) rather than silently
+// skip. normalize()'s strictly-after-cursor filter + the UNIQUE dedup make over-fetch harmless.
+const MAX_POLL_PAGES = 40; // a regular loop poll exits after 1 page; this only bites a huge backlog
+export async function pollVia(provider, creds, channelRef, cursor, fetchImpl) {
+    const collected = [];
+    if (provider === "slack") {
+        if (!creds.token)
+            throw new Error("slack token unset");
+        let pageCursor;
+        let pages = 0;
+        for (;;) {
+            const p = new URLSearchParams({ channel: channelRef, limit: "100" });
+            if (cursor)
+                p.set("oldest", cursor);
+            if (pageCursor)
+                p.set("cursor", pageCursor);
+            const { status, body } = await httpJson(fetchImpl, `https://slack.com/api/conversations.history?${p}`, { headers: { Authorization: `Bearer ${creds.token}` } });
+            if (status !== 200 || body.ok !== true)
+                throw new Error(`slack history failed: ${body.error ?? status}`);
+            for (const m of (Array.isArray(body.messages) ? body.messages : [])) {
+                if (m.bot_id || m.subtype === "bot_message")
+                    continue; // self/bot echo guard (security)
+                collected.push({ providerMsgId: String(m.ts), authorRef: String(m.user ?? "unknown"), text: String(m.text ?? ""), providerTs: String(m.ts) });
+            }
+            const meta = body.response_metadata;
+            pageCursor = body.has_more && meta?.next_cursor ? String(meta.next_cursor) : undefined;
+            if (!pageCursor)
+                break;
+            if (++pages >= MAX_POLL_PAGES)
+                throw new Error("slack history exceeded max pages (backlog too large for one poll; widen cadence)");
+        }
+        return normalize(collected, cursor);
+    }
+    // lark
+    if (!creds.appId || !creds.appSecret)
+        throw new Error("lark app_id/app_secret unset");
+    const token = await larkToken(fetchImpl, creds.appId, creds.appSecret);
+    let pageToken;
+    let pages = 0;
+    for (;;) {
+        const p = new URLSearchParams({ container_id_type: "chat", container_id: channelRef, page_size: "50" });
+        if (cursor)
+            p.set("start_time", cursor);
+        if (pageToken)
+            p.set("page_token", pageToken);
+        const { status, body } = await httpJson(fetchImpl, `https://open.feishu.cn/open-apis/im/v1/messages?${p}`, { headers: { Authorization: `Bearer ${token}` } });
+        if (status !== 200 || body.code !== 0)
+            throw new Error(`lark history failed: ${body.code ?? status}`);
+        const data = body.data;
+        for (const m of (Array.isArray(data?.items) ? data.items : [])) {
+            if (m.sender?.sender_type === "app")
+                continue; // self/app echo guard
+            collected.push({ providerMsgId: String(m.message_id), authorRef: String(m.sender?.id ?? "unknown"), text: larkText(m.body), providerTs: String(m.create_time) });
+        }
+        pageToken = data?.has_more && data?.page_token ? String(data.page_token) : undefined;
+        if (!pageToken)
+            break;
+        if (++pages >= MAX_POLL_PAGES)
+            throw new Error("lark history exceeded max pages (backlog too large for one poll; widen cadence)");
+    }
+    return normalize(collected, cursor);
+}
+function larkText(body) {
+    try {
+        const c = JSON.parse(String(body?.content ?? "{}"));
+        return String(c.text ?? "");
+    }
+    catch {
+        return "";
+    }
+}
+// strictly-after-cursor + advance the cursor to the max provider_ts ACTUALLY returned (never the
+// window end) — so a message can never be skipped by an over-eager cursor advance.
+function normalize(msgs, cursor) {
+    const fresh = msgs.filter((m) => cursor === null || m.providerTs > cursor);
+    const next = fresh.reduce((acc, m) => (acc === null || m.providerTs > acc ? m.providerTs : acc), cursor);
+    return { messages: fresh, cursor: next };
+}

package/dist/channelstore.js

@@ -0,0 +1,269 @@
+// Shared P6 IM-channel store (DL-67) — the channel register/send/poll/ack/status HANDLER logic + the DL-4
+// roadmap-over-chat bridge, used by BOTH the MCP server (server.ts) and the daemon op-API (agentops.ts). The
+// provider TRANSPORT (send/poll/cred-resolution/gating/scrub) stays in channel.ts and is reused AS-IS; this
+// module is the handler layer channel.ts's transport serves — the docstore.ts/topicstore.ts precedent that
+// lets the stdio server and the daemon op-API share ONE implementation and never drift.
+//
+// SIDE-EFFECT-FREE entrypoint (no top-level db; identity (actor) + scope (projectId/projectKey) are passed in
+// by the caller — the daemon resolves the actor from X-Devloop-Actor, the stdio server passes its ACTOR — so
+// every channel event is attributed to the REAL caller on both paths, exactly the topicstore precedent). The
+// only module state is the per-process send throttle (below), the same loop-safety cap server.ts held before.
+//
+// §16: secrets are read by channel.ts from env NAMES (config_ref/secret_ref) SERVER-SIDE; this module NEVER
+// stores/returns/logs a token (a failed send throws the scrubbed status, never the URL/secret — DL-52). §17
+// firewall (structural): every write here is an INSERT/UPDATE on the `channels` / `channel_messages` DB tables
+// — there is NO filesystem path anywhere in this module, so a channel op can never target a SKILL/conventions/
+// code file; the only external effect is the network send via channel.ts's transport. The DL-4 bridge lands an
+// operator chat edit as a roadmap DRAFT only — the operator-publish gate (docstore) is never bypassed, so an
+// injected edit can never go live.
+import { randomUUID } from "node:crypto";
+import { nowIso, logEvent } from "./db.js";
+import { sendVia, pollVia, getEnabledChannel, resolveCreds, scrubErr, cleanLine, CHANNEL_DRYRUN, CHANNEL_SEND_CAP } from "./channel.js";
+import { resolveDoc, latestVersion, docSave } from "./docstore.js";
+// Map a channelstore error to an HTTP status: a missing inbound message (ack) → 404; everything else
+// (no-channel-register-first / reply-needs-text / send-cap / send|poll failed / a non-env-NAME *Ref) → 400.
+// (No 403/409 here: the op-API's origin/actor/mode gates are upstream in the daemon, and channel has no CAS.)
+export const statusForChannelErr = (msg) => /^no inbound message\b/.test(msg) ? 404 : 400;
+// §16 (Codex review): a *Ref is an ENV-VAR NAME, never a literal secret — reject anything that isn't an
+// env-name shape, and anything that looks like an actual token, so a caller can't persist a secret to the DB.
+// Exported because the P7 mirror's tokenEnv check (server.ts) reuses the SAME validator — one definition, no drift.
+const TOKEN_PREFIXES = /^(xox[abp]-|lin_api_|lin_oauth_|sk-|ghp_|Bearer\s)/i;
+export const isEnvName = (s) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s) && !TOKEN_PREFIXES.test(s) && s.length <= 100;
+// strip control chars + truncate — channel.ts's cleanLine IS server.ts's old local `clean` (byte-identical)
+const clean = cleanLine;
+const INBOX_GC_DAYS = 14;
+// per-process send throttle (was server.ts's `channelSendsThisProcess`): module-scope here so the stdio server
+// AND the daemon op-API each keep their OWN per-process cap — identical loop-safety semantics on both paths.
+let sendsThisProcess = 0;
+export function channelRegister(db, projectId, actor, a) {
+    if (!isEnvName(a.configRef))
+        return { ok: false, error: `configRef must be an ENV-VAR NAME (e.g. DEVLOOP_CHANNEL_TOKEN), not the secret value itself` };
+    if (a.secretRef && !isEnvName(a.secretRef))
+        return { ok: false, error: `secretRef must be an ENV-VAR NAME, not the secret value itself` };
+    const t = nowIso();
+    const existing = db.prepare("SELECT id FROM channels WHERE project_id=? AND provider=? AND channel_ref=?").get(projectId, a.provider, a.channelRef);
+    if (existing) {
+        db.prepare("UPDATE channels SET config_ref=?, secret_ref=?, enabled=1, updated_at=? WHERE id=?").run(a.configRef, a.secretRef ?? null, t, existing.id);
+        logEvent(db, { project_id: projectId, actor, kind: "channel.register", data: { provider: a.provider, channelRef: a.channelRef, updated: true } });
+        return { ok: true, data: { id: existing.id, provider: a.provider, channelRef: a.channelRef, updated: true } };
+    }
+    const id = randomUUID();
+    db.prepare("INSERT INTO channels(id,project_id,provider,config_ref,secret_ref,channel_ref,enabled,created_at,updated_at) VALUES (?,?,?,?,?,?,1,?,?)")
+        .run(id, projectId, a.provider, a.configRef, a.secretRef ?? null, a.channelRef, t, t);
+    logEvent(db, { project_id: projectId, actor, kind: "channel.register", data: { provider: a.provider, channelRef: a.channelRef } });
+    return { ok: true, data: { id, provider: a.provider, channelRef: a.channelRef } };
+}
+export async function channelSend(db, projectId, projectKey, actor, a) {
+    const ch = getEnabledChannel(db, projectId);
+    if (!ch)
+        return { ok: false, error: `no enabled channel for ${projectKey} — channel.register first` };
+    const lines = [];
+    if (a.kind === "notify") {
+        const tk = a.ticketId ? db.prepare("SELECT title FROM tickets WHERE id=? AND project_id=?").get(a.ticketId, projectId) : undefined;
+        const title = tk ? clean(tk.title, 80) : a.ticketId ? `(unknown ${a.ticketId})` : "(no ticket)";
+        lines.push(`[${projectKey}] ${a.bailShape ?? "blocked"}: ${a.ticketId ?? "—"} ${title}`);
+    }
+    else if (a.kind === "digest") {
+        const d = a.digest ?? {};
+        lines.push(`[${projectKey}] dev-loop digest`);
+        if (d.headline)
+            lines.push(clean(d.headline, 200));
+        lines.push(`topics chaired ${d.topicsChaired ?? 0} · decisions ${d.decisionsClosed ?? 0} · roadmap draft v${d.roadmapDraftVersion ?? "—"}`);
+        if (d.throughput)
+            lines.push(`tickets: done ${d.throughput.done ?? 0} · in-review ${d.throughput.inReview ?? 0} · todo ${d.throughput.todo ?? 0}`);
+        if (d.openProposals?.length)
+            lines.push(`open proposals: ${d.openProposals.slice(0, 20).map((p) => clean(p, 24)).join(", ")}`);
+    }
+    else {
+        if (!a.text)
+            return { ok: false, error: "reply requires text" };
+        lines.push(clean(a.text, 800));
+    }
+    const msg = { kind: a.kind, lines };
+    if (CHANNEL_DRYRUN) {
+        logEvent(db, { project_id: projectId, actor, kind: "channel.send", data: { kind: a.kind, dryrun: true } });
+        return { ok: true, data: { ok: true, dryrun: true, provider: ch.provider, kind: a.kind, lines } };
+    }
+    if (sendsThisProcess >= CHANNEL_SEND_CAP)
+        return { ok: false, error: `channel send cap (${CHANNEL_SEND_CAP}/process) reached — loop-safety throttle` };
+    sendsThisProcess++;
+    try {
+        await sendVia(ch.provider, resolveCreds(ch), ch.channel_ref, msg, fetch);
+    }
+    catch (e) {
+        return { ok: false, error: `channel send failed: ${scrubErr(e.message)}` }; // secret-free by construction (channel.ts) + scrubbed
+    }
+    const t = nowIso();
+    db.prepare("INSERT INTO channel_messages(id,channel_id,project_id,direction,provider_msg_id,body,kind,created_at) VALUES (?,?,?,?,?,?,?,?)")
+        .run(randomUUID(), ch.id, projectId, "outbound", null, lines.join(" | ").slice(0, 500), a.kind, t);
+    logEvent(db, { project_id: projectId, actor, kind: "channel.send", data: { kind: a.kind } });
+    return { ok: true, data: { ok: true, provider: ch.provider, kind: a.kind } };
+}
+// ── DL-4: roadmap-over-chat bridge (handled INSIDE channelPoll) — moved verbatim from server.ts ────────────
+// Recognize an operator roadmap command in an inbound message: a bare `roadmap` (summary) or `roadmap edit
+// <text>` (an edit). null ⇒ a normal message → the Director's inbox. There is deliberately NO publish command
+// — publishing stays the operator-actor doc.publish gate (DL-3/§25), so a chat message can never push the
+// roadmap live; an edit only ever lands as a DRAFT. A bare `roadmap: <musing>` is NOT captured as an edit.
+function parseRoadmapCommand(text) {
+    const t = text.trim();
+    const m = t.match(/^\/?roadmap\s+edit\s+([\s\S]+)$/i);
+    if (m) {
+        const body = m[1].trim();
+        if (body)
+            return { type: "edit", body };
+    }
+    if (/^\/?roadmap(?:\s+(?:show|view|status))?\??$/i.test(t))
+        return { type: "summary" };
+    return null;
+}
+// Scrub channel-originated content before it lands in a doc or an outbound summary (§16/AC4 — no secrets or
+// PII pasted from chat). Broadened past the loop's own creds to common third-party secret shapes + PII; secret
+// shapes never occur in real roadmap prose so aggressive is safe, the operator reviews the DRAFT before
+// publishing, so light over-redaction is acceptable. No truncation here — the caller bounds length (DL-4).
+const scrubChannel = (s) => s
+    .replace(/\b(xox[abprs]-[\w-]+|xapp-[\w-]+|AKIA[0-9A-Z]{16}|AIza[\w-]{35}|gh[opusr]_[A-Za-z0-9]+|github_pat_[A-Za-z0-9_]+|sk-[A-Za-z0-9-]+|[sr]k_(?:live|test)_[A-Za-z0-9]+|lin_(?:api|oauth)_[\w-]+|eyJ[\w.-]{20,})\b/g, "***") // API tokens/keys
+    .replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, "***") // email
+    .replace(/\b\+?\d{1,4}[ .-]\(?\d{2,4}\)?[ .-]\d{3,4}(?:[ .-]\d{2,4})?\b/g, "***") // phone (multi-segment, avoids plain numbers)
+    .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, "***") // IPv4
+    .replace(/(?:\d[ -]?){13,19}/g, (m) => m.replace(/\D/g, "").length >= 13 ? "***" : m); // card-shaped digit run
+// A §16-safe one-shot summary of the current kind:"roadmap" doc for the channel (DL-4 AC1): title, status,
+// versions, and a bounded, scrubbed excerpt — never a secret/PII, never the full history.
+function roadmapSummaryLines(db, projectId, projectKey) {
+    const d = resolveDoc(db, projectId, undefined, "roadmap");
+    if (!d)
+        return [`[${projectKey}] roadmap — no roadmap document yet`];
+    const latest = latestVersion(db, d.id), published = d.current_version;
+    const head = `[${projectKey}] roadmap "${clean(d.title, 80)}" — ${published > 0 ? `published v${published}` : "unpublished"}${latest > published ? `, latest draft v${latest}` : ""}`;
+    const v = latest > 0 ? db.prepare("SELECT body FROM document_versions WHERE doc_id=? AND version=?").get(d.id, latest) : undefined;
+    return [head, v?.body ? scrubChannel(clean(v.body, 600)) : "(empty)"];
+}
+// Send pre-built lines to the channel as a reply (the roadmap auto-reply). Respects CHANNEL_DRYRUN (log, no
+// network) + the per-process send cap; the token never crosses this boundary.
+async function sendChannelLines(db, projectId, actor, ch, lines) {
+    if (CHANNEL_DRYRUN) {
+        logEvent(db, { project_id: projectId, actor, kind: "channel.send", data: { kind: "reply", dryrun: true } });
+        return;
+    }
+    if (sendsThisProcess >= CHANNEL_SEND_CAP)
+        return;
+    sendsThisProcess++;
+    await sendVia(ch.provider, resolveCreds(ch), ch.channel_ref, { kind: "reply", lines }, fetch);
+    db.prepare("INSERT INTO channel_messages(id,channel_id,project_id,direction,provider_msg_id,body,kind,created_at) VALUES (?,?,?,?,?,?,?,?)")
+        .run(randomUUID(), ch.id, projectId, "outbound", null, lines.join(" | ").slice(0, 500), "reply", nowIso());
+    logEvent(db, { project_id: projectId, actor, kind: "channel.send", data: { kind: "reply" } });
+}
+// ── channel.poll — TWO-PHASE (fetch lock-free → atomic dedup-insert+cursor advance) + the DL-4 bridge ─────
+export async function channelPoll(db, projectId, projectKey, actor) {
+    const ch = getEnabledChannel(db, projectId);
+    if (!ch)
+        return { ok: false, error: `no enabled channel for ${projectKey} — channel.register first` };
+    const cursor = ch.inbound_cursor; // PHASE 1 — lock-free read
+    // PHASE 2 — fetch OUTSIDE any lock (network I/O must never be held under busy_timeout)
+    let fetched;
+    try {
+        if (CHANNEL_DRYRUN) {
+            const fixture = JSON.parse(process.env.DEVLOOP_CHANNEL_FIXTURE ?? "[]");
+            const fresh = fixture.filter((m) => cursor === null || m.providerTs > cursor);
+            const next = fresh.reduce((acc, m) => (acc === null || m.providerTs > acc ? m.providerTs : acc), cursor);
+            fetched = { messages: fresh, cursor: next };
+        }
+        else {
+            fetched = await pollVia(ch.provider, resolveCreds(ch), ch.channel_ref, cursor, fetch);
+        }
+    }
+    catch (e) {
+        return { ok: false, error: `channel poll failed: ${scrubErr(e.message)}` }; // cursor unchanged → next fire retries
+    }
+    const t = nowIso();
+    db.exec("BEGIN IMMEDIATE"); // PHASE 3 — atomic dedup-insert + cursor advance
+    try {
+        // ON CONFLICT DO NOTHING: suppress ONLY the dedup-key conflict — any OTHER constraint failure must throw → ROLLBACK → cursor NOT advanced.
+        const ins = db.prepare("INSERT INTO channel_messages(id,channel_id,project_id,direction,provider_msg_id,author_ref,body,acted,created_at,provider_ts) VALUES (?,?,?,?,?,?,?,0,?,?) ON CONFLICT(channel_id,direction,provider_msg_id) DO NOTHING");
+        let inserted = 0;
+        for (const m of fetched.messages) {
+            const r = ins.run(randomUUID(), ch.id, projectId, "inbound", m.providerMsgId, m.authorRef, m.text, t, m.providerTs);
+            if (r.changes > 0)
+                inserted++;
+        }
+        if (fetched.cursor !== null)
+            db.prepare("UPDATE channels SET inbound_cursor=?, last_poll_at=? WHERE id=?").run(fetched.cursor, t, ch.id);
+        else
+            db.prepare("UPDATE channels SET last_poll_at=? WHERE id=?").run(t, ch.id);
+        db.prepare("DELETE FROM channel_messages WHERE project_id=? AND direction='inbound' AND acted=1 AND created_at < ?")
+            .run(projectId, new Date(Date.now() - INBOX_GC_DAYS * 86400000).toISOString());
+        logEvent(db, { project_id: projectId, actor, kind: "channel.poll", data: { new: inserted } });
+        db.exec("COMMIT");
+    }
+    catch (e) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* */ }
+        throw e;
+    }
+    // ── DL-4: auto-handle roadmap commands among the now-ingested inbox — a §16-safe summary reply, or a
+    //    roadmap DRAFT via doc.save (NEVER published). Run OUTSIDE the poll txn (docSave has its own; sendVia
+    //    is network). Handled messages are ack'd so they never reach the Director's `pending`; non-roadmap
+    //    messages flow through unchanged. A chat author is UNVERIFIED, but a draft is non-live + reversible
+    //    (§16/§25) — only the operator can publish it, so an injected edit can never go live.
+    const roadmapHandled = [];
+    for (const msg of db.prepare("SELECT id,body FROM channel_messages WHERE project_id=? AND direction='inbound' AND acted=0 ORDER BY provider_ts").all(projectId)) {
+        const cmd = parseRoadmapCommand(msg.body);
+        if (!cmd)
+            continue;
+        // ATOMIC CLAIM (cross-process safety §7/§18/§26): flip acted 0→1 in one statement, proceed ONLY if we won
+        // it, so a second overlapping poll (another Director fire / a 2nd CLI) can't double-process the command.
+        if (db.prepare("UPDATE channel_messages SET acted=1, acted_into='roadmap:handling' WHERE id=? AND project_id=? AND direction='inbound' AND acted=0").run(msg.id, projectId).changes === 0)
+            continue;
+        let lines, actedInto, result;
+        if (cmd.type === "summary") {
+            lines = roadmapSummaryLines(db, projectId, projectKey);
+            actedInto = "roadmap:summary";
+            result = "summary";
+        }
+        else {
+            const existing = resolveDoc(db, projectId, undefined, "roadmap");
+            const r = docSave(db, projectId, actor, { slug: existing?.slug ?? "roadmap", kind: "roadmap", body: scrubChannel(cmd.body).slice(0, 8000), baseVersion: existing ? latestVersion(db, existing.id) : 0, summary: "via channel" });
+            if (r.ok) {
+                lines = [`[${projectKey}] roadmap draft v${r.data.version} saved from chat — awaiting operator publish`];
+                actedInto = `roadmap:draft:v${r.data.version}`;
+                result = `draft v${r.data.version}`;
+            }
+            else {
+                lines = [`[${projectKey}] roadmap edit not applied — ${clean(r.error, 160)}`];
+                actedInto = "roadmap:edit-rejected";
+                result = "rejected";
+            }
+        }
+        try {
+            await sendChannelLines(db, projectId, actor, ch, lines);
+        }
+        catch { /* a failed reply must not wedge the poll or undo a persisted draft */ }
+        db.prepare("UPDATE channel_messages SET acted_into=? WHERE id=? AND project_id=?").run(actedInto, msg.id, projectId);
+        roadmapHandled.push({ messageId: msg.id, type: cmd.type, result, lines });
+    }
+    const pending = db.prepare("SELECT id,author_ref,body,provider_ts FROM channel_messages WHERE project_id=? AND direction='inbound' AND acted=0 ORDER BY provider_ts")
+        .all(projectId);
+    return { ok: true, data: { new: fetched.messages.length, cursor: fetched.cursor, roadmapHandled, pending: pending.map((p) => ({ messageId: p.id, author: p.author_ref, text: p.body, ts: p.provider_ts })) } };
+}
+export function channelAck(db, projectId, projectKey, actor, a) {
+    const r = db.prepare("UPDATE channel_messages SET acted=1, acted_into=? WHERE id=? AND project_id=? AND direction='inbound'")
+        .run(a.actedInto ?? null, a.messageId, projectId);
+    if (r.changes === 0)
+        return { ok: false, error: `no inbound message ${a.messageId} in ${projectKey}` };
+    logEvent(db, { project_id: projectId, actor, kind: "channel.ack", data: { messageId: a.messageId, actedInto: a.actedInto ?? null } });
+    return { ok: true, data: { messageId: a.messageId, acted: true, actedInto: a.actedInto ?? null } };
+}
+// ── channel.status (read; never origin/actor-gated — parity with the read ticket/doc/topic ops) ──────────
+// Returns the ENV-VAR NAMES' SET-or-not as booleans, NEVER the secret values (§16).
+export function channelStatus(db, projectId) {
+    const ch = getEnabledChannel(db, projectId);
+    if (!ch)
+        return { configured: false };
+    const pending = db.prepare("SELECT count(*) c FROM channel_messages WHERE project_id=? AND direction='inbound' AND acted=0").get(projectId).c;
+    return {
+        configured: true, provider: ch.provider, channelRef: ch.channel_ref, cursor: ch.inbound_cursor, lastPoll: ch.last_poll_at,
+        configRefSet: process.env[ch.config_ref] !== undefined, secretRefSet: ch.secret_ref ? process.env[ch.secret_ref] !== undefined : null,
+        inboxPending: pending,
+    };
+}

package/dist/cli-tickets.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// `dev-loop tickets` + `dev-loop ticket <id>` — the read-only TERMINAL board-read client (DL-90).
+// The Vision (docs/STRATEGY.md §Vision) names the `dev-loop` CLI as one of the interchangeable board-READ
+// clients (alongside the stdio MCP shim + the localhost web UI). The web UI binds 127.0.0.1 only (§16), so a
+// terminal-first / SSH'd operator had no way to see the board. This closes that gap — the `gh issue list`/
+// `gh issue view` of the hub. Opens the hub SoR the SAME way server.ts/seed.ts do (openDb + DEVLOOP_HUB_DB) and
+// resolves the project via the SAME DEVLOOP_PROJECT/cwd ladder (resolveIdentity, §11). STRICTLY read-only:
+// `PRAGMA query_only` after open makes any write/event throw; needs NO daemon and NO DEVLOOP_ACTOR (identity is
+// irrelevant to a read). Routed from cli.ts (`tickets`/`ticket` → this file with the subcommand as argv[0]).
+import { homedir } from "node:os";
+import { openDb } from "./db.js";
+import { resolveIdentity } from "./resolve-project.js";
+import { findProject } from "./seed.js";
+const TERMINAL = new Set(["Done", "Canceled", "Duplicate"]); // §3 terminal states — hidden unless --all
+const PRIORITY = { 1: "Urgent", 2: "High", 3: "Medium", 4: "Low", 0: "None" }; // §5 (mirrors daemonviews)
+const prioOf = (p) => PRIORITY[p] ?? String(p);
+// owner = the §4 routing label (mirrors daemonviews.ownerOf); the CLI keeps a local copy to stay decoupled
+// from the HTML views module, matching the codebase's existing per-module toTicket copies.
+const ownerOf = (labels) => (labels.includes("pm") ? "pm" : labels.includes("qa") ? "qa" : "—");
+const parseArr = (j) => { try {
+    const a = JSON.parse(j);
+    return Array.isArray(a) ? a : [];
+}
+catch {
+    return [];
+} };
+// `dev-loop tickets [--all] [--state <name>] [--type <T>] [--owner <pm|qa>] [--label <name>] [--q <text>|<text>]` — board list, one line per ticket.
+function listTickets(db, projectId, args) {
+    let all = false, state, q, type, owner, label;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--all")
+            all = true;
+        else if (a === "--state" || a === "--q" || a === "--type" || a === "--owner" || a === "--label") {
+            const v = args[++i];
+            if (v === undefined) {
+                console.error(`dev-loop: ${a} needs a value`);
+                return 2;
+            } // a dangling flag is a usage error, not a silent no-filter (DL-91)
+            if (a === "--state")
+                state = v;
+            else if (a === "--q")
+                q = v;
+            else if (a === "--type")
+                type = v;
+            else if (a === "--owner")
+                owner = v;
+            else
+                label = v;
+        }
+        else if (a.startsWith("-")) {
+            console.error(`dev-loop: unknown flag '${a}'`);
+            return 2;
+        } // DL-93: reject unknown flags — never swallow the following arg as positional --q (the `--type Bug` footgun)
+        else if (q === undefined)
+            q = a; // positional free-text (parity with the web board's `q`)
+    }
+    // board order (priority ASC, updated_at DESC) — verbatim from daemonviews.boardPage so the terminal view matches the web view.
+    let rows = db.prepare("SELECT id,title,type,state,assignee,priority,labels,updated_at FROM tickets WHERE project_id=? ORDER BY priority ASC, updated_at DESC").all(projectId);
+    if (!all && !state)
+        rows = rows.filter((r) => !TERMINAL.has(r.state)); // default (only when no explicit --state): non-terminal only — an explicit --state always wins, incl. a terminal one (DL-91)
+    if (state)
+        rows = rows.filter((r) => r.state === state);
+    if (type)
+        rows = rows.filter((r) => r.type === type); // DL-93: exact type match (r.type already selected at the query); composes (AND) with the others & is orthogonal to the non-terminal default
+    if (owner)
+        rows = rows.filter((r) => ownerOf(parseArr(r.labels)) === owner); // DL-93: owner via the §4 routing-label helper (same helper the render uses below)
+    if (label)
+        rows = rows.filter((r) => parseArr(r.labels).includes(label)); // DL-93: arbitrary label membership (e.g. --label blocked / edge-case / tech-debt)
+    if (q) {
+        const needle = q.toLowerCase();
+        rows = rows.filter((r) => r.id.toLowerCase().includes(needle) || (r.title ?? "").toLowerCase().includes(needle));
+    }
+    if (rows.length === 0) {
+        console.log("No tickets.");
+        return 0;
+    }
+    for (const r of rows) {
+        console.log([
+            r.id.padEnd(7), r.state.padEnd(13), r.type.padEnd(11),
+            ownerOf(parseArr(r.labels)).padEnd(2), prioOf(r.priority).padEnd(6), r.title,
+        ].join(" · "));
+    }
+    return 0;
+}
+// `dev-loop ticket <id>` — one ticket's full detail + its comments (chronological).
+function showTicket(db, projectId, args) {
+    const id = args.find((a) => !a.startsWith("-"));
+    if (!id) {
+        console.error("dev-loop: usage: dev-loop ticket <id>");
+        return 2;
+    }
+    // §2 isolation: scope by project_id so a read can never reach another project's ticket.
+    const t = db.prepare("SELECT * FROM tickets WHERE id=? AND project_id=?").get(id, projectId);
+    if (!t) {
+        console.error(`dev-loop: ticket '${id}' not found in this project.`);
+        return 1;
+    }
+    const labels = parseArr(t.labels);
+    const related = parseArr(t.related_to); // DL-92: SELECT * already carries related_to (JSON array) + duplicate_of (scalar) — no new query
+    const out = [
+        `${t.id} · ${t.title}`,
+        `state: ${t.state}   type: ${t.type}   owner: ${ownerOf(labels)}   priority: ${prioOf(t.priority)}   assignee: ${t.assignee ?? "—"}`,
+        `labels: ${labels.join(", ") || "—"}`,
+    ];
+    if (related.length)
+        out.push(`related: ${related.join(", ")}`); // DL-92: ids render plainly so the operator can `dev-loop ticket <id>` to follow the chain (web detail / DL-8 parity)
+    if (t.duplicate_of)
+        out.push(`duplicate of: ${t.duplicate_of}`); // DL-92: shown only when set — a relation-less ticket omits these lines (no awkward empty label)
+    out.push("", t.description?.trim() || "(no description)");
+    const comments = db.prepare("SELECT author,body,created_at FROM comments WHERE ticket_id=? ORDER BY created_at").all(id);
+    out.push("", comments.length ? `── Comments (${comments.length}) ──` : "── No comments ──");
+    for (const c of comments)
+        out.push("", `${c.created_at} — ${c.author}`, c.body);
+    console.log(out.join("\n"));
+    return 0;
+}
+function main() {
+    const [sub, ...rest] = process.argv.slice(2); // sub = "tickets" | "ticket" (cli.ts passes it as argv[0])
+    const { projectKey, projectFromCwd } = resolveIdentity(); // a read needs no DEVLOOP_ACTOR
+    const db = openDb(process.env.DEVLOOP_HUB_DB ?? `${homedir()}/.dev-loop/hub.db`);
+    db.exec("PRAGMA query_only=1"); // AC5: structurally read-only — any write/event from here on throws
+    const projectId = findProject(db, projectKey);
+    if (!projectId) {
+        const srcDesc = projectFromCwd ? `resolved from cwd '${process.cwd()}'` : `from DEVLOOP_PROJECT='${projectKey}'`;
+        console.error(`dev-loop: project '${projectKey}' (${srcDesc}) is not seeded in the hub DB. Seed it once (\`dev-loop seed ${projectKey} "<name>" <UNIQUE_PREFIX>\`), or set DEVLOOP_PROJECT / run from inside the project repo.`);
+        return 1;
+    }
+    return sub === "ticket" ? showTicket(db, projectId, rest) : listTickets(db, projectId, rest);
+}
+process.exit(main());