bostrat-node 0.0.1 → 0.2.0

package/LICENSE.md

@@ -0,0 +1,18 @@
+# License
+
+Copyright (c) 2026 Bostrat. All rights reserved.
+
+This package is proprietary software, distributed in bundled form for use with
+the Bostrat service (https://bostrat.ai). You may install and run it to operate
+a Bostrat node connected to a Bostrat coordination plane under your account.
+
+You may not copy, modify, reverse engineer, decompile, redistribute, sublicense,
+or create derivative works from this software, in whole or in part, except as
+permitted by applicable law notwithstanding this restriction.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# bostrat-node
+
+The Bostrat **node** — the runtime that turns a machine you own (laptop, home
+server, or a VM in your own cloud account) into an isolated home for your coding
+agents, coordinated from one chat by your [Bostrat](https://bostrat.ai) plane.
+
+The node **dials out** over WSS; nothing listens publicly. It custodies no model
+credentials — you sign in to your own agent CLIs (Claude Code, Codex, Cursor)
+yourself, inside the boxes it runs, and those logins never leave the machine.
+
+## Quick start
+
+```sh
+npx bostrat-node init      # paste your node token from the Bostrat setup chat
+npx bostrat-node run       # run in the foreground — your plane sees it connect
+```
+
+Keep it running across reboots:
+
+```sh
+npm install -g bostrat-node
+bostrat-node install-service   # systemd --user (Linux) / launchd (macOS)
+```
+
+Other commands: `doctor` (check this machine), `fly` (provision a node in your
+own Fly.io org, on your bill), `--version`.
+
+## Requirements
+
+- Node.js ≥ 22.5, `tmux`, `git`, and at least one agent CLI (`claude`, `codex`,
+  or `cursor-agent`).
+- macOS installs with no build toolchain. Linux compiles one native dependency
+  on install and needs `build-essential` + `python3` (Debian/Ubuntu:
+  `sudo apt-get install build-essential python3`).
+
+Setup walkthrough and node tokens: your plane's setup chat at
+[bostrat.ai](https://bostrat.ai).

package/bin/bostrat-git-credential

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// git credential helper — the broker path (github-node-provisioning-scope.md N2).
+//
+// git invokes this with the action appended after any configured args:
+//   bostrat-git-credential [agent-url] <get|store|erase>
+// On `get` it reads git's key=value description from stdin (host, protocol, and —
+// because managed clones set credential.useHttpPath — the repo path), asks the
+// local agent's loopback for a per-repo broker token, and prints the credential.
+// `store`/`erase` are no-ops: there is nothing to persist — tokens live only in
+// the agent's memory (P1-D1) and expire on their own.
+//
+// Exit 0 with no output on anything unhandled: git then falls through to its
+// remaining helpers/prompting rather than hard-failing the operation.
+
+const args = process.argv.slice(2);
+const action = args[args.length - 1];
+const agentUrl = (args.length > 1 ? args[0] : "") || process.env.BOSTRAT_AGENT_URL || "http://127.0.0.1:3362";
+
+if (action !== "get") process.exit(0);
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (d) => (input += d));
+process.stdin.on("end", async () => {
+  const desc = {};
+  for (const line of input.split("\n")) {
+    const i = line.indexOf("=");
+    if (i > 0) desc[line.slice(0, i)] = line.slice(i + 1).trim();
+  }
+  if (desc.host !== "github.com" || (desc.protocol && desc.protocol !== "https")) process.exit(0);
+  const slug = String(desc.path || "").replace(/^\/+/, "").replace(/\.git$/, "");
+  if (!/^[^/\s]+\/[^/\s]+$/.test(slug)) process.exit(0);
+  try {
+    const r = await fetch(`${agentUrl.replace(/\/+$/, "")}/api/github/token?repo=${encodeURIComponent(slug)}`);
+    if (!r.ok) {
+      const body = await r.json().catch(() => ({}));
+      process.stderr.write(`bostrat-git-credential: ${body?.error || `agent replied ${r.status}`}\n`);
+      process.exit(0);
+    }
+    const { token } = await r.json();
+    if (token) process.stdout.write(`username=x-access-token\npassword=${token}\n`);
+  } catch (e) {
+    process.stderr.write(`bostrat-git-credential: agent unreachable at ${agentUrl} (${e?.message || e})\n`);
+  }
+  process.exit(0);
+});

package/bin/bostrat-mock

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// bostrat-mock — the in-box CLI agents use to publish design comps as IMAGES
+// (mocks scope §6, §12). Talks to the on-box bostrat agent over loopback (same
+// pattern as bostrat-view) and prints the outcome plus a stable `(mock:<id>)`
+// marker. The Track is resolved server-side from this process's cwd (the box
+// always runs inside its Track's workspace), so the CLI needs no configuration.
+//
+//   bostrat-mock add    --name "Homepage — v1" [--group options] [--width 1300] <file.html|file.png>
+//   bostrat-mock update <name|id> <file.html|file.png>     # a new VERSION of the same mock
+//   bostrat-mock ls
+//   bostrat-mock rm <name|id>
+//
+// .html is rendered full-page in the box; .png is published verbatim (the image
+// IS the deliverable). To revise after feedback, always `update` — never add a
+// near-duplicate mock.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+const AGENT = process.env.BOSTRAT_AGENT_URL || `http://127.0.0.1:${process.env.BOSTRAT_AGENT_PORT || 3362}`;
+
+async function call(method, apiPath, body, contentType) {
+  const r = await fetch(`${AGENT}${apiPath}`, {
+    method,
+    headers: body ? { "content-type": contentType || "application/json" } : undefined,
+    body: body ? (contentType ? body : JSON.stringify(body)) : undefined,
+  });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`);
+  return data;
+}
+
+function fail(msg) {
+  console.error(`[bostrat-mock] ${msg}`);
+  process.exit(1);
+}
+
+// Poll until the mock's latest version settles (renders are serialized; an image
+// publish is ready immediately) so the printed state is real.
+async function settle(id) {
+  let m = (await call("GET", `/api/mocks/${id}`)).mock;
+  for (let i = 0; i < 60 && (m.state === "queued" || m.state === "rendering"); i++) {
+    await new Promise((r) => setTimeout(r, 2000));
+    m = (await call("GET", `/api/mocks/${id}`)).mock;
+  }
+  return m;
+}
+
+function report(m, verb) {
+  if (m.state === "error") fail(`render failed:\n${m.error || "(no detail)"}`);
+  if (m.state !== "ready") fail(`render still ${m.state} — check the gallery later (mock:${m.id})`);
+  const v = m.version > 1 ? ` v${m.version}` : "";
+  console.log(`[bostrat-mock] ${verb}: "${m.name}"${v} ${m.width}×${m.height}${m.dpr > 1 ? ` @${m.dpr}x` : ""} (mock:${m.id})`);
+  console.log(`The operator sees it as an image in the Track chat and the gallery — no need to screenshot or link it.`);
+}
+
+// A publishable payload from a file: html → JSON field, png → raw body.
+async function payload(file) {
+  const isPng = path.extname(file).toLowerCase() === ".png";
+  const data = await fsp.readFile(file).catch(() => fail(`cannot read ${file}`));
+  return isPng ? { image: data } : { html: data.toString("utf8") };
+}
+
+const argv = process.argv.slice(2);
+const sub = argv.shift();
+
+if (sub === "add") {
+  let name = null, group, width, file = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--name") name = argv[++i];
+    else if (argv[i] === "--group") group = argv[++i];
+    else if (argv[i] === "--width") width = Number(argv[++i]);
+    else if (!argv[i].startsWith("--")) file = argv[i];
+  }
+  if (!name || !file) fail('usage: bostrat-mock add --name "<name>" [--group <id>] [--width N] <file.html|file.png>');
+  try {
+    const p = await payload(file);
+    const mock = p.image
+      ? (await call("POST", `/api/mocks?${new URLSearchParams({ name, cwd: process.cwd(), ...(group ? { group } : {}) })}`, p.image, "image/png")).mock
+      : (await call("POST", "/api/mocks", { name, html: p.html, group, width, cwd: process.cwd() })).mock;
+    report(await settle(mock.id), "ready");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "update") {
+  const [key, file] = argv.filter((a) => !a.startsWith("--"));
+  if (!key || !file) fail("usage: bostrat-mock update <name|id> <file.html|file.png>");
+  try {
+    const { mocks } = await call("GET", "/api/mocks");
+    const target = mocks.find((x) => x.id === key || x.name === key);
+    if (!target) fail(`no mock matching "${key}" — use \`bostrat-mock ls\`, or \`add\` for a new comp`);
+    const p = await payload(file);
+    const mock = p.image
+      ? (await call("POST", `/api/mocks/${target.id}/update`, p.image, "image/png")).mock
+      : (await call("POST", `/api/mocks/${target.id}/update`, { html: p.html })).mock;
+    report(await settle(mock.id), "updated");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "ls") {
+  const { mocks } = await call("GET", "/api/mocks").catch((e) => fail(e.message));
+  if (!mocks.length) console.log("no mocks");
+  for (const m of mocks) {
+    const dims = m.readyVersion ? ` ${m.width}×${m.height}` : "";
+    const ver = m.version > 1 ? ` v${m.version}` : "";
+    console.log(`${m.state.padEnd(9)} ${m.name}${ver}${m.group ? ` [${m.group}]` : ""}${dims} (mock:${m.id})`);
+  }
+} else if (sub === "rm") {
+  const key = argv[0];
+  if (!key) fail("usage: bostrat-mock rm <name|id>");
+  const { mocks } = await call("GET", "/api/mocks").catch((e) => fail(e.message));
+  const m = mocks.find((x) => x.id === key || x.name === key);
+  if (!m) fail(`no mock matching "${key}"`);
+  await call("DELETE", `/api/mocks/${m.id}`).catch((e) => fail(e.message));
+  console.log(`[bostrat-mock] deleted: ${m.name}`);
+} else {
+  fail('usage: bostrat-mock <add|update|ls|rm> …  (add --name "<name>" <file>; update <name|id> <file>)');
+}

package/bin/bostrat-node.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Thin dual-layout wrapper — everything lives (testably) in ../src/node-cli.js.
+// A repo checkout runs ../src (always fresh, never a stale bundle); the
+// published bostrat-node package ships no src/ and falls through to the
+// minified ../dist bundle (node-package-distribution-scope-2026-07-20.md §2).
+import { existsSync } from "node:fs";
+
+const src = new URL("../src/node-cli.js", import.meta.url);
+const { main } = existsSync(src) ? await import(src.href) : await import(new URL("../dist/cli.js", import.meta.url).href);
+
+const code = await main();
+if (code !== null) process.exit(code);

package/bin/bostrat-runbook

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// bostrat-runbook — the in-box CLI agents use to publish OPERATOR RUNBOOKS: the
+// steps only the operator can perform when a piece of work lands (registrations,
+// secrets, interactive logins, device installs). Talks to the on-box bostrat
+// agent over loopback (same pattern as bostrat-mock) and prints the outcome plus
+// a stable `(runbook:<id>)` marker. The Track is resolved server-side from this
+// process's cwd, so the CLI needs no configuration.
+//
+//   bostrat-runbook add    --name "<deliverable state>" <file.md>
+//   bostrat-runbook update <name|id> [--note "<what changed>"] <file.md>   # a new VERSION of the same runbook
+//   bostrat-runbook done   <name|id>        # every step confirmed by the operator
+//   bostrat-runbook reopen <name|id>        # a step turned out not-done / new steps appeared
+//   bostrat-runbook ls     [--all]          # default: this Track's runbooks; --all: everything
+//   bostrat-runbook rm     <name|id>
+//
+// Runbooks are read-only for the operator — you are the only writer. Never put a
+// secret VALUE in one (name the secret and where it goes; the server rejects
+// token-shaped content). To revise after operator feedback, always `update` —
+// never add a near-duplicate runbook.
+
+import fsp from "node:fs/promises";
+
+const AGENT = process.env.BOSTRAT_AGENT_URL || `http://127.0.0.1:${process.env.BOSTRAT_AGENT_PORT || 3362}`;
+
+async function call(method, apiPath, body) {
+  const r = await fetch(`${AGENT}${apiPath}`, {
+    method,
+    headers: body ? { "content-type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`);
+  return data;
+}
+
+function fail(msg) {
+  console.error(`[bostrat-runbook] ${msg}`);
+  process.exit(1);
+}
+
+async function resolve(key) {
+  const { runbooks } = await call("GET", "/api/runbooks");
+  const rb = runbooks.find((x) => x.id === key || x.name === key);
+  if (!rb) fail(`no runbook matching "${key}" — use \`bostrat-runbook ls\`, or \`add\` for a new one`);
+  return rb;
+}
+
+function report(rb, verb) {
+  const v = rb.version > 1 ? ` v${rb.version}` : "";
+  console.log(`[bostrat-runbook] ${verb}: "${rb.name}"${v} [${rb.status}] (runbook:${rb.id})`);
+  console.log(`The operator sees it as a card in the Track chat and in the Runbooks tab — no need to paste the steps into chat.`);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv.shift();
+
+if (sub === "add") {
+  let name = null, file = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--name") name = argv[++i];
+    else if (!argv[i].startsWith("--")) file = argv[i];
+  }
+  if (!name || !file) fail('usage: bostrat-runbook add --name "<name>" <file.md>');
+  try {
+    const md = await fsp.readFile(file, "utf8").catch(() => fail(`cannot read ${file}`));
+    const { runbook } = await call("POST", "/api/runbooks", { name, md, cwd: process.cwd() });
+    report(runbook, "published");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "update") {
+  let note = null;
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--note") note = argv[++i];
+    else if (!argv[i].startsWith("--")) rest.push(argv[i]);
+  }
+  const [key, file] = rest;
+  if (!key || !file) fail('usage: bostrat-runbook update <name|id> [--note "<what changed>"] <file.md>');
+  try {
+    const target = await resolve(key);
+    const md = await fsp.readFile(file, "utf8").catch(() => fail(`cannot read ${file}`));
+    const { runbook } = await call("POST", `/api/runbooks/${target.id}/update`, { md, ...(note ? { note } : {}) });
+    report(runbook, "updated");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "done" || sub === "reopen") {
+  const key = argv.find((a) => !a.startsWith("--"));
+  if (!key) fail(`usage: bostrat-runbook ${sub} <name|id>`);
+  try {
+    const target = await resolve(key);
+    const { runbook } = await call("POST", `/api/runbooks/${target.id}/status`, { status: sub === "done" ? "done" : "open" });
+    report(runbook, sub === "done" ? "marked done" : "reopened");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "ls") {
+  // Default to THIS Track's runbooks (resolved from cwd); --all shows the fleet,
+  // including orphaned ones from deleted Tracks.
+  const all = argv.includes("--all");
+  try {
+    const query = all ? "" : `?cwd=${encodeURIComponent(process.cwd())}`;
+    const { runbooks } = await call("GET", `/api/runbooks${query}`);
+    if (!runbooks.length) console.log(all ? "no runbooks" : "no runbooks on this Track (try --all)");
+    for (const rb of runbooks) {
+      const ver = rb.version > 1 ? ` v${rb.version}` : "";
+      const orphan = rb.trackDeletedAt ? " [orphaned]" : "";
+      console.log(`${rb.status.padEnd(5)} ${rb.name}${ver}${orphan} (runbook:${rb.id})`);
+    }
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "rm") {
+  const key = argv[0];
+  if (!key) fail("usage: bostrat-runbook rm <name|id>");
+  try {
+    const rb = await resolve(key);
+    await call("DELETE", `/api/runbooks/${rb.id}`);
+    console.log(`[bostrat-runbook] deleted: ${rb.name}`);
+  } catch (e) {
+    fail(e.message);
+  }
+} else {
+  fail('usage: bostrat-runbook <add|update|done|reopen|ls|rm> …  (add --name "<name>" <file.md>; update <name|id> <file.md>)');
+}

package/bin/bostrat-ticket

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// bostrat-ticket — the in-box CLI for linking a Track to its Linear/Jira issue
+// (docs/ticketing-integration-epic.md §4). Talks to the on-box bostrat agent over
+// loopback like its siblings (bostrat-view / bostrat-mock); the Track is resolved
+// server-side from this process's cwd, and the TRACKER TOKEN NEVER ENTERS THE BOX —
+// the agent makes the API calls.
+//
+//   bostrat-ticket link <issue-url-or-KEY-123>
+//   bostrat-ticket status
+//   bostrat-ticket unlink
+//   bostrat-ticket flow                                  # show automation modes
+//   bostrat-ticket flow set <phase>=<mode> [...]         # e.g. flow set prMerged=auto
+//   bostrat-ticket propose [plan.json | -]               # offer to CREATE issues/an epic
+//
+// `flow` is the PREPARED automation config (phases: linked, prOpened, prMerged,
+// create; modes: prompt | auto | off — `create` is prompt|off only, never auto).
+// Only these phases exist — if asked to automate or silence a ticket behavior that
+// is not one of them, say it isn't configurable yet; do not improvise a workaround.
+//
+// `propose` is the outbound-authoring door: hand it a JSON plan (from a file or
+// stdin) and bostrat posts a one-tap review card to the Track chat that CREATES a
+// Linear epic (a Project) and/or issues once the operator confirms. Nothing is
+// created until they tap. Plan shape:
+//   { "epic": {"name":"…","description":"…"},          // omit for standalone issues
+//     "issues": [{"title":"…","description":"…","priority":2}],
+//     "team": "ENG",                                     // optional; else inferred
+//     "linkCurrentTrack": true }                         // link this Track to a lone new issue
+
+const AGENT = process.env.BOSTRAT_AGENT_URL || `http://127.0.0.1:${process.env.BOSTRAT_AGENT_PORT || 3362}`;
+
+async function call(method, apiPath, body) {
+  const r = await fetch(`${AGENT}${apiPath}`, {
+    method,
+    headers: body ? { "content-type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`);
+  return data;
+}
+
+function fail(msg) {
+  console.error(`[bostrat-ticket] ${msg}`);
+  process.exit(1);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv.shift();
+
+if (sub === "link") {
+  const ref = argv[0];
+  if (!ref) fail("usage: bostrat-ticket link <issue-url-or-KEY-123>");
+  try {
+    const { ticket } = await call("POST", "/api/tickets/link", { cwd: process.cwd(), ref });
+    console.log(`[bostrat-ticket] linked ${ticket.key} — ${ticket.title}`);
+    console.log(`${ticket.url}`);
+    console.log("The issue now carries a live Bostrat card; PR opened/merged land as comments.");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "status") {
+  try {
+    const { configured, ticket } = await call("GET", `/api/tickets/status?cwd=${encodeURIComponent(process.cwd())}`);
+    if (!configured) console.log("[bostrat-ticket] no ticketing integration configured (add a linear or jira entry to ~/.bostrat/integrations.json on the host)");
+    if (ticket) console.log(`[bostrat-ticket] linked: ${ticket.key} — ${ticket.title}\n${ticket.url}`);
+    else console.log("[bostrat-ticket] no ticket linked to this Track");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "unlink") {
+  try {
+    const { trackId } = await call("GET", `/api/tickets/status?cwd=${encodeURIComponent(process.cwd())}`);
+    const { removed } = await call("DELETE", `/api/tracks/${trackId}/ticket`);
+    console.log(removed ? "[bostrat-ticket] unlinked" : "[bostrat-ticket] nothing was linked");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "flow") {
+  const showFlow = (flow) => {
+    for (const [phase, mode] of Object.entries(flow)) console.log(`  ${phase.padEnd(9)} ${mode}`);
+  };
+  if (argv[0] === "set") {
+    const set = {};
+    for (const arg of argv.slice(1)) {
+      const m = arg.match(/^([A-Za-z]+)=([A-Za-z]+)$/);
+      if (!m) fail(`bad assignment "${arg}" — usage: bostrat-ticket flow set <phase>=<mode> (phases: linked, prOpened, prMerged, create; modes: prompt, auto, off — create is prompt|off)`);
+      set[m[1]] = m[2];
+    }
+    if (!Object.keys(set).length) fail("usage: bostrat-ticket flow set <phase>=<mode> [...]");
+    try {
+      const { flow } = await call("POST", "/api/tickets/flow", { cwd: process.cwd(), set });
+      console.log("[bostrat-ticket] ticket automation updated:");
+      showFlow(flow);
+      console.log("(prompt = one-tap offer in chat · auto = bostrat moves the issue · off = nothing)");
+    } catch (e) {
+      fail(e.message);
+    }
+  } else if (!argv.length) {
+    try {
+      const { flow } = await call("GET", "/api/tickets/flow");
+      console.log("[bostrat-ticket] ticket automation (phases → modes):");
+      showFlow(flow);
+    } catch (e) {
+      fail(e.message);
+    }
+  } else {
+    fail("usage: bostrat-ticket flow [set <phase>=<mode> ...]");
+  }
+} else if (sub === "propose") {
+  const src = argv[0];
+  const readStdin = async () => {
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    return Buffer.concat(chunks).toString("utf8");
+  };
+  try {
+    const raw = !src || src === "-" ? await readStdin() : await (await import("node:fs/promises")).readFile(src, "utf8");
+    let plan;
+    try {
+      plan = JSON.parse(raw);
+    } catch {
+      fail("plan must be JSON (a file path, or piped on stdin) — see `bostrat-ticket` header for the shape");
+    }
+    const { proposal } = await call("POST", "/api/tickets/propose", { cwd: process.cwd(), plan });
+    const n = proposal.issues?.length ?? 0;
+    const bits = [];
+    if (proposal.epic) bits.push(`epic “${proposal.epic.name}”`);
+    if (n) bits.push(`${n} issue${n === 1 ? "" : "s"}`);
+    console.log(`[bostrat-ticket] proposed ${bits.join(" + ") || "nothing"} — review card posted to the Track chat.`);
+    if (proposal.needsTeam) console.log("  (no team resolved — the card will ask which team to create in)");
+    else if (proposal.team) console.log(`  team: ${proposal.team.key} · nothing is created until you confirm.`);
+  } catch (e) {
+    fail(e.message);
+  }
+} else {
+  fail("usage: bostrat-ticket <link|status|unlink|flow|propose> …  (link <issue-url-or-KEY-123>)");
+}

package/bin/bostrat-view

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// bostrat-view — the in-box CLI agents use to publish a live preview (Views scope
+// §5.1). Talks to the on-box bostrat agent over loopback (same pattern as the
+// claude hook URL) and prints the PUBLIC URL — the link that works off-box —
+// plus a stable `(view:<id>)` marker the chat projection can key on.
+//
+//   bostrat-view up --name "Checkout preview" [--port 4310] -- npm run dev
+//   bostrat-view ls
+//   bostrat-view stop <name|slug|id>
+//   bostrat-view rm <name|slug|id>
+//
+// The Track is resolved server-side from this process's cwd (the box always runs
+// inside its Track's workspace), so the CLI needs no configuration at all. That same
+// cwd is where the serve command runs — in a monorepo, invoke this from the directory
+// holding the app's package.json (e.g. client/), not the workspace root.
+
+const AGENT = process.env.BOSTRAT_AGENT_URL || `http://127.0.0.1:${process.env.BOSTRAT_AGENT_PORT || 3362}`;
+
+async function call(method, apiPath, body) {
+  const r = await fetch(`${AGENT}${apiPath}`, {
+    method,
+    headers: body ? { "content-type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`);
+  return data;
+}
+
+function fail(msg) {
+  console.error(`[bostrat-view] ${msg}`);
+  process.exit(1);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv.shift();
+
+if (sub === "up") {
+  const dashdash = argv.indexOf("--");
+  if (dashdash === -1 || dashdash === argv.length - 1) {
+    fail('usage: bostrat-view up --name "<name>" [--port N] -- <serve command>');
+  }
+  const opts = argv.slice(0, dashdash);
+  const cmd = argv.slice(dashdash + 1).join(" ");
+  let name = null;
+  let port;
+  for (let i = 0; i < opts.length; i++) {
+    if (opts[i] === "--name") name = opts[++i];
+    else if (opts[i] === "--port") port = Number(opts[++i]);
+  }
+  if (!name) fail("--name is required");
+  try {
+    const { view } = await call("POST", "/api/views", { name, cmd, port, cwd: process.cwd() });
+    if (view.reused) {
+      console.log(`[bostrat-view] reusing existing view "${view.name}" — same URL, no new server needed`);
+    }
+    // Poll until live (or error) so the printed URL is real, not a race.
+    let v = view;
+    for (let i = 0; i < 60 && v.state === "starting"; i++) {
+      await new Promise((r) => setTimeout(r, 2000));
+      v = (await call("GET", `/api/views/${view.id}`)).view;
+    }
+    if (v.state === "error") fail(`server failed to start:\n${v.error || "(no output captured)"}`);
+    console.log(`[bostrat-view] ${v.state}: ${v.url} (view:${v.id})`);
+    // Print WHERE it runs: a view serving the wrong directory is otherwise invisible.
+    if (v.serveCwd) console.log(`[bostrat-view] running \`${v.cmd}\` in ${v.serveCwd}`);
+    console.log(`Share this URL — it works from the operator's phone. Do NOT share a localhost URL.`);
+    if (v.state === "starting") console.log("(still starting — the URL shows a holding page until it's up)");
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (sub === "ls") {
+  const { views } = await call("GET", "/api/views").catch((e) => fail(e.message));
+  if (!views.length) console.log("no views");
+  for (const v of views) {
+    console.log(`${v.state.padEnd(9)} ${v.name} — ${v.url} (view:${v.id}, port ${v.port})`);
+    if (v.cmd) console.log(`${" ".repeat(10)}\`${v.cmd}\` in ${v.serveCwd || v.cwd}`);
+  }
+} else if (sub === "stop" || sub === "rm") {
+  const key = argv[0];
+  if (!key) fail(`usage: bostrat-view ${sub} <name|slug|id>`);
+  const { views } = await call("GET", "/api/views").catch((e) => fail(e.message));
+  const v = views.find((x) => x.id === key || x.slug === key || x.name === key);
+  if (!v) fail(`no view matching "${key}"`);
+  if (sub === "stop") {
+    await call("POST", `/api/views/${v.id}/stop`).catch((e) => fail(e.message));
+    console.log(`[bostrat-view] stopped: ${v.name}`);
+  } else {
+    // `stop` keeps the record, and createView's reuse match hits on slug OR exact cmd
+    // regardless of state — so a record with a bad field is sticky until it is removed.
+    await call("DELETE", `/api/views/${v.id}`).catch((e) => fail(e.message));
+    console.log(`[bostrat-view] removed: ${v.name}`);
+  }
+} else {
+  fail('usage: bostrat-view <up|ls|stop|rm> …  (up --name "<name>" -- <serve command>)');
+}

package/bin/gh

@@ -0,0 +1,51 @@
+#!/bin/sh
+# gh shim — broker auth for agent-typed gh (github-node-provisioning-scope.md N4).
+#
+# Sits ahead of the real gh on the box PATH (~/.local/bin symlink, ensureViewCli).
+# For the PR-surface command families (pr / run / api / issue / search) it asks
+# the local agent loopback for a per-repo broker token derived from the cwd's
+# origin remote and execs the REAL gh with GH_TOKEN set for THIS invocation only
+# — in-memory, per-exec, nothing on disk (P1-D1). Everything else, an already-set
+# token env, an uncovered repo, or an unreachable agent runs gh unchanged (the
+# keyring fallback, until phase R). Actions under the broker are actored by the
+# App bot (P1-D8) — prs.js adds the on-behalf-of breadcrumbs.
+
+self="$(readlink -f "$0" 2>/dev/null || echo "$0")"
+real=""
+OLDIFS="$IFS"
+IFS=:
+for d in $PATH; do
+  c="${d:-.}/gh"
+  [ -x "$c" ] || continue
+  [ "$(readlink -f "$c" 2>/dev/null || echo "$c")" = "$self" ] && continue
+  real="$c"
+  break
+done
+IFS="$OLDIFS"
+if [ -z "$real" ]; then
+  echo "gh: real gh binary not found behind the bostrat shim" >&2
+  exit 127
+fi
+
+case "$1" in
+  pr|run|api|issue|search) ;;
+  *) exec "$real" "$@" ;;
+esac
+if [ -n "$GH_TOKEN" ] || [ -n "$GITHUB_TOKEN" ]; then
+  exec "$real" "$@"
+fi
+
+origin="$(git config --get remote.origin.url 2>/dev/null)"
+slug="$(printf '%s' "$origin" | sed -nE 's#.*github\.com[:/]+##p' | sed -E 's#\.git$##; s#/+$##')"
+case "$slug" in
+  */*) ;;
+  *) exec "$real" "$@" ;;
+esac
+
+agent_url="${BOSTRAT_AGENT_URL:-http://127.0.0.1:3362}"
+token="$(curl -fsS --max-time 10 "$agent_url/api/github/token?repo=$slug" 2>/dev/null \
+  | sed -nE 's/.*"token":"([^"]+)".*/\1/p')"
+if [ -n "$token" ]; then
+  GH_TOKEN="$token" exec "$real" "$@"
+fi
+exec "$real" "$@"