beecork 2.7.2 → 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";
@@ -1296,7 +1296,8 @@ function killAllTasks() {
 
 // src/skills.ts
 import { readdir, readFile as readFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { homedir as homedir3 } from "node:os";
 function parseSkill(raw) {
   let body = raw;
@@ -1331,9 +1332,11 @@ function getSkill(name) {
 }
 async function loadSkills() {
   registry.clear();
+  const bundledDir = join2(dirname2(fileURLToPath2(import.meta.url)), "..", "skills");
   const dirs = [
     [join2(homedir3(), ".beecork", "skills"), "global"],
-    [join2(process.cwd(), ".beecork", "skills"), "project"]
+    [join2(process.cwd(), ".beecork", "skills"), "project"],
+    [bundledDir, "bundled"]
   ];
   for (const [dir, source] of dirs) {
     let entries;
@@ -1346,13 +1349,13 @@ async function loadSkills() {
       if (!e.isFile() || !e.name.endsWith(".md")) continue;
       const name = e.name.slice(0, -3);
       if (!/^[a-z0-9][a-z0-9_-]*$/i.test(name)) continue;
+      if (registry.has(name)) {
+        if (source === "project") console.error(color.yellow(`\u26A0 project skill /${name} ignored \u2014 a global skill of that name takes precedence`));
+        continue;
+      }
       try {
         const raw = (await readFile2(join2(dir, e.name), "utf8")).trim();
         if (!raw) continue;
-        if (source === "project" && registry.has(name)) {
-          console.error(color.yellow(`\u26A0 project skill /${name} ignored \u2014 a global skill of that name takes precedence`));
-          continue;
-        }
         const { description, modelInvocable, body } = parseSkill(raw);
         registry.set(name, { name, content: body, description, modelInvocable, path: join2(dir, e.name), source });
       } catch {
@@ -1675,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 = () => {
@@ -1961,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) {
@@ -1991,6 +2063,15 @@ async function readLineWindow(abs, offset1, limit) {
   }
   return { lines, startLine: start + 1, hasMore, empty: i === 0 };
 }
+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 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):
+
+` + EXTENSION_STEPS + `
+
+Then call read_dev_signals again. Full step-by-step + troubleshooting is in the "browser-signals" skill.`;
 var toolDefs = [
   {
     name: "read_file",
@@ -2384,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 = "";
@@ -2496,6 +2577,94 @@ ${skill.content}`;
       }
       return `No interactive user is available (headless run). Proceed with the most reasonable option for "${question}" and state the assumption you made.`;
     }
+  },
+  {
+    name: "read_dev_signals",
+    description: "Read the browser's recent console errors and failed network requests for the user's app (localhost or production), captured live by the Beecork Skeleton extension \u2014 so you can SEE what's actually happening instead of guessing. Call this whenever the user reports a bug a browser would surface (blank page, broken button, failed save, a 500, a visual glitch). If it isn't connected yet it returns setup steps to relay to the user. Pull on demand; don't spam it.",
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", description: 'Filter: "network", "console", "pageError", "log", or "all" (default all).' },
+        since_minutes: { type: "number", description: "Only signals from the last N minutes (optional)." },
+        limit: { type: "number", description: "Max signals to return (default 30, max 200)." }
+      },
+      required: []
+    },
+    run: async (args, signal) => {
+      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;
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (kind && kind !== "all") params.set("kind", kind);
+      if (sinceMin > 0) params.set("since", String(Date.now() - sinceMin * 6e4));
+      const timeout = AbortSignal.timeout(Math.min(config.webTimeoutMs, 5e3));
+      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 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 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) => {
+        if (s.kind === "network") return `[network] ${s.method || "GET"} ${s.url ?? ""} \u2192 ${s.status || s.text || "failed"}  (${ago2(s.ts)})`;
+        const text = String(s.text ?? "").replace(/\s+/g, " ").slice(0, 300);
+        return `[${s.kind}] ${text}${s.url ? `  @ ${s.url}` : ""}  (${ago2(s.ts)})`;
+      });
+      return `${signals.length} browser signal(s), newest last:
+${lines.join("\n")}`;
+    }
+  },
+  {
+    name: "watch_site",
+    description: "Ask the Beecork Skeleton extension to start watching an APPROVED site's tab right now \u2014 use for an on-demand or production site you need to investigate (localhost/dev sites are watched automatically, so you don't need this for them). Only sites the user already approved are honored. After calling this, reproduce the issue (or open the site), then read_dev_signals.",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The site to watch, e.g. https://app.example.com (its origin is used)." },
+        minutes: { type: "number", description: "How long to keep watching (default 10, max 120)." }
+      },
+      required: ["url"]
+    },
+    run: async (args, signal) => {
+      await ensureBridge().catch(() => {
+      });
+      const base = skeletonUrl();
+      let origin;
+      try {
+        origin = new URL(String(args.url ?? "")).origin;
+      } catch {
+        return `Error: "${args.url}" is not a valid URL.`;
+      }
+      const minutes = Math.min(Math.max(Number(args.minutes) || 10, 1), 120);
+      const timeout = AbortSignal.timeout(Math.min(config.webTimeoutMs, 5e3));
+      try {
+        const res = await fetch(`${base}/request-watch`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ origin, ttlMs: minutes * 6e4 }),
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout
+        });
+        if (!res.ok) return `The browser link responded with HTTP ${res.status}.`;
+      } catch {
+        return DEV_SIGNALS_SETUP;
+      }
+      return `Requested watching ${origin} for ${minutes} min. If the user has approved that site in the extension, it will start capturing shortly \u2014 have them reproduce the issue in a tab on ${origin} (or open it), then call read_dev_signals. If nothing shows up, the site isn't approved yet: ask the user to open it and click "Pair this site" in the Beecork Skeleton popup.`;
+    }
   }
 ];
 var TOOLS = toolDefs.map((t) => ({
@@ -2859,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 dirname2 } 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 !== dirname2(dir)) {
+  while (dir !== home && dir !== dirname4(dir)) {
     dirs.push(dir);
-    dir = dirname2(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 = [];
@@ -2937,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(dirname2(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 });
@@ -2954,8 +3123,8 @@ async function saveUserConfig(patch) {
 }
 async function saveModelPreference(model) {
   try {
-    const file = join4(homedir5(), BEECORK, "settings.json");
-    await mkdir3(dirname2(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 {
@@ -2963,19 +3132,19 @@ async function saveModelPreference(model) {
 }
 async function saveReasoningPreference(reasoningEffort) {
   try {
-    const file = join4(homedir5(), BEECORK, "settings.json");
-    await mkdir3(dirname2(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(() => {
@@ -2990,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) {
@@ -3029,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(() => {
     });
@@ -3070,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());
@@ -3080,7 +3249,7 @@ async function loadProjectApprovals() {
 async function addProjectApproval(tool) {
   try {
     const file = projectApprovalsPath();
-    await mkdir3(dirname2(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);
@@ -3798,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);
@@ -3925,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.7.2",
+  "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": {
@@ -8,7 +8,9 @@
   },
   "main": "dist/index.js",
   "files": [
-    "dist/"
+    "dist/",
+    "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

@@ -0,0 +1,61 @@
+---
+description: Set up / use the browser link so beecork sees the app's console + network errors (read_dev_signals)
+---
+
+# Browser signals — let beecork see the running app
+
+You can read the user's app **console errors** and **failed network requests** straight
+from the browser — on localhost *or* production, in their real logged-in session — with the
+`read_dev_signals` tool. No copy-pasting errors. This is the **Beecork Skeleton** Chrome
+extension plus a tiny local inbox (the "bridge").
+
+## When to use `read_dev_signals`
+
+Call it whenever the user reports something a browser would surface — a blank page, a broken
+button, a form that won't submit, a save that 500s, a visual glitch. Instead of guessing, pull
+the real errors:
+
+- `read_dev_signals({ kind: "network" })` — failed requests (status ≥ 400 / network failures)
+- `read_dev_signals({ since_minutes: 5 })` — everything captured in the last 5 minutes
+- `read_dev_signals({})` — the most recent signals of any kind
+
+Pull it **on demand** while debugging — don't call it in a loop or on every turn.
+
+## Watching an on-demand / production site
+
+Localhost/dev sites the user approved are watched automatically. A **production** (or
+any "on-demand") approved site is idle until asked. To investigate one, call
+`watch_site({ url })` — it asks the extension to watch that site for a while. Only sites
+the user already approved are honored (beecork can't start watching a brand-new site on
+its own). Then have the user reproduce the issue (or open the site) and call
+`read_dev_signals`.
+
+## If it says "not connected" — one-time setup
+
+**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. **Load the extension:** Chrome → `chrome://extensions` → enable **Developer mode** →
+   **Load unpacked** → select the `beecork-extension/extension` folder → pin the icon.
+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. (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
+
+If it connects but returns nothing, the watched tab just hasn't hit the error yet. Either ask
+the user to reproduce it, or open the app yourself to trigger it — e.g.
+`open -a "Google Chrome" http://localhost:3000` (macOS) — then reproduce the action and call
+`read_dev_signals` again.
+
+## How it stays safe
+
+- **Approved sites only** — nothing is watched except sites the user approved in the popup.
+- **Secrets redacted in the browser** — tokens, API keys, passwords, and Authorization values
+  are stripped *before* any signal leaves the tab, so they never reach the inbox.
+- **Local + authenticated** — the inbox is `127.0.0.1` only, and only the extension can write to
+  it (an automatic local token; a web page you visit cannot).