beecork 2.8.0 → 2.8.1

package/dist/index.js

@@ -1195,11 +1195,11 @@ function createMarkdownStream(write) {
 }
 
 // src/tools.ts
-import { readFile as readFile3, writeFile as writeFile2, appendFile, readdir as readdir2, mkdir as mkdir2, stat, rename, chmod } from "node:fs/promises";
+import { readFile as readFile3, writeFile as writeFile2, appendFile, readdir as readdir2, mkdir as mkdir3, stat, rename, chmod } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { createInterface as createLineReader } from "node:readline";
-import { spawn as spawn3 } from "node:child_process";
-import { join as join3 } from "node:path";
+import { spawn as spawn4 } from "node:child_process";
+import { join as join4 } from "node:path";
 import { lookup as dnsLookup } from "node:dns";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
@@ -1678,11 +1678,80 @@ function decodeEntities(s) {
   });
 }
 
+// src/skeleton.ts
+import { spawn as spawn3 } from "node:child_process";
+import { mkdir as mkdir2 } from "node:fs/promises";
+import { join as join3, dirname as dirname3 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { homedir as homedir5 } from "node:os";
+var port = () => Number(process.env.BEECORK_SKELETON_PORT) || 8317;
+var skeletonUrl = () => process.env.BEECORK_DEV_SIGNALS_URL || `http://localhost:${port()}`;
+var managedExternally = () => !!process.env.BEECORK_DEV_SIGNALS_URL;
+var skeletonHome = () => process.env.BEECORK_SKELETON_HOME || join3(homedir5(), ".beecork", "skeleton");
+var bridgeScript = () => join3(dirname3(fileURLToPath3(import.meta.url)), "..", "skeleton", "bridge.mjs");
+async function probe(url = skeletonUrl(), timeoutMs = 600) {
+  try {
+    const res = await fetch(`${url}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (res.ok) {
+      const j = await res.json();
+      if (j && j.skeleton === true) return "up";
+    }
+  } catch {
+    return "down";
+  }
+  try {
+    const res = await fetch(`${url}/signals?limit=1`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (res.ok) {
+      const j = await res.json();
+      if (Array.isArray(j && j.signals)) return "up";
+    }
+  } catch {
+  }
+  return "foreign";
+}
+var inFlight = null;
+function ensureBridge() {
+  if (inFlight) return inFlight;
+  inFlight = doEnsure().finally(() => {
+    inFlight = null;
+  });
+  return inFlight;
+}
+async function doEnsure() {
+  if (managedExternally()) return { up: false, reason: "external" };
+  const first = await probe();
+  if (first === "up") return { up: true };
+  if (first === "foreign") return { up: false, reason: "foreign-port" };
+  let pid;
+  try {
+    const home = skeletonHome();
+    await mkdir2(home, { recursive: true });
+    const child = spawn3(process.execPath, [bridgeScript()], {
+      cwd: home,
+      env: { ...process.env, BEECORK_SKELETON_HOME: home, BEECORK_SKELETON_PORT: String(port()) },
+      detached: true,
+      stdio: "ignore"
+      // fire-and-forget; it logs to no one, which is fine
+    });
+    child.on("error", () => {
+    });
+    pid = child.pid;
+    child.unref();
+  } catch {
+    return { up: false, reason: "spawn-failed" };
+  }
+  for (let i = 0; i < 10; i++) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (await probe() === "up") return { up: true, started: true, pid };
+  }
+  return { up: false, started: true, pid, reason: "spawn-failed" };
+}
+
 // src/tools.ts
 function runShell(command, opts) {
   return new Promise((resolve2, reject) => {
     const unix2 = process.platform !== "win32";
-    const child = spawn3(command, { shell: true, detached: unix2, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn4(command, { shell: true, detached: unix2, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "", stderr = "", outLen = 0, errLen = 0, timedOut = false, aborted = false;
     let settled = false, exitCode = null;
     const kill = () => {
@@ -1964,7 +2033,7 @@ async function walkTree(abs, prefix, items, cap) {
     const e = kept[i];
     const last = i === kept.length - 1;
     items.push({ prefix: prefix + (last ? "\u2514\u2500 " : "\u251C\u2500 "), name: e.name + (e.isDirectory() ? "/" : ""), isDir: e.isDirectory() });
-    if (e.isDirectory()) await walkTree(join3(abs, e.name), prefix + (last ? "   " : "\u2502  "), items, cap);
+    if (e.isDirectory()) await walkTree(join4(abs, e.name), prefix + (last ? "   " : "\u2502  "), items, cap);
   }
 }
 function parseRange(args, defLimit) {
@@ -1994,14 +2063,13 @@ async function readLineWindow(abs, offset1, limit) {
   }
   return { lines, startLine: start + 1, hasMore, empty: i === 0 };
 }
-var DEV_SIGNALS_SETUP = `The browser link isn't connected yet (nothing is responding on localhost:8317).
+var EXTENSION_STEPS = `1. Load the extension: Chrome \u2192 chrome://extensions \u2192 turn on "Developer mode" \u2192 "Load unpacked" \u2192 select the beecork-extension/extension folder, and pin the icon.
+2. Click the icon (it auto-connects \u2014 no token to paste), tick "Capture enabled", open the app in a tab, and click "Pair this site".`;
+var DEV_SIGNALS_SETUP = `The browser link isn't connected yet.
 
-This is "Beecork Skeleton" \u2014 a Chrome extension that sends the app's console errors and failed network requests to me, so I can see what the browser sees instead of guessing. One-time, local-only setup (no account, no signup).
+This is "Beecork Skeleton" \u2014 a Chrome extension that streams the app's console errors and failed network requests to me, so I see what the browser sees instead of guessing. beecork runs the local inbox for you automatically; the only one-time step is loading the extension (local-only, no account):
 
-Walk the user through connecting it:
-1. Start the local inbox: run \`node bridge/server.mjs\` in the beecork-extension folder, and leave it running.
-2. Load the extension: Chrome \u2192 chrome://extensions \u2192 turn on "Developer mode" \u2192 "Load unpacked" \u2192 select the beecork-extension/extension folder. Pin the icon.
-3. Click the icon (it auto-connects), tick "Capture enabled", open the app in a tab, and click "Pair this site".
+` + EXTENSION_STEPS + `
 
 Then call read_dev_signals again. Full step-by-step + troubleshooting is in the "browser-signals" skill.`;
 var toolDefs = [
@@ -2397,9 +2465,9 @@ ${list}`;
     },
     run: async (args) => {
       try {
-        const dir = join3(process.cwd(), ".beecork");
-        await mkdir2(dir, { recursive: true });
-        const file = join3(dir, "memory.md");
+        const dir = join4(process.cwd(), ".beecork");
+        await mkdir3(dir, { recursive: true });
+        const file = join4(dir, "memory.md");
         const fact = String(args.fact).trim();
         if (!fact) return 'Error: remember needs a non-empty "fact".';
         let current = "";
@@ -2523,7 +2591,8 @@ ${skill.content}`;
       required: []
     },
     run: async (args, signal) => {
-      const base = process.env.BEECORK_DEV_SIGNALS_URL || "http://localhost:8317";
+      const ens = await ensureBridge().catch(() => ({ up: false, reason: "spawn-failed" }));
+      const base = skeletonUrl();
       const kind = args.kind ? String(args.kind) : "";
       const limit = Math.min(Math.max(Number(args.limit) || 30, 1), 200);
       const sinceMin = Number(args.since_minutes) || 0;
@@ -2534,15 +2603,21 @@ ${skill.content}`;
       let data;
       try {
         const res = await fetch(`${base}/signals?${params}`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
-        if (!res.ok) return `The browser link responded with HTTP ${res.status}. The bridge may be unhealthy \u2014 try restarting it (node bridge/server.mjs).`;
+        if (!res.ok) return `The browser link responded with HTTP ${res.status}. The inbox may be unhealthy \u2014 I'll try to start a fresh one on the next call.`;
         data = await res.json();
       } catch {
+        if (ens.reason === "foreign-port") return `Another program is using the browser-link inbox port, so I couldn't start it. Free that port (or set BEECORK_DEV_SIGNALS_URL to a different inbox) and try again.`;
         return DEV_SIGNALS_SETUP;
       }
       const now = Date.now();
       const signals = (data.signals ?? []).filter((s) => s && s.kind !== "watch");
       if (signals.length === 0) {
-        return `The browser link is connected, but no ${kind && kind !== "all" ? `"${kind}" ` : ""}signals were captured${sinceMin ? ` in the last ${sinceMin} min` : ""}. The watched tab just hasn't hit the error yet \u2014 reproduce the issue in the browser (or open the app), then call this again.`;
+        return `The inbox is running${ens.started ? " (I just started it)" : ""}, but no ${kind && kind !== "all" ? `"${kind}" ` : ""}signals were captured${sinceMin ? ` in the last ${sinceMin} min` : ""} yet.
+
+If the Beecork Skeleton extension isn't loaded yet, connect it:
+${EXTENSION_STEPS}
+
+Already connected? Reproduce the issue in the browser (or open the app), then call read_dev_signals again.`;
       }
       const ago2 = (ts) => ts ? `${Math.max(0, Math.round((now - ts) / 1e3))}s ago` : "";
       const lines = signals.map((s) => {
@@ -2566,7 +2641,9 @@ ${lines.join("\n")}`;
       required: ["url"]
     },
     run: async (args, signal) => {
-      const base = process.env.BEECORK_DEV_SIGNALS_URL || "http://localhost:8317";
+      await ensureBridge().catch(() => {
+      });
+      const base = skeletonUrl();
       let origin;
       try {
         origin = new URL(String(args.url ?? "")).origin;
@@ -2951,32 +3028,32 @@ ${summary}` }, ...recent];
 }
 
 // src/memory.ts
-import { readFile as readFile4, writeFile as writeFile3, readdir as readdir3, mkdir as mkdir3, chmod as chmod2, rename as rename2, unlink } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
-import { join as join4, dirname as dirname3 } from "node:path";
+import { readFile as readFile4, writeFile as writeFile3, readdir as readdir3, mkdir as mkdir4, chmod as chmod2, rename as rename2, unlink } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join5, dirname as dirname4 } from "node:path";
 var BEECORK = ".beecork";
 function ancestorDirs() {
-  const home = homedir5();
+  const home = homedir6();
   const dirs = [];
   let dir = process.cwd();
-  while (dir !== home && dir !== dirname3(dir)) {
+  while (dir !== home && dir !== dirname4(dir)) {
     dirs.push(dir);
-    dir = dirname3(dir);
+    dir = dirname4(dir);
   }
   return dirs.reverse();
 }
 function corkPaths() {
-  return [join4(homedir5(), BEECORK, "cork.md"), ...ancestorDirs().map((d) => join4(d, "cork.md"))];
+  return [join5(homedir6(), BEECORK, "cork.md"), ...ancestorDirs().map((d) => join5(d, "cork.md"))];
 }
 function beecorkPaths(name) {
-  return [join4(homedir5(), BEECORK, name), ...ancestorDirs().map((d) => join4(d, BEECORK, name))];
+  return [join5(homedir6(), BEECORK, name), ...ancestorDirs().map((d) => join5(d, BEECORK, name))];
 }
 function standardInstructionPaths() {
-  return ancestorDirs().flatMap((d) => [join4(d, "AGENTS.md"), join4(d, "CLAUDE.md")]);
+  return ancestorDirs().flatMap((d) => [join5(d, "AGENTS.md"), join5(d, "CLAUDE.md")]);
 }
 async function loadInstructions() {
-  const home = homedir5();
-  const homeBeecork = join4(home, ".beecork");
+  const home = homedir6();
+  const homeBeecork = join5(home, ".beecork");
   const trusted = [];
   const project = [];
   const sources = [];
@@ -3029,14 +3106,14 @@ async function loadSettings() {
   return { model, reasoningEffort, alwaysAllow, projectAlwaysAllowIgnored };
 }
 function userConfigPath() {
-  return join4(homedir5(), BEECORK, "config.json");
+  return join5(homedir6(), BEECORK, "config.json");
 }
 async function loadUserConfig() {
   return await readJsonFile(userConfigPath()) ?? {};
 }
 async function saveUserConfig(patch) {
   const file = userConfigPath();
-  await mkdir3(dirname3(file), { recursive: true });
+  await mkdir4(dirname4(file), { recursive: true });
   const merged = { ...await loadUserConfig(), ...patch };
   const tmp = `${file}.tmp`;
   await writeFile3(tmp, JSON.stringify(merged, null, 2), { encoding: "utf8", mode: 384 });
@@ -3046,8 +3123,8 @@ async function saveUserConfig(patch) {
 }
 async function saveModelPreference(model) {
   try {
-    const file = join4(homedir5(), BEECORK, "settings.json");
-    await mkdir3(dirname3(file), { recursive: true });
+    const file = join5(homedir6(), BEECORK, "settings.json");
+    await mkdir4(dirname4(file), { recursive: true });
     const current = await readJsonFile(file) ?? {};
     await writeFile3(file, JSON.stringify({ ...current, model }, null, 2), "utf8");
   } catch {
@@ -3055,19 +3132,19 @@ async function saveModelPreference(model) {
 }
 async function saveReasoningPreference(reasoningEffort) {
   try {
-    const file = join4(homedir5(), BEECORK, "settings.json");
-    await mkdir3(dirname3(file), { recursive: true });
+    const file = join5(homedir6(), BEECORK, "settings.json");
+    await mkdir4(dirname4(file), { recursive: true });
     const current = await readJsonFile(file) ?? {};
     await writeFile3(file, JSON.stringify({ ...current, reasoningEffort }, null, 2), "utf8");
   } catch {
   }
 }
-var sessionsDir = () => join4(process.cwd(), BEECORK, "sessions");
+var sessionsDir = () => join5(process.cwd(), BEECORK, "sessions");
 async function saveSession(messages) {
   try {
     const dir = sessionsDir();
-    await mkdir3(dir, { recursive: true });
-    const file = join4(dir, `${Date.now()}.json`);
+    await mkdir4(dir, { recursive: true });
+    const file = join5(dir, `${Date.now()}.json`);
     const tmp = `${file}.tmp`;
     await writeFile3(tmp, JSON.stringify(messages), "utf8");
     await chmod2(tmp, 384).catch(() => {
@@ -3082,7 +3159,7 @@ var MAX_SESSIONS = 50;
 async function pruneSessions(dir) {
   const files = (await readdir3(dir)).filter((f) => f.endsWith(".json"));
   if (files.length <= MAX_SESSIONS) return;
-  for (const f of files.sort().slice(0, files.length - MAX_SESSIONS)) await unlink(join4(dir, f)).catch(() => {
+  for (const f of files.sort().slice(0, files.length - MAX_SESSIONS)) await unlink(join5(dir, f)).catch(() => {
   });
 }
 function sanitizeSession(raw) {
@@ -3121,7 +3198,7 @@ function dropIncompleteToolTail(messages) {
 }
 async function readSession(file) {
   try {
-    const path = join4(sessionsDir(), file);
+    const path = join5(sessionsDir(), file);
     const parsed = sanitizeSession(JSON.parse(await readFile4(path, "utf8")));
     await chmod2(path, 384).catch(() => {
     });
@@ -3162,7 +3239,7 @@ async function loadSession(file) {
   return await readSession(file) ?? [];
 }
 function projectApprovalsPath() {
-  return join4(homedir5(), BEECORK, "project-approvals.json");
+  return join5(homedir6(), BEECORK, "project-approvals.json");
 }
 async function loadProjectApprovals() {
   const all = await readJsonFile(projectApprovalsPath());
@@ -3172,7 +3249,7 @@ async function loadProjectApprovals() {
 async function addProjectApproval(tool) {
   try {
     const file = projectApprovalsPath();
-    await mkdir3(dirname3(file), { recursive: true });
+    await mkdir4(dirname4(file), { recursive: true });
     const all = await readJsonFile(file) ?? {};
     const list = new Set(Array.isArray(all[projectRoot]) ? all[projectRoot] : []);
     list.add(tool);
@@ -3890,7 +3967,7 @@ function stopChrome() {
 var chromeEnabled = () => config.statuslineEnabled && !!process.stdout.isTTY;
 
 // src/commands.ts
-import { writeFile as writeFile4, mkdir as mkdir4, chmod as chmod3 } from "node:fs/promises";
+import { writeFile as writeFile4, mkdir as mkdir5, chmod as chmod3 } from "node:fs/promises";
 async function pick(opts) {
   if (chromeEnabled()) {
     const v = await chromePick(opts.items.map((it) => ({ label: it.label, hint: it.hint, value: it.value })), opts.initial, opts.title);
@@ -4017,7 +4094,7 @@ async function handleCommand(input, messages) {
   } else if (cmd === "/good" || cmd === "/bad") {
     const dir = cmd === "/bad" ? "eval/failures" : "eval/good";
     try {
-      await mkdir4(dir, { recursive: true });
+      await mkdir5(dir, { recursive: true });
       const file = `${dir}/${Date.now()}.json`;
       await writeFile4(file, JSON.stringify({ rating: cmd.slice(1), model: state.model, messages }, null, 2), "utf8");
       await chmod3(file, 384).catch(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beecork",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "beecork — a from-scratch CLI coding agent: multi-model (OpenRouter), BYOK, path-confined tools, built part by part.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "main": "dist/index.js",
   "files": [
     "dist/",
-    "skills/"
+    "skills/",
+    "skeleton/"
   ],
   "engines": {
     "node": ">=20.12"

package/skeleton/bridge.mjs

@@ -0,0 +1,176 @@
+// Beecork Skeleton — local inbox (bridge). SHIPPED WITH beecork and auto-started
+// by it (src/skeleton.ts), so the user never runs this by hand. It can still be run
+// directly (`node skeleton/bridge.mjs`) for development.
+//
+// Receives signals POSTed by the extension, keeps a *bounded* rolling window of the
+// most recent ones, and mirrors that window to dev-signals.jsonl (one JSON object per
+// line). Writes are atomic (temp file + rename) so a reader never sees a half file.
+// No dependencies — Node built-ins only.
+//
+// Lifecycle notes (what makes it safe for beecork to own):
+//   - Single instance: a second copy racing for the port exits(0) quietly on EADDRINUSE
+//     instead of crashing — so parallel beecork sessions share ONE inbox.
+//   - Self-tidying: exits itself after IDLE_MS with no traffic and no reads, so an
+//     auto-started bridge can't linger forever after the extension/browser is gone.
+//   - Fixed home: reads/writes under BEECORK_SKELETON_HOME (beecork points this at
+//     ~/.beecork/skeleton) instead of whatever cwd it was launched from.
+
+import http from "node:http";
+import { writeFile, readFile, rename } from "node:fs/promises";
+import { resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+
+const PORT = Number(process.env.BEECORK_SKELETON_PORT) || 8317;
+const HOME = process.env.BEECORK_SKELETON_HOME || process.cwd();
+const FILE = resolve(HOME, "dev-signals.jsonl");
+const TMP = FILE + ".tmp";
+const TOKEN_FILE = resolve(HOME, ".beecork-token");
+const MAX = 1000; // keep at most this many recent signals
+const IDLE_MS = 60 * 60 * 1000; // self-shutdown after an hour with zero activity
+
+// Pairing token: the extension must present this to write. Blocks any other local
+// process or malicious web page from POSTing fake signals to your agent. Generated
+// once and persisted; the extension fetches it via /pair so the user never sees it.
+let TOKEN;
+try {
+  TOKEN = (await readFile(TOKEN_FILE, "utf8")).trim();
+  if (!TOKEN) throw new Error("empty token file");
+} catch {
+  TOKEN = randomBytes(24).toString("hex");
+  await writeFile(TOKEN_FILE, TOKEN + "\n", { mode: 0o600 });
+}
+
+let buffer = []; // rolling in-memory window of recent signal lines; the file mirrors it.
+const watchRequests = new Map(); // origin beecork asked to watch → expiry (ms)
+let lastActivity = Date.now(); // reset on every request; drives idle self-shutdown
+
+// Load any existing signals so a bridge restart keeps recent context.
+try {
+  const prior = await readFile(FILE, "utf8");
+  buffer = prior.split("\n").filter(Boolean).slice(-MAX);
+} catch {
+  /* no file yet — start empty */
+}
+
+// Persist the bounded window atomically. Writes are serialized through one chain so
+// two concurrent ingests can't clobber the temp file mid-write.
+let chain = Promise.resolve();
+function persist() {
+  chain = chain
+    .then(async () => {
+      await writeFile(TMP, buffer.length ? buffer.join("\n") + "\n" : "");
+      await rename(TMP, FILE);
+    })
+    .catch((e) => console.error("[skeleton] persist failed:", e));
+  return chain;
+}
+
+// A web page's fetch carries an http(s) Origin; refuse those so a page you visit can't
+// read your captured app data or drive your extension. beecork's Node fetch has no web
+// origin and passes. No CORS header is set on these routes on purpose.
+const fromWebPage = (req) => /^https?:\/\//i.test(req.headers.origin || "");
+
+const server = http.createServer((req, res) => {
+  lastActivity = Date.now();
+
+  // Liveness + identity marker: lets beecork tell OUR bridge apart from some other
+  // program that happens to hold the port, so it never spawns a duplicate or talks to
+  // a stranger. Non-sensitive, but web-origin-gated like everything else.
+  if (req.method === "GET" && req.url === "/health") {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    return void res
+      .writeHead(200, { "Content-Type": "application/json" })
+      .end(JSON.stringify({ skeleton: true, port: PORT, signals: buffer.length }));
+  }
+
+  // Auto-pairing: hand the token to the extension so the user never touches it.
+  if (req.method === "GET" && req.url === "/pair") {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    return void res.writeHead(200, { "Content-Type": "text/plain" }).end(TOKEN);
+  }
+
+  // A distilled read for the agent: recent signals, filtered. ?kind=&since=<epoch-ms>&limit=
+  if (req.method === "GET" && req.url.startsWith("/signals")) {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    const q = new URL(req.url, "http://localhost").searchParams;
+    const kind = q.get("kind");
+    const since = Number(q.get("since")) || 0;
+    const limit = Math.min(Math.max(Number(q.get("limit")) || 50, 1), 1000);
+    let items = buffer.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    if (kind && kind !== "all") items = items.filter((s) => s.kind === kind);
+    if (since) items = items.filter((s) => (s.ts || 0) >= since);
+    items = items.slice(-limit);
+    return void res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({ signals: items }));
+  }
+
+  // Reverse channel: beecork asks for a site to be watched. The extension honors it
+  // only for sites the user already approved.
+  if (req.method === "POST" && req.url === "/request-watch") {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      try {
+        const { origin: site, ttlMs } = JSON.parse(body || "{}");
+        if (site) watchRequests.set(String(site), Date.now() + (Number(ttlMs) || 10 * 60 * 1000));
+        res.writeHead(200).end("ok");
+      } catch {
+        res.writeHead(400).end("bad json");
+      }
+    });
+    return;
+  }
+  if (req.method === "GET" && req.url.startsWith("/watch-requests")) {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    const now = Date.now();
+    for (const [site, exp] of watchRequests) if (exp < now) watchRequests.delete(site); // expire
+    return void res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({ origins: [...watchRequests.keys()] }));
+  }
+
+  // Permissive CORS so the extension's service worker can POST to /ingest.
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  if (req.method === "OPTIONS") return void res.writeHead(204).end();
+
+  if (req.method === "POST" && req.url === "/ingest") {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", async () => {
+      try {
+        const signal = JSON.parse(body);
+        if (signal.token !== TOKEN) { res.writeHead(401).end("unauthorized"); return; } // token-gated
+        delete signal.token; // never persist the token itself
+        buffer.push(JSON.stringify(signal));
+        if (buffer.length > MAX) buffer.splice(0, buffer.length - MAX); // bound it
+        await persist();
+        console.log(`[skeleton] ${signal.kind}: ${String(signal.text || "").slice(0, 200)}`);
+        res.writeHead(200).end("ok");
+      } catch {
+        res.writeHead(400).end("bad json");
+      }
+    });
+    return;
+  }
+  res.writeHead(404).end();
+});
+
+// Single-instance: if another bridge already holds the port (a parallel beecork
+// session started it), step aside quietly rather than crash.
+server.on("error", (e) => {
+  if (e && e.code === "EADDRINUSE") process.exit(0);
+  console.error("[skeleton]", e);
+  process.exit(1);
+});
+
+// Self-tidying: an auto-started bridge shouldn't outlive its usefulness. When the
+// extension is loaded it polls every ~30s, so this only fires once the browser side
+// is truly gone AND nothing has read for an hour.
+const idle = setInterval(() => {
+  if (Date.now() - lastActivity > IDLE_MS) { server.close(); process.exit(0); }
+}, 5 * 60 * 1000);
+idle.unref(); // don't let the timer alone keep the process alive
+
+server.listen(PORT, "127.0.0.1", () => {
+  console.log(`[skeleton] inbox listening on http://localhost:${PORT} (home: ${HOME})`);
+});

package/skills/browser-signals.md

@@ -32,16 +32,18 @@ its own). Then have the user reproduce the issue (or open the site) and call
 
 ## If it says "not connected" — one-time setup
 
-The tool returns setup steps when the bridge isn't running. Relay them to the user:
+**beecork starts the local inbox itself** — the first time you call `read_dev_signals` or
+`watch_site`, beecork auto-starts the bundled bridge (a `127.0.0.1:8317` inbox) in the
+background and shares it across sessions. So there is **no bridge to run by hand**; the only
+one-time step is loading the Chrome extension:
 
-1. **Start the local inbox (bridge):** run `node bridge/server.mjs` in the `beecork-extension`
-   folder and leave it running. It listens on `localhost:8317`.
-2. **Load the extension:** Chrome → `chrome://extensions` → enable **Developer mode** →
+1. **Load the extension:** Chrome → `chrome://extensions` → enable **Developer mode** →
    **Load unpacked** → select the `beecork-extension/extension` folder → pin the icon.
-3. **Connect + approve:** click the icon (it auto-connects — no token to paste), tick
+2. **Connect + approve:** click the icon (it auto-connects — no token to paste), tick
    **Capture enabled**, open the app in a tab, and click **Pair this site**.
 
-Then call `read_dev_signals` again.
+Then call `read_dev_signals` again. (If beecork reports the inbox port is held by another
+program, free port 8317 or set `BEECORK_DEV_SIGNALS_URL` to a different inbox.)
 
 ## Empty result