huddle-cli 0.1.0 → 0.1.3

package/dist/room/context.js

@@ -0,0 +1,1285 @@
+// The shared screen: everything the user pastes, drops or uploads, kept ONCE
+// in the Room for every agent to look at — instead of N copies stuffed into N
+// prompts. Prompts carry only the index (one line per item); agents open what
+// they need with huddle_context_read, search it, and pin notes on items that
+// everyone (agents and people) sees.
+//
+//   <repo>/.huddle/context/ctx-3.txt     the item itself (.huddle is git-ignored)
+//   <repo>/.huddle/context/index.json    a mirror of the rows, for processes that
+//                                        only know the repo root (launcher, planner)
+//   context_item / context_note / context_link   rows in the Room db (the truth)
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnToolSync } from "../platform.js";
+/** Per-item and total caps. Env vars raise them (MB). */
+export const CAPS = {
+    textBytes: mb("HUDDLE_CTX_MAX_TEXT_MB", 2),
+    fileBytes: mb("HUDDLE_CTX_MAX_FILE_MB", 25),
+    totalBytes: mb("HUDDLE_CTX_MAX_TOTAL_MB", 200),
+    items: 200,
+    /** A folder or glob becomes one bundle item: at most this many files go in. */
+    folderFiles: 300,
+};
+function mb(env, def) {
+    const v = Number(process.env[env]);
+    return Math.round((Number.isFinite(v) && v > 0 ? v : def) * 1024 * 1024);
+}
+/** What one read may return: enough to work with, small enough to not drown a prompt. */
+export const READ_MAX_LINES = 400;
+const READ_MAX_CHARS = 60_000;
+const LINE_MAX_CHARS = 4_000;
+/** The index in a prompt never grows past this, however many items there are. */
+export const INDEX_CAP = 1_500;
+/** Items this small may be shown inline (once) in a task's prompt. */
+export const INLINE_MAX = 1_500;
+const SCHEMA = /* sql */ `
+CREATE TABLE IF NOT EXISTS context_item (
+  id TEXT PRIMARY KEY,
+  seq INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  title TEXT NOT NULL,
+  file TEXT NOT NULL,
+  mime TEXT NOT NULL DEFAULT '',
+  bytes INTEGER NOT NULL,
+  lines INTEGER NOT NULL DEFAULT 0,
+  sha256 TEXT NOT NULL,
+  added_by TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  summary TEXT NOT NULL DEFAULT '',
+  brain_summary TEXT NOT NULL DEFAULT '',
+  sections TEXT NOT NULL DEFAULT '[]',
+  source TEXT NOT NULL DEFAULT '',
+  removed_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS context_note (
+  id TEXT PRIMARY KEY,
+  item_id TEXT NOT NULL,
+  by TEXT NOT NULL,
+  body TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS context_link (
+  task_id TEXT NOT NULL,
+  item_id TEXT NOT NULL,
+  PRIMARY KEY (task_id, item_id)
+);
+`;
+// ---- kinds, languages, cheap summaries ---------------------------------------
+const IMAGE_EXT = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" };
+const TEXT_EXT = new Set(["txt", "log", "md", "markdown", "rst", "csv", "tsv", "json", "jsonl", "yaml", "yml", "toml", "ini", "cfg", "conf", "xml", "html", "htm", "svg", "env", "diff", "patch", "out", "err"]);
+const CODE_LANG = {
+    js: "javascript", mjs: "javascript", cjs: "javascript", jsx: "javascript", ts: "typescript", tsx: "typescript", py: "python", rb: "ruby", go: "go", rs: "rust",
+    java: "java", kt: "kotlin", swift: "swift", c: "c", h: "c", cc: "c++", cpp: "c++", hpp: "c++", cs: "c#", php: "php", sh: "shell", bash: "shell", zsh: "shell",
+    ps1: "powershell", sql: "sql", css: "css", scss: "scss", vue: "vue", svelte: "svelte", lua: "lua", dart: "dart", scala: "scala", ex: "elixir", exs: "elixir",
+    r: "r", m: "objective-c", zig: "zig", graphql: "graphql", proto: "protobuf", tf: "terraform", dockerfile: "dockerfile", makefile: "makefile",
+};
+const TEXT_LANG = { md: "markdown", markdown: "markdown", csv: "csv", tsv: "tsv", json: "json", jsonl: "jsonl", yaml: "yaml", yml: "yaml", toml: "toml", xml: "xml", html: "html", htm: "html", svg: "svg", log: "log", diff: "diff", patch: "diff" };
+const extOf = (name) => {
+    const base = path.basename(name).toLowerCase();
+    if (base === "dockerfile" || base === "makefile")
+        return base;
+    const i = base.lastIndexOf(".");
+    return i > 0 ? base.slice(i + 1) : "";
+};
+/** Does this buffer look like text? No NULs, valid UTF-8, few control chars. */
+export function looksText(buf) {
+    const head = buf.subarray(0, 8192);
+    if (head.includes(0))
+        return false;
+    const s = head.toString("utf8");
+    // A cut multi-byte char at the 8 KB edge is fine; replacement chars elsewhere aren't.
+    const bad = (s.slice(0, -4).match(/\uFFFD/g) ?? []).length;
+    const ctrl = (s.match(/[\x00-\x08\x0E-\x1A\x1C-\x1F]/g) ?? []).length;
+    return bad === 0 && ctrl <= s.length * 0.01;
+}
+/** Guess what a pasted text is, for the index line. */
+export function guessLang(text) {
+    const t = text.trimStart();
+    if (/^(Traceback \(most recent call last\)|\w*(Error|Exception)\b.*\n\s+at |.*\n\s+at [\w.<>$]+ \()/m.test(text) || /\n\s+at .+:\d+:\d+\)?$/m.test(text))
+        return "stack trace";
+    if (/^[{[]/.test(t)) {
+        try {
+            JSON.parse(t);
+            return "json";
+        }
+        catch {
+            /* not json */
+        }
+    }
+    if (/^diff --git |^@@ .* @@/m.test(text))
+        return "diff";
+    if (/^#{1,6} \S/m.test(text) || /^```/m.test(text))
+        return "markdown";
+    const lines = text.split("\n");
+    const codey = lines.filter((l) => /[;{}]\s*$|^\s*(import|export|from|def|class|function|const|let|var|return|public|private|func|fn|package|#include)\b/.test(l)).length;
+    if (codey >= Math.max(2, lines.length * 0.25))
+        return "code";
+    if (lines.length > 3 && lines.filter((l) => /^\d{4}-\d\d-\d\d|^\[?\d\d:\d\d:\d\d|\b(INFO|WARN|ERROR|DEBUG)\b/.test(l)).length >= lines.length * 0.3)
+        return "log";
+    return "text";
+}
+/** Split long text into sections: markdown headings, code fences, or ~200-line chunks. */
+export function sectionsOf(text, fileHeaders = false) {
+    const lines = text.split("\n");
+    const n = lines.length;
+    const cuts = [];
+    let fence = false;
+    lines.forEach((l, i) => {
+        if (fileHeaders) {
+            const m = /^===== (.+) =====$/.exec(l);
+            if (m)
+                cuts.push({ title: m[1], at: i + 1 });
+            return;
+        }
+        if (/^```/.test(l)) {
+            if (!fence)
+                cuts.push({ title: `code block${l.slice(3).trim() ? " (" + l.slice(3).trim() + ")" : ""}`, at: i + 1 });
+            fence = !fence;
+            return;
+        }
+        const h = !fence && /^(#{1,3}) (.+)/.exec(l);
+        if (h)
+            cuts.push({ title: h[2].trim().slice(0, 80), at: i + 1 });
+    });
+    let out = [];
+    if (cuts.length) {
+        if (cuts[0].at > 1)
+            cuts.unshift({ title: "(top)", at: 1 });
+        out = cuts.map((c, k) => ({ title: c.title, from: c.at, to: (cuts[k + 1]?.at ?? n + 1) - 1 }));
+    }
+    // Too few cuts for a long text, or none: fixed chunks keep every read under the cap.
+    if (!out.length || out.some((s) => s.to - s.from + 1 > 200)) {
+        if (n <= 200 && !out.length)
+            return [];
+        const chunked = [];
+        for (const s of out.length ? out : [{ title: "lines", from: 1, to: n }]) {
+            if (s.to - s.from + 1 <= 200) {
+                chunked.push(s);
+                continue;
+            }
+            for (let a = s.from; a <= s.to; a += 200)
+                chunked.push({ title: `${s.title === "lines" ? "lines" : s.title + " ·"} ${a}-${Math.min(s.to, a + 199)}`, from: a, to: Math.min(s.to, a + 199) });
+        }
+        out = chunked;
+    }
+    return out.slice(0, 200);
+}
+/** Width × height from the image header — cheap, no decoder. */
+export function imageSize(buf, mime) {
+    try {
+        if (mime === "image/png" && buf.length >= 24 && buf.toString("ascii", 1, 4) === "PNG")
+            return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+        if (mime === "image/gif" && buf.length >= 10)
+            return { w: buf.readUInt16LE(6), h: buf.readUInt16LE(8) };
+        if (mime === "image/webp" && buf.length >= 30 && buf.toString("ascii", 12, 16) === "VP8X")
+            return { w: 1 + buf.readUIntLE(24, 3), h: 1 + buf.readUIntLE(27, 3) };
+        if (mime === "image/jpeg") {
+            let i = 2;
+            while (i + 9 < buf.length) {
+                if (buf[i] !== 0xff)
+                    return null;
+                const marker = buf[i + 1];
+                const len = buf.readUInt16BE(i + 2);
+                if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker))
+                    return { w: buf.readUInt16BE(i + 7), h: buf.readUInt16BE(i + 5) };
+                i += 2 + len;
+            }
+        }
+    }
+    catch {
+        /* a broken header is just "no size" */
+    }
+    return null;
+}
+const human = (n) => (n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(n < 10 * 1024 ? 1 : 0)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`);
+export const fmtBytes = human;
+/** The deterministic summary: language, headings / symbols / columns, the first error. */
+export function summarize(kind, text, lang, extra = "") {
+    if (!text)
+        return [lang, extra].filter(Boolean).join(" · ");
+    const lines = text.split("\n");
+    const bits = [];
+    if (lang)
+        bits.push(lang);
+    if (lang === "markdown") {
+        const hs = lines.filter((l) => /^#{1,3} \S/.test(l)).map((l) => l.replace(/^#+ /, "").trim());
+        if (hs.length)
+            bits.push("headings: " + hs.slice(0, 6).join(" / ") + (hs.length > 6 ? ` (+${hs.length - 6})` : ""));
+    }
+    else if (lang === "csv" || lang === "tsv") {
+        bits.push(`columns: ${lines[0].slice(0, 120)}`, `${Math.max(0, lines.filter(Boolean).length - 1)} rows`);
+    }
+    else if (lang === "json") {
+        try {
+            const j = JSON.parse(text);
+            bits.push(Array.isArray(j) ? `array of ${j.length}` : "keys: " + Object.keys(j).slice(0, 8).join(", "));
+        }
+        catch {
+            /* not one JSON value */
+        }
+    }
+    else if (kind === "code" || lang === "code") {
+        const syms = [...text.matchAll(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|def|func|fn|interface|type|struct|enum)\s+([A-Za-z_$][\w$]*)/gm)].map((m) => m[1]);
+        if (syms.length)
+            bits.push("defines: " + [...new Set(syms)].slice(0, 8).join(", "));
+    }
+    else if (lang === "stack trace" || lang === "log") {
+        const err = lines.find((l) => /error|exception|failed|fatal|panic/i.test(l));
+        if (err)
+            bits.push(err.trim().slice(0, 120));
+    }
+    if (extra)
+        bits.push(extra);
+    return bits.join(" · ").slice(0, 300);
+}
+const SECRET_PATTERNS = [
+    { kind: "private key", re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g },
+    { kind: "Anthropic key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+    { kind: "OpenAI key", re: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}/g },
+    { kind: "AWS access key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { kind: "AWS secret", re: /\baws_secret_access_key\s*[=:]\s*["']?[A-Za-z0-9/+=]{40}["']?/gi },
+    { kind: "GitHub token", re: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})\b/g },
+    { kind: "Slack token", re: /\bxox[abprse]-[A-Za-z0-9-]{10,}/g },
+    { kind: "Google API key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    { kind: "Stripe key", re: /\b(?:sk|rk)_live_[0-9A-Za-z]{16,}\b/g },
+    // .env-style lines: NAME_KEY=value, NAME_TOKEN: value, PASSWORD=…
+    { kind: ".env secret", re: /^[ \t]*(?:export[ \t]+)?[A-Za-z_][A-Za-z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|PWD|CREDENTIALS?|AUTH)[A-Za-z0-9_]*[ \t]*[=:][ \t]*["']?[^\s"'#]{6,}["']?/gim },
+];
+const mask = (s) => (s.length <= 10 ? "****" : `${s.slice(0, 6)}…${s.slice(-2)}`);
+/** Likely secrets in a text: API keys, tokens, private keys, .env lines. */
+export function scanSecrets(text) {
+    const hits = [];
+    const taken = [];
+    for (const { kind, re } of SECRET_PATTERNS) {
+        for (const m of text.matchAll(re)) {
+            const a = m.index ?? 0;
+            const b = a + m[0].length;
+            if (taken.some(([x, y]) => a < y && b > x))
+                continue; // one hit per span (sk-ant- is not also an OpenAI key)
+            taken.push([a, b]);
+            hits.push({ kind, line: text.slice(0, a).split("\n").length, preview: mask(m[0].split("\n")[0].trim()) });
+        }
+    }
+    return hits.sort((x, y) => x.line - y.line);
+}
+/** Replace every likely secret with [REDACTED:<kind>]. .env lines keep their name. */
+export function redactSecrets(text) {
+    let count = 0;
+    let out = text;
+    for (const { kind, re } of SECRET_PATTERNS) {
+        out = out.replace(re, (m) => {
+            if (/^\[REDACTED/.test(m))
+                return m;
+            if (kind !== ".env secret")
+                count++;
+            if (kind === ".env secret") {
+                if (/[=:][ \t]*["']?\[REDACTED/.test(m))
+                    return m; // its value was already a known key
+                count++;
+                const eq = /^([^=:]*[=:][ \t]*)/.exec(m);
+                return `${eq ? eq[1] : ""}[REDACTED:secret]`;
+            }
+            return `[REDACTED:${kind}]`;
+        });
+    }
+    return { text: out, count };
+}
+// ---- dropped paths -----------------------------------------------------------------
+/**
+ * Split a line the way a terminal pastes a dragged file: 'quoted paths',
+ * "double quoted", escaped\ spaces, file:// URLs, Windows C:\paths. A
+ * backslash only escapes shell-special characters, so C:\Users stays intact.
+ */
+export function splitPathTokens(line) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    let had = false;
+    const s = line.trim();
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (quote) {
+            if (c === quote)
+                quote = null;
+            else
+                cur += c;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            had = true;
+            continue;
+        }
+        // A backslash never escapes a backslash: that is a UNC path or a Windows separator.
+        if (c === "\\" && i + 1 < s.length && /[\s'"()\[\]{}&;!$#*?<>|~`,]/.test(s[i + 1])) {
+            cur += s[++i];
+            had = true;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            if (cur || had)
+                out.push(cur);
+            cur = "";
+            had = false;
+            continue;
+        }
+        cur += c;
+        had = true;
+    }
+    if (cur || had)
+        out.push(cur);
+    return out.map(normalizePathToken).filter(Boolean);
+}
+/** One path as a person typed or dropped it: file:// URLs and ~ resolved. */
+export function normalizePathToken(t) {
+    if (/^file:\/\//i.test(t)) {
+        try {
+            // file:///C:/x → C:/x on Windows; file:///Users/x → /Users/x
+            let p = decodeURIComponent(new URL(t).pathname);
+            if (/^\/[A-Za-z]:\//.test(p))
+                p = p.slice(1);
+            return p;
+        }
+        catch {
+            return t;
+        }
+    }
+    if (t === "~" || t.startsWith("~/"))
+        return path.join(os.homedir(), t.slice(1));
+    return t;
+}
+/** A path a drag-and-drop would paste: absolute (/x, ~/x, C:\x, \\server\x) or file://. */
+export function isAbsoluteish(p) {
+    return path.isAbsolute(p) || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\");
+}
+/**
+ * If the whole line is just one or more existing absolute paths (a dragged
+ * file, or a few), return them. Anything else — a goal that mentions a path,
+ * a missing file — is not a drop.
+ */
+export function droppedPaths(line, exists = fs.existsSync) {
+    if (!line.trim() || line.length > 8000 || /\n/.test(line.trim()))
+        return null;
+    const toks = splitPathTokens(line);
+    if (!toks.length || !toks.every(isAbsoluteish))
+        return null;
+    return toks.every((t) => exists(t)) ? toks : null;
+}
+// ---- folders & globs -------------------------------------------------------------
+const SKIP_DIRS = new Set([".git", "node_modules", ".huddle", "dist", "build", "out", ".next", ".nuxt", ".venv", "venv", "env", "__pycache__", "target", "coverage", ".cache", ".idea", ".vscode", ".turbo", "vendor", ".gradle", "Pods"]);
+const SKIP_FILES = /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|poetry\.lock|\.DS_Store)$|\.(min\.js|map|lock)$/i;
+/** A tiny .gitignore reader: names, dir/, *.ext, /rooted — enough to skip the usual noise. */
+function ignoreRules(dir) {
+    let txt = "";
+    try {
+        txt = fs.readFileSync(path.join(dir, ".gitignore"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    return txt
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#") && !l.startsWith("!"))
+        .map((pat) => {
+        const dirOnly = pat.endsWith("/");
+        const p = pat.replace(/\/$/, "").replace(/^\//, "");
+        const re = globRe(p.includes("/") ? p : `**/${p}`);
+        return (rel, isDir) => (!dirOnly || isDir) && re.test(rel);
+    });
+}
+/** Glob → RegExp over forward-slash relative paths: *, **, ?, [abc], {a,b}. */
+export function globRe(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                i++;
+                if (glob[i + 1] === "/") {
+                    i++;
+                    re += "(?:.*/)?";
+                }
+                else
+                    re += ".*";
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else if (c === "[") {
+            const j = glob.indexOf("]", i);
+            if (j < 0)
+                re += "\\[";
+            else {
+                re += glob.slice(i, j + 1);
+                i = j;
+            }
+        }
+        else if (c === "{") {
+            const j = glob.indexOf("}", i);
+            if (j < 0)
+                re += "\\{";
+            else {
+                re += "(?:" + glob.slice(i + 1, j).split(",").map((x) => x.replace(/[.+^$()|\\]/g, "\\$&").replace(/\*/g, "[^/]*")).join("|") + ")";
+                i = j;
+            }
+        }
+        else
+            re += c.replace(/[.+^$()|\\]/g, "\\$&");
+    }
+    return new RegExp(`^${re}$`);
+}
+export const isGlob = (p) => /[*?[{]/.test(p);
+/**
+ * Every file under `dir` (relative, forward slashes), skipping the usual
+ * build/vendor dirs and .gitignore'd paths. Never follows a symlinked folder
+ * (no loops); stops at `max`.
+ */
+export function walk(dir, max = CAPS.folderFiles * 4) {
+    const files = [];
+    let skipped = 0;
+    const rules = ignoreRules(dir);
+    const seen = new Set();
+    const visit = (abs, rel) => {
+        let real;
+        try {
+            real = fs.realpathSync(abs);
+        }
+        catch {
+            return;
+        }
+        if (seen.has(real))
+            return;
+        seen.add(real);
+        let ents;
+        try {
+            ents = fs.readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            skipped++;
+            return;
+        }
+        ents.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of ents) {
+            if (files.length >= max)
+                return;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isSymbolicLink()) {
+                // A symlinked file is fine; a symlinked folder could loop.
+                try {
+                    if (!fs.statSync(path.join(abs, e.name)).isFile())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+            }
+            else if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name) || rules.some((f) => f(r, true)))
+                    continue;
+                visit(path.join(abs, e.name), r);
+                continue;
+            }
+            if (SKIP_FILES.test(r) || rules.some((f) => f(r, false)))
+                continue;
+            files.push(r);
+        }
+    };
+    visit(dir, "");
+    return { files, skipped };
+}
+/** Expand a glob (relative to cwd, or absolute) to the files it matches. */
+export function expandGlob(pattern, cwd = process.cwd()) {
+    const norm = pattern.replace(/\\/g, "/");
+    const parts = norm.split("/");
+    const firstGlob = parts.findIndex(isGlob);
+    const baseRel = parts.slice(0, firstGlob).join("/");
+    const base = path.resolve(cwd, baseRel || ".");
+    const rest = parts.slice(firstGlob).join("/");
+    const re = globRe(rest);
+    if (!fs.existsSync(base))
+        return [];
+    return walk(base).files.filter((f) => re.test(f)).map((f) => path.join(base, f));
+}
+const stores = new WeakMap();
+export class ContextStore {
+    db;
+    dir;
+    constructor(db) {
+        this.db = db;
+        // Next to the Room db: <repo>/.huddle/huddle.db → <repo>/.huddle/context/.
+        // Attach mode's live room (.huddle/live.db) is a separate db with its own
+        // ctx-N numbering, so its files go in .huddle/live-context/ — sharing one
+        // folder would let the two stores overwrite each other's ctx-1.
+        this.dir =
+            db.path === ":memory:"
+                ? fs.mkdtempSync(path.join(os.tmpdir(), "huddle-ctx-"))
+                : path.join(path.dirname(db.path), path.basename(db.path) === "live.db" ? "live-context" : "context");
+        db.sql.exec(SCHEMA);
+    }
+    /** The store for a Room (one per db, made on first use). */
+    static open(db) {
+        let s = stores.get(db);
+        if (!s) {
+            s = new ContextStore(db);
+            stores.set(db, s);
+        }
+        return s;
+    }
+    // ---- reading -------------------------------------------------------------
+    rows(sql, ...params) {
+        const rows = this.db.sql.prepare(sql).all(...params);
+        if (!rows.length)
+            return [];
+        const notes = this.db.sql.prepare("SELECT * FROM context_note ORDER BY created_at, rowid").all();
+        return rows.map((r) => {
+            const { seq: _s, removed_at: _r, sections, ...rest } = r;
+            return { ...rest, sections: JSON.parse(sections || "[]"), notes: notes.filter((n) => n.item_id === r.id) };
+        });
+    }
+    list() {
+        return this.rows("SELECT * FROM context_item WHERE removed_at IS NULL ORDER BY seq");
+    }
+    get(id) {
+        return this.rows("SELECT * FROM context_item WHERE id=? AND removed_at IS NULL", normId(id))[0];
+    }
+    /** Absolute path of an item's file on this machine. */
+    pathOf(item) {
+        return path.join(this.dir, item.file);
+    }
+    totalBytes() {
+        return this.db.sql.prepare("SELECT COALESCE(SUM(bytes),0) AS n FROM context_item WHERE removed_at IS NULL").get().n;
+    }
+    // ---- preparing (nothing written yet: the caller may ask about secrets) ---
+    /** A paste (or stdin) as an item. */
+    prepareText(raw, opts = {}) {
+        // CRLF → LF; stray control chars from a terminal (not tabs/newlines) dropped.
+        const text = raw.replace(/\r\n?/g, "\n").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "").replace(/\n+$/, "");
+        if (!text.trim())
+            return { ok: false, reason: "that paste is empty" };
+        const data = Buffer.from(text, "utf8");
+        if (data.length > CAPS.textBytes)
+            return { ok: false, reason: `that paste is ${human(data.length)} — over the ${human(CAPS.textBytes)} text cap. Save it to a file and add a part of it, or raise HUDDLE_CTX_MAX_TEXT_MB` };
+        const lang = guessLang(text);
+        const first = text.split("\n").find((l) => l.trim()) ?? "";
+        return {
+            kind: lang === "code" || lang === "stack trace" || lang === "diff" ? "code" : "text",
+            title: (opts.title ?? first.trim()).replace(/\s+/g, " ").slice(0, 60) + (!opts.title && first.trim().length > 60 ? "…" : ""),
+            ext: lang === "markdown" ? "md" : lang === "json" ? "json" : lang === "diff" ? "diff" : "txt",
+            mime: "text/plain",
+            data,
+            text,
+            lang,
+            source: opts.source ?? "paste",
+            bundle: false,
+            secrets: scanSecrets(text),
+            warnings: [],
+        };
+    }
+    /** A file or a folder (its text files, as one bundle item). */
+    preparePath(p, cwd = process.cwd()) {
+        const abs = path.resolve(cwd, p);
+        let st;
+        try {
+            st = fs.statSync(abs);
+        }
+        catch (e) {
+            if (e?.code === "EACCES" || e?.code === "EPERM")
+                return { ok: false, reason: `can't read ${p} — permission denied` };
+            return { ok: false, reason: `no such file: ${p}` };
+        }
+        if (st.isDirectory())
+            return this.prepareBundle(path.basename(abs) + "/", abs, walk(abs).files.map((f) => path.join(abs, f)));
+        if (!st.isFile())
+            return { ok: false, reason: `${p} isn't a regular file` };
+        const name = path.basename(abs);
+        const ext = extOf(name);
+        const isImage = ext in IMAGE_EXT;
+        const isPdf = ext === "pdf";
+        const knownText = !isImage && !isPdf && (TEXT_EXT.has(ext) || ext in CODE_LANG);
+        // Text is capped tighter than files: it is what agents actually read.
+        const cap = knownText ? CAPS.textBytes : CAPS.fileBytes;
+        if (st.size > cap)
+            return { ok: false, reason: `${name} is ${human(st.size)} — over the ${human(cap)} ${knownText ? "text" : "file"} cap (${knownText ? "HUDDLE_CTX_MAX_TEXT_MB" : "HUDDLE_CTX_MAX_FILE_MB"} raises it)` };
+        let data;
+        try {
+            data = fs.readFileSync(abs);
+        }
+        catch (e) {
+            return { ok: false, reason: e?.code === "EACCES" || e?.code === "EPERM" ? `can't read ${name} — permission denied` : `couldn't read ${name}: ${e?.message ?? e}` };
+        }
+        if (isImage) {
+            const mime = IMAGE_EXT[ext];
+            return { kind: "image", title: name, ext, mime, data, text: null, lang: ext, source: name, bundle: false, secrets: [], warnings: [] };
+        }
+        if (isPdf)
+            return { kind: "pdf", title: name, ext, mime: "application/pdf", data, text: null, lang: "pdf", source: name, bundle: false, secrets: [], warnings: [] };
+        if (knownText || looksText(data)) {
+            if (data.length > CAPS.textBytes)
+                return { ok: false, reason: `${name} is ${human(data.length)} of text — over the ${human(CAPS.textBytes)} text cap (HUDDLE_CTX_MAX_TEXT_MB raises it)` };
+            const text = data.toString("utf8").replace(/\r\n?/g, "\n");
+            const lang = CODE_LANG[ext] ?? TEXT_LANG[ext] ?? guessLang(text);
+            return {
+                kind: ext in CODE_LANG ? "code" : "text",
+                title: name,
+                ext: ext || "txt",
+                mime: "text/plain",
+                data: Buffer.from(text, "utf8"),
+                text,
+                lang,
+                source: name,
+                bundle: false,
+                secrets: scanSecrets(text),
+                warnings: [],
+            };
+        }
+        return { kind: "file", title: name, ext: ext || "bin", mime: "application/octet-stream", data, text: null, lang: ext || "binary", source: name, bundle: false, secrets: [], warnings: [`${name} is binary — agents get its path, not its contents`] };
+    }
+    /** Several files in one item: "===== path =====" headers, one section per file. */
+    prepareBundle(title, base, files) {
+        const parts = [];
+        const skipped = [];
+        let bytes = 0;
+        for (const f of files) {
+            if (parts.length >= CAPS.folderFiles) {
+                skipped.push(`${files.length - CAPS.folderFiles} more file(s) past the ${CAPS.folderFiles}-file cap`);
+                break;
+            }
+            const rel = path.relative(base, f).replace(/\\/g, "/") || path.basename(f);
+            let data;
+            try {
+                if (fs.statSync(f).size > CAPS.textBytes) {
+                    skipped.push(`${rel} (too big)`);
+                    continue;
+                }
+                data = fs.readFileSync(f);
+            }
+            catch {
+                skipped.push(`${rel} (unreadable)`);
+                continue;
+            }
+            const ext = extOf(f);
+            if (ext in IMAGE_EXT || ext === "pdf" || !looksText(data)) {
+                skipped.push(`${rel} (binary — add it on its own)`);
+                continue;
+            }
+            if (bytes + data.length > CAPS.textBytes) {
+                skipped.push(`${rel} and the rest (the bundle hit the ${human(CAPS.textBytes)} text cap)`);
+                break;
+            }
+            bytes += data.length;
+            parts.push(`===== ${rel} =====\n${data.toString("utf8").replace(/\r\n?/g, "\n").replace(/\n+$/, "")}`);
+        }
+        if (!parts.length)
+            return { ok: false, reason: `no text files in ${title}${skipped.length ? ` (skipped: ${skipped.slice(0, 3).join(", ")})` : ""}` };
+        const text = parts.join("\n");
+        return {
+            kind: "code",
+            title: title.slice(0, 60),
+            ext: "txt",
+            mime: "text/plain",
+            data: Buffer.from(text, "utf8"),
+            text,
+            lang: `${parts.length} files`,
+            source: title,
+            bundle: true,
+            secrets: scanSecrets(text),
+            warnings: skipped.length ? [`skipped ${skipped.length}: ${skipped.slice(0, 4).join(", ")}${skipped.length > 4 ? ", …" : ""}`] : [],
+        };
+    }
+    // ---- writing --------------------------------------------------------------
+    /** Save a prepared item. `redact` (default true) rewrites likely secrets first. */
+    commit(p, opts = {}) {
+        let data = p.data;
+        let text = p.text;
+        let redacted = 0;
+        if (text !== null && p.secrets.length && opts.redact !== false) {
+            const r = redactSecrets(text);
+            text = r.text;
+            redacted = r.count;
+            data = Buffer.from(text, "utf8");
+        }
+        const sha = crypto.createHash("sha256").update(data).digest("hex");
+        const dup = this.rows("SELECT * FROM context_item WHERE sha256=? AND removed_at IS NULL", sha)[0];
+        if (dup)
+            return { ok: true, item: dup, duplicate: true };
+        const live = this.list();
+        if (live.length >= CAPS.items)
+            return { ok: false, reason: `the screen already has ${live.length} items — ctx rm some first` };
+        const total = this.totalBytes();
+        if (total + data.length > CAPS.totalBytes)
+            return { ok: false, reason: `the screen is full (${human(total)} of ${human(CAPS.totalBytes)}) — ctx rm some items, or raise HUDDLE_CTX_MAX_TOTAL_MB` };
+        const seq = (this.db.sql.prepare("SELECT MAX(seq) AS n FROM context_item").get().n ?? 0) + 1;
+        const id = `ctx-${seq}`;
+        const file = `${id}.${p.ext.replace(/[^\w]/g, "") || "bin"}`;
+        fs.mkdirSync(this.dir, { recursive: true });
+        fs.writeFileSync(path.join(this.dir, file), data);
+        const lines = text === null ? 0 : text.split("\n").length;
+        let extra = "";
+        if (p.kind === "image") {
+            const sz = imageSize(data, p.mime);
+            extra = sz ? `${sz.w}×${sz.h}` : "";
+        }
+        else if (p.kind === "pdf") {
+            const pages = (data.toString("latin1").match(/\/Type\s*\/Page(?!s)/g) ?? []).length;
+            extra = pages ? `${pages} page${pages > 1 ? "s" : ""}` : "";
+        }
+        const item = {
+            id,
+            kind: p.kind,
+            title: p.title || id,
+            file,
+            mime: p.mime,
+            bytes: data.length,
+            lines,
+            sha256: sha,
+            added_by: opts.by ?? "you",
+            created_at: Date.now(),
+            summary: summarize(p.kind, text, p.lang, extra),
+            brain_summary: "",
+            sections: text === null ? [] : sectionsOf(text, p.bundle),
+            source: p.source,
+            notes: [],
+        };
+        this.db.sql
+            .prepare(`INSERT INTO context_item (id,seq,kind,title,file,mime,bytes,lines,sha256,added_by,created_at,summary,brain_summary,sections,source)
+         VALUES (@id,@seq,@kind,@title,@file,@mime,@bytes,@lines,@sha256,@added_by,@created_at,@summary,@brain_summary,@sections,@source)`)
+            .run({
+            id,
+            seq,
+            kind: item.kind,
+            title: item.title,
+            file,
+            mime: item.mime,
+            bytes: item.bytes,
+            lines,
+            sha256: sha,
+            added_by: item.added_by,
+            created_at: item.created_at,
+            summary: item.summary,
+            brain_summary: "",
+            sections: JSON.stringify(item.sections),
+            source: item.source,
+        });
+        this.writeMirror();
+        this.db.publish("context.added", { agent_id: null, payload: { id, kind: item.kind, title: item.title, bytes: item.bytes, lines, by: item.added_by, summary: item.summary, redacted } });
+        const announced = opts.announce === false ? [] : this.announce(item);
+        return { ok: true, item, ...(redacted ? { redacted } : {}), ...(p.warnings.length ? { warnings: p.warnings } : {}), ...(announced.length ? { announced } : {}) };
+    }
+    addText(text, opts = {}) {
+        const p = this.prepareText(text, opts);
+        return "ok" in p ? p : this.commit(p, opts);
+    }
+    addPath(p, opts = {}) {
+        const prep = this.preparePath(p, opts.cwd);
+        return "ok" in prep ? prep : this.commit(prep, opts);
+    }
+    /**
+     * Mid-run: tell every agent working right now, through its inbox (the same
+     * path huddle_send uses), so nobody finishes without seeing the new item.
+     */
+    announce(item) {
+        const working = this.db.listAgents().filter((a) => a.status === "working").map((a) => a.id);
+        const what = item.kind === "image" ? "screenshot" : item.kind;
+        for (const to of working)
+            this.db.sendMessage({
+                from: item.added_by,
+                to,
+                kind: "note",
+                body: `📎 new on the screen from ${item.added_by}: ${item.id} ${what} '${item.title}' — huddle_context_read ${item.id}`,
+            });
+        return working;
+    }
+    remove(id, by = "you") {
+        const it = this.get(id);
+        if (!it)
+            return false;
+        this.db.sql.prepare("UPDATE context_item SET removed_at=? WHERE id=?").run(Date.now(), it.id);
+        this.db.sql.prepare("DELETE FROM context_link WHERE item_id=?").run(it.id);
+        try {
+            fs.rmSync(this.pathOf(it), { force: true });
+            fs.rmSync(this.pathOf(it) + ".txt", { force: true });
+        }
+        catch {
+            /* already gone */
+        }
+        this.writeMirror();
+        this.db.publish("context.removed", { payload: { id: it.id, title: it.title, by } });
+        return true;
+    }
+    /** A comment pinned on an item — every agent and person sees it in the index. */
+    note(id, body, by) {
+        const it = this.get(id);
+        if (!it)
+            return { error: `no item ${id} on the screen — huddle_context lists them` };
+        const text = String(body ?? "").replace(/\s+/g, " ").trim().slice(0, 1000);
+        if (!text)
+            return { error: "empty note" };
+        const n = { id: crypto.randomBytes(4).toString("hex"), item_id: it.id, by, body: text, created_at: Date.now() };
+        this.db.sql.prepare("INSERT INTO context_note (id,item_id,by,body,created_at) VALUES (@id,@item_id,@by,@body,@created_at)").run(n);
+        this.writeMirror();
+        this.db.publish("context.note", { agent_id: by, payload: { id: it.id, title: it.title, by, body: text } });
+        return n;
+    }
+    setBrainSummary(id, s) {
+        this.db.sql.prepare("UPDATE context_item SET brain_summary=? WHERE id=?").run(s.replace(/\s+/g, " ").trim().slice(0, 200), normId(id));
+        this.writeMirror();
+    }
+    /** The planner tied these items to a task: they ride in that task's prompt. */
+    link(taskId, ids) {
+        const ok = ids.map(normId).filter((id) => this.get(id));
+        for (const id of ok)
+            this.db.sql.prepare("INSERT OR IGNORE INTO context_link (task_id,item_id) VALUES (?,?)").run(taskId, id);
+        if (ok.length)
+            this.writeMirror();
+        return ok;
+    }
+    linked(taskId) {
+        const ids = this.db.sql.prepare("SELECT item_id FROM context_link WHERE task_id=?").all(taskId).map((r) => r.item_id);
+        return this.list().filter((i) => ids.includes(i.id));
+    }
+    /** index.json: the same rows as plain JSON next to the files. */
+    writeMirror() {
+        const links = {};
+        for (const r of this.db.sql.prepare("SELECT task_id, item_id FROM context_link").all())
+            (links[r.task_id] ??= []).push(r.item_id);
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            const tmp = path.join(this.dir, `index.json.${process.pid}.tmp`);
+            fs.writeFileSync(tmp, JSON.stringify({ items: this.list(), links }, null, 1));
+            fs.renameSync(tmp, path.join(this.dir, "index.json"));
+        }
+        catch {
+            /* the db is the truth; a missing mirror only means a shorter prompt */
+        }
+    }
+    // ---- reading content -------------------------------------------------------
+    /** An item's text: the file itself, or a PDF's extracted text (pdftotext, if installed). */
+    textOf(item) {
+        if (item.kind === "text" || item.kind === "code") {
+            try {
+                return fs.readFileSync(this.pathOf(item), "utf8");
+            }
+            catch {
+                return null;
+            }
+        }
+        if (item.kind === "pdf")
+            return pdfText(this.pathOf(item));
+        return null;
+    }
+}
+export const normId = (id) => {
+    const s = String(id ?? "").trim().toLowerCase();
+    const m = /^(?:ctx[-_ ]?)?(\d+)$/.exec(s);
+    return m ? `ctx-${m[1]}` : s;
+};
+/** A PDF's text via poppler's pdftotext, cached next to it. null if unavailable. */
+export function pdfText(file) {
+    const cache = file + ".txt";
+    try {
+        if (fs.existsSync(cache))
+            return fs.readFileSync(cache, "utf8");
+    }
+    catch {
+        /* re-extract */
+    }
+    const r = spawnToolSync(["pdftotext", "-layout", file, cache], { timeout: 20_000, stdio: "ignore" });
+    if (r.status !== 0)
+        return null;
+    try {
+        return fs.readFileSync(cache, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+// ---- the index (what prompts carry instead of content) --------------------------
+const kindWord = (i) => (i.kind === "image" ? "image" : i.kind);
+const sizeOf = (i) => (i.lines && (i.kind === "text" || i.kind === "code") ? `${i.lines} line${i.lines === 1 ? "" : "s"}, ${human(i.bytes)}` : human(i.bytes));
+/** One line per item: id · kind · title · size · summary (+ the latest note). */
+export function indexLine(i, max = 220) {
+    const sum = i.brain_summary || i.summary;
+    const note = i.notes.at(-1);
+    let s = `- ${i.id} · ${kindWord(i)} · "${i.title}" · ${sizeOf(i)}${sum ? " · " + sum : ""}`;
+    if (note)
+        s += ` · 📌 ${note.by}: ${note.body}`;
+    if (i.notes.length > 1)
+        s += ` (+${i.notes.length - 1} note${i.notes.length > 2 ? "s" : ""})`;
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+/** The whole index, newest first if it must be cut, never over `cap` chars. */
+export function screenIndex(items, cap = INDEX_CAP) {
+    if (!items.length)
+        return "";
+    const lines = [];
+    let used = 0;
+    const newestFirst = [...items].reverse();
+    let shown = 0;
+    for (const it of newestFirst) {
+        const l = indexLine(it);
+        if (used + l.length + 1 > cap - 60)
+            break;
+        lines.push(l);
+        used += l.length + 1;
+        shown++;
+    }
+    lines.reverse();
+    if (shown < items.length)
+        lines.unshift(`- …${items.length - shown} older item(s) — huddle_context lists them all`);
+    return lines.join("\n");
+}
+const READ_HINT = `Open one with huddle_context_read(id) (≤${READ_MAX_LINES} lines per call; from_line/to_line or section for a part; images & PDFs come back as a file path to open), find text with huddle_context_search(query), and pin what you learn on an item with huddle_context_note(id, note) — everyone sees notes.`;
+/** The index as a mirror reader sees it (launcher, planner): .huddle/context/index.json. */
+export function readMirror(repoRoot) {
+    const dir = path.join(repoRoot, ".huddle", "context");
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(dir, "index.json"), "utf8"));
+        return { items: Array.isArray(j.items) ? j.items : [], links: j.links ?? {}, dir };
+    }
+    catch {
+        return { items: [], links: {}, dir };
+    }
+}
+function inlineText(dir, it) {
+    if ((it.kind !== "text" && it.kind !== "code") || it.bytes > INLINE_MAX)
+        return null;
+    try {
+        return fs.readFileSync(path.join(dir, it.file), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The SHARED SCREEN section of the planner's / council's repo snapshot: the
+ * index, plus small text items inline (one prompt, so a bigger budget than a
+ * task's), and how to tie items to tasks in the plan JSON.
+ */
+export function screenForPlanner(repoRoot, inlineBudget = 6_000) {
+    const { items, dir } = readMirror(repoRoot);
+    if (!items.length)
+        return "";
+    const out = [
+        `SHARED SCREEN — what the user put up for the whole team (pastes, files, screenshots). Workers don't get copies; they open items with huddle_context_read. The newest item is usually what the goal is about.`,
+        screenIndex(items),
+        `When a task needs an item, add "context": ["ctx-N"] to that task in your JSON (Huddle hands those items to that task's agent), and write the requirements the task needs from it into its spec.`,
+    ];
+    let budget = inlineBudget;
+    for (const it of [...items].reverse()) {
+        if (it.kind !== "text" && it.kind !== "code")
+            continue;
+        let body;
+        try {
+            body = fs.readFileSync(path.join(dir, it.file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (budget < 300)
+            break;
+        const part = body.length > budget ? body.slice(0, budget) + `\n…(${it.lines} lines in all — the rest via huddle_context_read)` : body;
+        budget -= part.length;
+        out.push(`--- ${it.id} "${it.title}" ---\n${part}`);
+    }
+    return out.join("\n");
+}
+/**
+ * The SHARED SCREEN section of one task's launch prompt: the index, then the
+ * items the planner linked to this task (paths for images/PDFs, small ones
+ * inline). `images`: linked screenshots, for CLIs that attach images at launch.
+ */
+export function screenForTask(repoRoot, taskId) {
+    const { items, links, dir } = readMirror(repoRoot);
+    if (!items.length)
+        return { text: "", images: [], dir: null };
+    const mine = items.filter((i) => (links[taskId] ?? []).includes(i.id));
+    const out = [`SHARED SCREEN (one copy in the Room for the whole team, not pasted into your prompt):`, screenIndex(items)];
+    if (mine.length) {
+        out.push(`FOR THIS TASK the planner linked: ${mine.map((i) => i.id).join(", ")}`);
+        for (const it of mine) {
+            const abs = path.join(dir, it.file);
+            const what = it.kind === "image" ? "an image" : it.kind === "pdf" ? "a PDF" : it.kind === "file" ? "a file" : "";
+            if (what)
+                out.push(`- ${it.id} is ${what} at ${abs} — open it with your file/image reading tool`);
+            const body = inlineText(dir, it);
+            if (body)
+                out.push(`--- ${it.id} "${it.title}" ---\n${body}\n---`);
+        }
+    }
+    out.push(READ_HINT);
+    return {
+        text: out.join("\n"),
+        images: mine.filter((i) => i.kind === "image").map((i) => path.join(dir, i.file)),
+        dir,
+    };
+}
+/** The short line seedBoard adds to a linked task's spec (teammates' machines have no mirror). */
+export function linkedLine(items) {
+    if (!items.length)
+        return "";
+    return `\n\nOn the shared screen for this task: ${items.map((i) => `${i.id} (${kindWord(i)} "${i.title}")`).join(", ")} — open with huddle_context_read(id).`;
+}
+/** The planner's context ids, however they came back: "ctx-2", "ctx2", 2. */
+export function parseContextIds(v) {
+    const arr = Array.isArray(v) ? v : typeof v === "string" ? v.split(/[\s,]+/) : [];
+    return [...new Set(arr.map(normId).filter((x) => /^ctx-\d+$/.test(x)))];
+}
+/**
+ * seedBoard's hook: tie the plan's context ids to the new tasks and add a
+ * one-line pointer to each linked task's spec (teammates' machines read the
+ * spec, not this mirror). A one-task plan (or the template fallback) gets the
+ * whole screen. Returns the ids linked per task.
+ */
+export function linkPlan(db, taskIds, planned) {
+    const store = ContextStore.open(db);
+    const items = store.list();
+    if (!items.length)
+        return taskIds.map(() => []);
+    const anyLinks = planned.some((p) => p.context?.length);
+    return taskIds.map((tid, k) => {
+        const want = anyLinks ? planned[k]?.context ?? [] : planned.length === 1 ? items.map((i) => i.id) : [];
+        const ok = store.link(tid, want);
+        const line = linkedLine(items.filter((i) => ok.includes(i.id)));
+        if (line)
+            db.sql.prepare("UPDATE task SET spec = spec || ? WHERE id=?").run(line, tid);
+        return ok;
+    });
+}
+/** huddle_context, _read, _search, _note — for local agents and (via the shared door) teammates'. */
+export function contextVerb(db, verb, body, agentId) {
+    const store = ContextStore.open(db);
+    // A teammate's agent is on another machine: never hand it this machine's paths.
+    const remote = !!body?._shared;
+    switch (verb) {
+        case "context": {
+            const items = store.list();
+            return {
+                status: 200,
+                body: {
+                    items: items.map((i) => ({
+                        id: i.id,
+                        kind: i.kind,
+                        title: i.title,
+                        size: sizeOf(i),
+                        added_by: i.added_by,
+                        summary: i.brain_summary || i.summary,
+                        sections: i.sections.slice(0, 40).map((s, k) => `${k + 1}. ${s.title} (lines ${s.from}-${s.to})`),
+                        notes: i.notes.slice(-5).map((n) => `${n.by}: ${n.body}`),
+                    })),
+                    note: items.length ? READ_HINT : "Nothing on the shared screen yet.",
+                },
+            };
+        }
+        case "context_read":
+            return readVerb(db, store, body, agentId, remote);
+        case "context_search": {
+            const q = String(body.query ?? body.q ?? "").trim();
+            if (!q)
+                return { status: 400, body: { error: "give a query" } };
+            let re;
+            try {
+                re = body.regex ? new RegExp(q, "i") : new RegExp(q.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i");
+            }
+            catch (e) {
+                return { status: 400, body: { error: `bad regex: ${e?.message ?? e}` } };
+            }
+            const matches = [];
+            let more = 0;
+            for (const it of store.list()) {
+                const t = store.textOf(it);
+                if (t === null)
+                    continue;
+                t.split("\n").forEach((l, k) => {
+                    const m = re.exec(l);
+                    if (!m)
+                        return;
+                    if (matches.length >= 50)
+                        return void more++;
+                    // A match in a huge line: show the part around it.
+                    const at = m.index;
+                    const text = l.length > 300 ? `${at > 120 ? "…" : ""}${l.slice(Math.max(0, at - 120), at + 180)}${at + 180 < l.length ? "…" : ""}` : l;
+                    matches.push({ id: it.id, line: k + 1, text });
+                });
+            }
+            db.publish("context.search", { agent_id: agentId, payload: { query: q.slice(0, 200), by: agentId, hits: matches.length + more } });
+            return {
+                status: 200,
+                body: { matches, ...(more ? { more: `${more} more match(es) — narrow the query` } : {}), note: matches.length ? "Read around a hit: huddle_context_read(id, from_line, to_line)." : "No matches on the shared screen." },
+            };
+        }
+        case "context_note": {
+            const r = store.note(String(body.id ?? ""), String(body.note ?? body.body ?? ""), agentId);
+            return "error" in r ? { status: 404, body: r } : { status: 200, body: { ok: true, note: "Pinned — every agent and the user sees it with the item." } };
+        }
+    }
+    return { status: 404, body: { error: "unknown verb" } };
+}
+/** Base64 file bytes over the wire are capped: a screenshot fits, a 25 MB PDF doesn't. */
+const WIRE_MAX = 8 * 1024 * 1024;
+const INLINE_IMAGE_MAX = 3.5 * 1024 * 1024;
+function readVerb(db, store, body, agentId, remote) {
+    const it = store.get(String(body.id ?? ""));
+    if (!it)
+        return { status: 404, body: { error: `no item ${body.id ?? "(none)"} on the screen — huddle_context lists them` } };
+    const abs = store.pathOf(it);
+    const text = store.textOf(it);
+    if (text === null) {
+        db.publish("context.read", { agent_id: agentId, payload: { id: it.id, title: it.title, kind: it.kind, by: agentId } });
+        let data = null;
+        try {
+            data = fs.readFileSync(abs);
+        }
+        catch {
+            return { status: 410, body: { error: `${it.id}'s file is gone from the screen` } };
+        }
+        const res = { id: it.id, kind: it.kind, title: it.title, size: human(it.bytes), summary: it.summary };
+        if (!remote) {
+            res.path = abs;
+            res.note = `Open this file with your image/file reading tool (e.g. Read ${abs}).${it.kind === "pdf" ? " (Install poppler's pdftotext and Huddle returns the PDF's text here too.)" : ""}`;
+        }
+        else if (data.length <= WIRE_MAX) {
+            // The teammate's Plug saves these bytes on their machine and gives the agent that path.
+            res.file = { name: `${it.id}.${it.file.split(".").pop()}`, mime: it.mime, data_base64: data.toString("base64") };
+        }
+        else
+            res.note = `${it.id} is ${human(it.bytes)} — too big to send across machines; ask the host to paste the part you need`;
+        if (it.kind === "image" && data.length <= INLINE_IMAGE_MAX)
+            res.image = { mime: it.mime, data_base64: data.toString("base64") };
+        return { status: 200, body: res };
+    }
+    const lines = text.split("\n");
+    const total = lines.length;
+    let from = Math.max(1, Math.floor(Number(body.from_line) || 1));
+    let to = Math.floor(Number(body.to_line) || 0);
+    let section;
+    if (body.section !== undefined && body.section !== null && body.section !== "") {
+        const secs = it.sections.length ? it.sections : sectionsOf(text);
+        const n = Number(body.section);
+        section = Number.isInteger(n) && n >= 1 && n <= secs.length ? secs[n - 1] : secs.find((s) => s.title.toLowerCase().includes(String(body.section).toLowerCase()));
+        if (!section)
+            return { status: 404, body: { error: `no section "${body.section}" in ${it.id}`, sections: secs.slice(0, 40).map((s, k) => `${k + 1}. ${s.title}`) } };
+        from = section.from;
+        to = section.to;
+    }
+    if (!to || to < from)
+        to = from + READ_MAX_LINES - 1;
+    to = Math.min(to, total, from + READ_MAX_LINES - 1);
+    if (from > total)
+        return { status: 200, body: { id: it.id, total_lines: total, text: "", note: `${it.id} has only ${total} lines` } };
+    let chars = 0;
+    const out = [];
+    let last = from - 1;
+    for (let k = from; k <= to; k++) {
+        let l = lines[k - 1];
+        if (l.length > LINE_MAX_CHARS)
+            l = l.slice(0, LINE_MAX_CHARS) + ` …[line ${k} goes on for ${l.length - LINE_MAX_CHARS} more chars]`;
+        if (chars + l.length > READ_MAX_CHARS && out.length)
+            break;
+        out.push(l);
+        chars += l.length + 1;
+        last = k;
+    }
+    db.publish("context.read", { agent_id: agentId, payload: { id: it.id, title: it.title, kind: it.kind, by: agentId, from, to: last } });
+    return {
+        status: 200,
+        body: {
+            id: it.id,
+            title: it.title,
+            from_line: from,
+            to_line: last,
+            total_lines: total,
+            ...(section ? { section: section.title } : {}),
+            text: out.join("\n"),
+            ...(last < total ? { more: `lines ${last + 1}-${total} remain: huddle_context_read(id="${it.id}", from_line=${last + 1})` } : {}),
+            ...(it.notes.length ? { notes: it.notes.slice(-5).map((n) => `${n.by}: ${n.body}`) } : {}),
+        },
+    };
+}
+/** Shared door for people (not agents): list, read, add text, note. Members add; guests may look. */
+export function contextShared(db, r, member) {
+    const body = { ...(r.body ?? {}), _shared: true };
+    if (r.method === "GET" && r.path === "/context")
+        return contextVerb(db, "context", body, member.name);
+    if (r.method === "POST" && r.path === "/context/read")
+        return contextVerb(db, "context_read", body, member.name);
+    if (r.method === "POST" && r.path === "/context/search")
+        return contextVerb(db, "context_search", body, member.name);
+    if (r.method === "POST" && r.path === "/context/note")
+        return contextVerb(db, "context_note", body, member.name);
+    if (r.method === "POST" && r.path === "/context/add") {
+        if (member.role === "guest")
+            return { status: 403, body: { error: "guests can look at the screen — not add to it" } };
+        const store = ContextStore.open(db);
+        // Text only over the wire (the body cap is 256 KB); redacted on arrival.
+        const res = store.addText(String(body.text ?? ""), { title: body.title ? String(body.title).slice(0, 60) : undefined, source: "teammate", by: member.name });
+        if (!res.ok)
+            return { status: 400, body: { error: res.reason } };
+        return { status: 200, body: { ok: true, id: res.item.id, duplicate: !!res.duplicate, redacted: res.redacted ?? 0 } };
+    }
+    return { status: 404, body: { error: "not found" } };
+}
+// ---- panels for the live view / story ----------------------------------------
+/** A few lines for the dashboard: items, newest first, and the latest notes. */
+export function screenPanel(db, max = 8) {
+    let items;
+    try {
+        items = ContextStore.open(db).list();
+    }
+    catch {
+        return [];
+    }
+    if (!items.length)
+        return [];
+    const out = [];
+    for (const i of [...items].reverse().slice(0, Math.max(1, max - 3)))
+        out.push(`📎 ${i.id} ${kindWord(i)} “${i.title}” · ${sizeOf(i)}`);
+    if (items.length > max - 3)
+        out.push(`   …and ${items.length - (max - 3)} more`);
+    const notes = items.flatMap((i) => i.notes).sort((a, b) => a.created_at - b.created_at).slice(-3);
+    for (const n of notes)
+        out.push(`📌 ${n.by} on ${n.item_id}: ${n.body}`);
+    return out.slice(0, max);
+}
+// ---- optional brain summary (never blocks the prompt) --------------------------
+/**
+ * One brain call for a long item (> 200 lines): a one-line summary for the
+ * index. Cached by sha in summaries.json; time-boxed; silently skipped on failure.
+ */
+export async function brainSummary(store, item, brain, cwd) {
+    if (!brain || item.lines <= 200)
+        return null;
+    const cacheFile = path.join(store.dir, "summaries.json");
+    let cache = {};
+    try {
+        cache = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+    }
+    catch {
+        /* fresh cache */
+    }
+    if (cache[item.sha256]) {
+        store.setBrainSummary(item.id, cache[item.sha256]);
+        return cache[item.sha256];
+    }
+    const text = store.textOf(item);
+    if (!text)
+        return null;
+    try {
+        const r = await brain.think(`Summarize this ${item.kind} for a team of coding agents in ONE line (max 160 chars): what it is and what matters in it. No preamble.\n\n${text.slice(0, 12_000)}`, cwd, { timeoutMs: 45_000, selfContained: true });
+        const line = r.ok ? r.text.trim().split("\n")[0].slice(0, 160) : "";
+        if (!line)
+            return null;
+        cache[item.sha256] = line;
+        fs.writeFileSync(cacheFile, JSON.stringify(cache));
+        store.setBrainSummary(item.id, line);
+        return line;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=context.js.map