@broject/bro 0.0.0 → 0.2.1

package/dist/dist-CZDdATdS.js

@@ -0,0 +1,1166 @@
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { execFileSync, spawnSync } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import { parse } from "smol-toml";
+
+//#region ../core/dist/index.js
+function gh(args, cwd) {
+	const proc = spawnSync("gh", args, {
+		cwd,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8"
+	});
+	if (proc.status !== 0) throw new Error(`gh ${args[0]} failed: ${(proc.stderr ?? "").trim()}`);
+	return proc.stdout ?? "";
+}
+function ghJson(args, cwd) {
+	return JSON.parse(gh(args, cwd));
+}
+/**
+* `gh` without the throw — for commands whose exit code carries meaning
+* (`gh pr checks` exits 1 when checks fail while still printing JSON).
+*/
+function ghTry(args, cwd) {
+	const proc = spawnSync("gh", args, {
+		cwd,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8"
+	});
+	return {
+		code: proc.status ?? 1,
+		out: proc.stdout ?? "",
+		err: (proc.stderr ?? "").trim()
+	};
+}
+function git(args) {
+	const proc = spawnSync("git", args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8"
+	});
+	if (proc.status !== 0) throw new Error(`git ${args[0]} failed: ${(proc.stderr ?? "").trim()}`);
+	return proc.stdout ?? "";
+}
+function gitTry(args) {
+	const proc = spawnSync("git", args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8"
+	});
+	return {
+		code: proc.status ?? 1,
+		out: proc.stdout ?? "",
+		err: (proc.stderr ?? "").trim()
+	};
+}
+function bd(args, cwd) {
+	return execFileSync("bd", args, {
+		encoding: "utf8",
+		cwd,
+		maxBuffer: 64 * 1024 * 1024,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		timeout: 15e3
+	});
+}
+/** Non-throwing bd — same contract as gitTry for paths where beads is
+*  optional (merge slot, hooks): a missing binary or absent database must
+*  degrade, not stall. */
+function bdTry(args, timeoutMs = 15e3, cwd) {
+	const proc = spawnSync("bd", args, {
+		cwd,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8",
+		timeout: timeoutMs,
+		maxBuffer: 64 * 1024 * 1024
+	});
+	return {
+		code: proc.status ?? 1,
+		out: proc.stdout ?? "",
+		err: (proc.stderr ?? proc.error?.message ?? "").trim()
+	};
+}
+function bdJson(args, cwd) {
+	const out = bd([...args, "--json"], cwd);
+	try {
+		return JSON.parse(out);
+	} catch (err) {
+		throw new Error(`bd returned malformed JSON — ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/** Classify a provenance ref — shared by drill and retro evidence. */
+function refKind(ref) {
+	if (/\/pull\/|\/merge_requests\//.test(ref)) return "pr";
+	if (/^[0-9a-f]{40}$/.test(ref)) return "git-sha";
+	return "work-id";
+}
+/** Provenance event kind for an evidence ref — a work-id is not a commit. */
+function evidenceKind(ref) {
+	switch (refKind(ref)) {
+		case "pr": return "land";
+		case "git-sha": return "commit";
+		default: return "used";
+	}
+}
+/** Only a real `.beads` *directory* counts — a file or dangling path must
+*  not suppress init (it would fail loudly rather than be repaired). */
+function beadsDirExists() {
+	try {
+		return statSync(join(process.cwd(), ".beads")).isDirectory();
+	} catch (err) {
+		const code = err.code;
+		if (code === "ENOENT" || code === "ENOTDIR") return false;
+		throw err;
+	}
+}
+/**
+* Stealth-init `.beads` in the current repo when missing — the single init
+* flags contract shared by debt sync and `bro setup` (local exclude,
+* nothing lands in git). Returns true when it initialized.
+*/
+function initBeadsStealth() {
+	if (beadsDirExists()) return false;
+	try {
+		bd([
+			"init",
+			"--stealth",
+			"--skip-agents",
+			"--skip-hooks",
+			"--quiet"
+		]);
+		return true;
+	} catch (err) {
+		if (beadsDirExists()) return false;
+		throw err;
+	}
+}
+function checkBeads() {
+	try {
+		bd(["--version"]);
+	} catch (err) {
+		if (err.code === "ENOENT") throw new Error("bd not found — install beads first (https://github.com/gastownhall/beads)");
+		throw err;
+	}
+	try {
+		bd([
+			"list",
+			"--json",
+			"-n",
+			"1"
+		]);
+	} catch (err) {
+		const stderr = err.stderr?.trim();
+		throw new Error(`bd list failed — ${stderr || (err instanceof Error ? err.message : String(err))} (run \`bd init\` if beads is not initialized here)`);
+	}
+}
+const STORE_BACKENDS = [
+	"jsonl",
+	"beads",
+	"gitref"
+];
+const PERSONALITIES = [
+	"terse",
+	"mentor",
+	"sarcastic"
+];
+const debtSection = (raw) => ({ dir: typeof raw === "object" && raw !== null && typeof raw.dir === "string" && raw.dir.trim() !== "" ? raw.dir : DEFAULT_CONFIG.debt.dir });
+const syncSection = (raw) => {
+	const obj = typeof raw === "object" && raw !== null ? raw : {};
+	return {
+		...DEFAULT_CONFIG.sync,
+		...Object.fromEntries(Object.entries(obj).filter(([, v]) => typeof v === "string" && v.trim() !== "")),
+		beads: typeof obj.beads === "boolean" ? obj.beads : DEFAULT_CONFIG.sync.beads
+	};
+};
+const actSection = (raw) => {
+	const obj = typeof raw === "object" && raw !== null ? raw : {};
+	return {
+		ignoreChecks: Array.isArray(obj.ignoreChecks) ? obj.ignoreChecks.filter((v) => typeof v === "string" && v.trim() !== "") : [],
+		maxRounds: typeof obj.maxRounds === "number" && Number.isInteger(obj.maxRounds) && obj.maxRounds >= 0 ? obj.maxRounds : DEFAULT_CONFIG.act.maxRounds
+	};
+};
+/** bro.config.json `connectors` section — facade → connector precedence,
+*  e.g. { "reviews": "gitlab", "tasks": "jira" }. Only string→string
+*  entries survive; anything else is dropped. */
+const connectorsSection = (raw) => {
+	const out = {};
+	if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+		for (const [k, v] of Object.entries(raw)) if (k.trim() !== "" && typeof v === "string" && v.trim() !== "") out[k.trim()] = v.trim();
+	}
+	return out;
+};
+/** Default global-beads store — XDG data dir, not a repo path. */
+const DEFAULT_GLOBAL_BEADS_DIR = join(homedir(), ".local", "share", "bro", "beads");
+/** bro.config.json `beads` section — `beads.global` is the global store
+*  dir. BRO_GLOBAL_BEADS wins over the file: a per-machine path should
+*  not need a committed edit. `~` expands against the home dir. */
+const beadsSection = (raw) => {
+	const fromConfig = typeof raw === "object" && raw !== null ? raw.global : void 0;
+	const env = process.env.BRO_GLOBAL_BEADS;
+	const v = (typeof env === "string" && env.trim() !== "" ? env : void 0) ?? (typeof fromConfig === "string" && fromConfig.trim() !== "" ? fromConfig : void 0);
+	if (v === void 0) return { global: DEFAULT_GLOBAL_BEADS_DIR };
+	const p = v.trim();
+	let dir = p;
+	if (p === "~") dir = homedir();
+	else if (p.startsWith("~/")) dir = join(homedir(), p.slice(2));
+	return { global: dir };
+};
+/** bro.config.json `stack` section — how `bro work enter` picks the base
+*  for a new worktree when a session already produced a PR branch.
+*  'manual' (default): stack only on explicit --stack/--base.
+*  'auto': base on the current worktree's branch whenever it isn't the
+*  main checkout's branch — second+ PR in a session lands on the stack
+*  head; gh-stack then drives submit/sync/merge bottom-up. */
+const stackSection = (raw) => {
+	const m = typeof raw === "object" && raw !== null ? raw.mode : void 0;
+	if (m !== void 0 && m !== "auto" && m !== "manual") {
+		console.error(`bro.config: stack.mode must be "auto" or "manual" — got ${JSON.stringify(m)}`);
+		return { mode: "manual" };
+	}
+	return { mode: m ?? "manual" };
+};
+const SDD_MODES = [
+	"off",
+	"remind",
+	"gate"
+];
+/** bro.config.json `sdd` section — spec-driven development policy.
+*  off (default): nothing emitted. remind: session-start/prompt context
+*  names claimed beads without a spec. gate: the stop gate also blocks
+*  once while an own claim lacks a spec. `dir` is where `specs/<id>.md`
+*  lives; a `spec:` link in the bead description counts too. */
+const sddSection = (raw) => {
+	const obj = typeof raw === "object" && raw !== null ? raw : {};
+	if (obj.mode !== void 0 && !SDD_MODES.includes(obj.mode)) console.error(`bro.config: sdd.mode must be one of ${SDD_MODES.map((m) => `"${m}"`).join("|")} — got ${JSON.stringify(obj.mode)}`);
+	return {
+		mode: obj.mode !== void 0 && SDD_MODES.includes(obj.mode) ? obj.mode : DEFAULT_CONFIG.sdd.mode,
+		dir: typeof obj.dir === "string" && obj.dir.trim() !== "" ? obj.dir.trim() : DEFAULT_CONFIG.sdd.dir
+	};
+};
+/** Sections core normalizes itself — identical to what the built-in
+*  plugins declare as their configSchema. */
+const CORE_SECTIONS = {
+	debt: debtSection,
+	sync: syncSection,
+	act: actSection,
+	connectors: connectorsSection,
+	sdd: sddSection
+};
+const DEFAULT_CONFIG = {
+	stores: ["jsonl", "beads"],
+	personality: "terse",
+	debt: { dir: ".agents/review-debt" },
+	sync: {
+		ref: "refs/bro/data",
+		remote: "origin",
+		beads: true
+	},
+	act: {
+		ignoreChecks: [],
+		maxRounds: 3
+	},
+	connectors: {},
+	sdd: {
+		mode: "off",
+		dir: "specs"
+	},
+	plugins: []
+};
+function normalizeStores(raw) {
+	const isBackend = (s) => typeof s === "string" && STORE_BACKENDS.includes(s);
+	if (Array.isArray(raw.stores)) return [...new Set(["jsonl", ...raw.stores.filter(isBackend)])];
+	if (raw.stores !== void 0) {
+		console.error("warning: bro.config.json \"stores\" must be an array — using jsonl-only");
+		return ["jsonl"];
+	}
+	if (raw.store === "beads" || raw.store === "both") return ["jsonl", "beads"];
+	if (raw.store !== void 0) return ["jsonl"];
+	return [...DEFAULT_CONFIG.stores];
+}
+/** Identity helper for bro.config.ts: `export default defineConfig({…})`
+*  gives typed sections when @broject/core is a local dep; a plain object
+*  works without it. Extra keys are plugin sections (see bro-akl). */
+function defineConfig(config) {
+	return config;
+}
+function unwrapDefault(mod) {
+	if (typeof mod !== "object" || mod === null) return mod;
+	const m = mod;
+	return (m[Symbol.toStringTag] === "Module" || Object.keys(m).every((k) => k === "default" || k === "__esModule")) && "default" in m ? m.default : mod;
+}
+function loadTsConfig(name, path) {
+	if (!process.features.typescript) {
+		console.error(`warning: ${name} needs Node >=22.18 (native type stripping) — using jsonl-only stores`);
+		return;
+	}
+	const abs = resolve(path);
+	const req = createRequire(abs);
+	try {
+		return unwrapDefault(req(abs));
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (!/Transform failed|Expected identifier|Cannot use export|ERR_REQUIRE/.test(msg)) throw err;
+		const out = execFileSync(process.execPath, ["--eval", `import(${JSON.stringify(pathToFileURL(abs).href)}).then(m => process.stdout.write(JSON.stringify(m.default ?? null)))`], { encoding: "utf8" });
+		return JSON.parse(out);
+	}
+}
+/** Reads one config file; undefined = failed (caller falls back to
+*  jsonl-only — a broken file must not silently enable beads). */
+function readConfigFile(name, path) {
+	try {
+		if (name.endsWith(".ts")) return loadTsConfig(name, path);
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		let hint = ` (${msg})`;
+		if (/module is not defined|exports is not defined/.test(msg)) hint = " (this repo is ESM — use `export default`, not module.exports)";
+		else if (/Transform failed|Expected identifier/.test(msg)) hint = " (this dir resolves as CommonJS — use `module.exports` or add `\"type\": \"module\"` to package.json)";
+		console.error(`warning: ${name} failed to load — skipping${hint}`);
+		return;
+	}
+}
+/** Runs every section schema over the raw file — a throwing schema warns
+*  and falls back to schema(undefined), never crashes the load. */
+function applySections(config, raw, sections) {
+	for (const [key, schema] of Object.entries({
+		...CORE_SECTIONS,
+		...sections
+	})) try {
+		config[key] = schema(raw[key]);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.error(`warning: bro.config "${key}" invalid (${msg}) — using defaults`);
+		config[key] = schema(void 0);
+	}
+}
+/** The main checkout's root when cwd sits in a linked worktree —
+*  `--git-common-dir` resolves to `<main>/.git` there (and to
+*  `<cwd>/.git` in the main checkout itself, which dedupes). */
+function mainWorktreeRoot(cwd) {
+	const r = gitTry([
+		"-C",
+		cwd,
+		"rev-parse",
+		"--git-common-dir"
+	]);
+	if (r.code !== 0 || r.out.trim() === "") return null;
+	const common = resolve(cwd, r.out.trim());
+	if (basename(common) === ".git") return dirname(common);
+	const parent = dirname(common);
+	let names = [];
+	try {
+		names = readdirSync(parent);
+	} catch {
+		return null;
+	}
+	for (const name of names) {
+		const dir = join(parent, name);
+		const gitfile = join(dir, ".git");
+		try {
+			if (!statSync(gitfile).isFile()) continue;
+			const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(gitfile, "utf8"));
+			if (m && resolve(dir, m[1].trim()) === common) return dir;
+		} catch {}
+	}
+	return null;
+}
+function loadConfig(cwd = process.cwd(), sections = {}) {
+	const fallback = (stores) => {
+		const config = {
+			...DEFAULT_CONFIG,
+			stores
+		};
+		applySections(config, {}, sections);
+		return config;
+	};
+	const dirs = [cwd, mainWorktreeRoot(cwd)].filter((d) => d !== null && d.trim() !== "");
+	let sawBroken = false;
+	for (const dir of new Set(dirs)) {
+		const r = loadDirConfig(dir, sections);
+		if (r === "broken") sawBroken = true;
+		else if (r !== null) return r;
+	}
+	return fallback(sawBroken ? ["jsonl"] : [...DEFAULT_CONFIG.stores]);
+}
+/** Tries bro.config.ts → bro.config.json inside one dir. 'broken' = a
+*  config exists but failed (the dir's remaining names are skipped —
+*  .ts precedence never promotes the sibling .json); null = nothing
+*  here. */
+function loadDirConfig(dir, sections) {
+	for (const name of ["bro.config.ts", "bro.config.json"]) {
+		const path = join(dir, name);
+		if (!existsSync(path)) continue;
+		const raw = readConfigFile(name, path);
+		if (raw === void 0) return "broken";
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+			console.error(`${name}: root must be an object — skipping`);
+			return "broken";
+		}
+		const { stores: _s, store: _legacy, plugins: _p,...rest } = raw;
+		const config = {
+			...DEFAULT_CONFIG,
+			...rest,
+			stores: normalizeStores(raw),
+			plugins: normalizePluginSpecs(dir, raw.plugins)
+		};
+		applySections(config, raw, sections);
+		return config;
+	}
+	return null;
+}
+/** Relative specs anchor at the config's own dir — an inherited config's
+*  `./x.ts` plugin must resolve in the main worktree, not the linked
+*  one. Containment is kept here: a spec escaping its anchor is dropped,
+*  so the absolute path reaching importPluginModule can't bypass its
+*  repo-root guard. */
+function normalizePluginSpecs(dir, plugins) {
+	if (!Array.isArray(plugins)) return [];
+	return plugins.filter((v) => typeof v === "string").map((v) => v.trim()).filter((v) => v !== "").flatMap((v) => {
+		if (!v.startsWith(".")) return [v];
+		const anchor = resolve(dir);
+		const abs = resolve(dir, v);
+		if (abs !== anchor && !abs.startsWith(anchor + sep)) {
+			console.error(`warning: plugin spec "${v}" escapes ${dir} — skipped`);
+			return [];
+		}
+		return [abs];
+	});
+}
+const DATA_REF = "refs/bro/data";
+function g(root, args, input) {
+	return execFileSync("git", [
+		"-C",
+		root,
+		...args
+	], {
+		encoding: "utf8",
+		input,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+}
+/** Untrimmed read — file contents must survive byte-for-byte. */
+function gRaw(root, args) {
+	return execFileSync("git", [
+		"-C",
+		root,
+		...args
+	], {
+		encoding: "utf8",
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+}
+/** Resolve the repo root for cwd, or null outside a worktree. */
+function dataRefRoot(cwd = process.cwd()) {
+	const r = gitTry([
+		"-C",
+		cwd,
+		"rev-parse",
+		"--show-toplevel"
+	]);
+	return r.code === 0 ? r.out.trim() : null;
+}
+function refSha(root, ref) {
+	const r = gitTry([
+		"-C",
+		root,
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		ref
+	]);
+	return r.code === 0 ? r.out.trim() : null;
+}
+/** All git ops share one throwaway index bound to the repo root —
+*  created empty per call so a crashed process can't leave a half-staged
+*  private index behind. */
+function withIndex(root, fn) {
+	const dir = mkdtempSync(join(tmpdir(), "bro-dataref-"));
+	const indexPath = join(dir, "index");
+	const ix = (args, input) => execFileSync("git", [
+		"-C",
+		root,
+		...args
+	], {
+		encoding: "utf8",
+		input,
+		env: {
+			...process.env,
+			GIT_INDEX_FILE: indexPath
+		},
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+	try {
+		return fn(ix);
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** `git ls-tree -rz` → path → {mode, sha}. */
+function treeEntries(root, sha) {
+	const out = g(root, [
+		"ls-tree",
+		"-rz",
+		sha
+	]);
+	const map = /* @__PURE__ */ new Map();
+	for (const rec of out.split("\0")) {
+		if (rec === "") continue;
+		const tab = rec.indexOf("	");
+		const [mode, , sha$1] = rec.slice(0, tab).split(" ");
+		const path = rec.slice(tab + 1);
+		if (tab === -1 || !mode || !sha$1 || !path) throw new Error(`malformed ls-tree record: ${JSON.stringify(rec.slice(0, 60))}`);
+		map.set(path, {
+			mode,
+			sha: sha$1
+		});
+	}
+	return map;
+}
+/** Line-union merge for append-only JSONL — order preserved, dupes dropped. */
+function unionJsonl(a, b) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const line of `${a}\n${b}`.split("\n")) {
+		const t = line.trim();
+		if (t === "" || seen.has(t)) continue;
+		seen.add(t);
+		out.push(t);
+	}
+	return `${out.join("\n")}\n`;
+}
+/** Tree-level merge of two data-ref heads: .jsonl unions by line, every
+*  other conflict resolves to ours — regenerated artifacts (summaries,
+*  indexes) are safe to clobber and the JSONL holds the real history. */
+function mergeDataHeads(root, ref, ours, theirs) {
+	const a = treeEntries(root, ours);
+	const merged = new Map(a);
+	for (const [path, e] of treeEntries(root, theirs)) {
+		const cur = merged.get(path);
+		if (!cur) {
+			merged.set(path, e);
+			continue;
+		}
+		if (cur.sha !== e.sha && path.endsWith(".jsonl")) {
+			const union = unionJsonl(g(root, ["show", `${ours}:${path}`]), g(root, ["show", `${theirs}:${path}`]));
+			merged.set(path, {
+				mode: "100644",
+				sha: g(root, [
+					"hash-object",
+					"-w",
+					"--stdin"
+				], union)
+			});
+		}
+	}
+	g(root, [
+		"update-ref",
+		ref,
+		g(root, [
+			"commit-tree",
+			withIndex(root, (ix) => {
+				ix(["read-tree", "--empty"]);
+				let info = "";
+				for (const [path, e] of merged) info += `${e.mode} ${e.sha}\t${path}\0`;
+				ix([
+					"update-index",
+					"-z",
+					"--index-info"
+				], info);
+				return ix(["write-tree"]);
+			}),
+			"-p",
+			ours,
+			"-p",
+			theirs,
+			"-m",
+			"bro data: merge replicas"
+		]),
+		ours
+	]);
+}
+/**
+* Commit the untracked+ignored files under relDir to the data ref.
+* Returns the ref head (existing sha when the tree didn't change, null
+* when there's nothing to sync).
+*/
+function dataRefCommit(root, relDir, message, ref = DATA_REF) {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const base = refSha(root, ref);
+		const result = withIndex(root, (ix) => {
+			ix(base ? ["read-tree", base] : ["read-tree", "--empty"]);
+			const files = ix([
+				"ls-files",
+				"-o",
+				"-i",
+				"--exclude-standard",
+				"-z",
+				"--",
+				relDir
+			]).split("\0").filter((f) => f !== "");
+			const staged = new Set(ix([
+				"ls-files",
+				"-z",
+				"--",
+				relDir
+			]).split("\0").filter(Boolean));
+			for (const f of files) {
+				ix([
+					"update-index",
+					"--add",
+					"--",
+					f
+				]);
+				staged.delete(f);
+			}
+			for (const gone of staged) ix([
+				"update-index",
+				"--remove",
+				"--",
+				gone
+			]);
+			if (files.length === 0 && staged.size === 0 && base === null) return null;
+			return ix(["write-tree"]);
+		});
+		if (result === null) return null;
+		if (result === (base === null ? null : g(root, ["rev-parse", `${base}^{tree}`]))) return base;
+		const commit = g(root, [
+			"commit-tree",
+			result,
+			...base ? ["-p", base] : [],
+			"-m",
+			message
+		]);
+		if (gitTry([
+			"-C",
+			root,
+			"update-ref",
+			ref,
+			commit,
+			base ?? ""
+		]).code === 0) return commit;
+	}
+	return refSha(root, ref);
+}
+/**
+* Push the data ref with CAS retry. A rejected push means a replica won
+* the race: fetch it, merge trees (JSONL union), retry. Returns false on
+* offline/no-remote after bounded attempts — callers treat sync as
+* best-effort and warn, never fail the command.
+*/
+function dataRefPush(root, remote = "origin", ref = DATA_REF) {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		if (gitTry([
+			"-C",
+			root,
+			"push",
+			remote,
+			`${ref}:${ref}`
+		]).code === 0) return true;
+		if (gitTry([
+			"-C",
+			root,
+			"fetch",
+			remote,
+			ref
+		]).code !== 0) return false;
+		const theirs = g(root, ["rev-parse", "FETCH_HEAD"]);
+		const ours = refSha(root, ref);
+		if (ours === null) return false;
+		if (gitTry([
+			"-C",
+			root,
+			"merge-base",
+			"--is-ancestor",
+			theirs,
+			ours
+		]).code !== 0) mergeDataHeads(root, ref, ours, theirs);
+	}
+	return false;
+}
+/**
+* Pull the remote data ref and write its files under the worktree —
+* restores artifacts on a fresh clone. Local-only files are left alone;
+* the ref is the truth for everything it contains. Returns the number of
+* files written, or -1 when no remote ref exists.
+*/
+function dataRefPull(root, remote = "origin", ref = DATA_REF) {
+	if (gitTry([
+		"-C",
+		root,
+		"fetch",
+		remote,
+		ref
+	]).code !== 0) return -1;
+	const theirs = g(root, ["rev-parse", "FETCH_HEAD"]);
+	const ours = refSha(root, ref);
+	if (ours === null) g(root, [
+		"update-ref",
+		ref,
+		theirs
+	]);
+	else if (gitTry([
+		"-C",
+		root,
+		"merge-base",
+		"--is-ancestor",
+		ours,
+		theirs
+	]).code !== 0) if (gitTry([
+		"-C",
+		root,
+		"merge-base",
+		"--is-ancestor",
+		theirs,
+		ours
+	]).code === 0) {} else mergeDataHeads(root, ref, ours, theirs);
+	else g(root, [
+		"update-ref",
+		ref,
+		theirs
+	]);
+	const tracked = new Set(g(root, ["ls-files", "-z"]).split("\0").filter(Boolean));
+	const realRoot = realpathSync(root);
+	let written = 0;
+	for (const [path] of treeEntries(root, ref)) {
+		const dest = resolve(root, path);
+		if (dest !== root && !dest.startsWith(root + sep)) {
+			console.error(`warning: skipping out-of-root data ref path: ${path}`);
+			continue;
+		}
+		if (tracked.has(path)) {
+			console.error(`warning: skipping tracked path in data ref: ${path}`);
+			continue;
+		}
+		mkdirSync(dirname(dest), { recursive: true });
+		const realParent = realpathSync(dirname(dest));
+		if (realParent !== realRoot && !realParent.startsWith(realRoot + sep)) {
+			console.error(`warning: skipping data ref path through symlinked dir: ${path}`);
+			continue;
+		}
+		writeFileSync(dest, gRaw(root, ["show", `${ref}:${path}`]));
+		written += 1;
+	}
+	return written;
+}
+/** Identity helper — typed declaration sites, same role as defineConfig. */
+function definePlugin(plugin) {
+	return plugin;
+}
+/** Standard verbs map CLI spelling → adapter method. Any other method
+*  name is itself a verb. */
+const STANDARD_VERBS = {
+	list: "list",
+	show: "get",
+	get: "get",
+	new: "create",
+	create: "create",
+	set: "update",
+	update: "update",
+	rm: "remove",
+	remove: "remove"
+};
+/** Verb names an adapter exposes — its function members plus canonical
+*  spellings for the standard methods it implements. */
+function docVerbs(adapter) {
+	const verbs = /* @__PURE__ */ new Set();
+	for (const [verb, method] of Object.entries(STANDARD_VERBS)) if (typeof adapter[method] === "function") verbs.add(verb);
+	for (const k of Object.keys(adapter)) if (!k.startsWith("_") && typeof adapter[k] === "function") verbs.add(k);
+	return [...verbs].sort((a, b) => a.localeCompare(b));
+}
+/** Resolve CLI verb → the adapter method to invoke (standard verbs map
+*  to their method names; anything else is taken literally). */
+function verbMethod(adapter, verb) {
+	const method = adapter[STANDARD_VERBS[verb] ?? verb];
+	return typeof method === "function" ? method : void 0;
+}
+/** A type matches `token` by name or alias. */
+function docTypeNamed(type, token) {
+	return type.name === token || (type.aliases?.includes(token) ?? false);
+}
+function filterArgs(f) {
+	const args = [];
+	if (f.status) args.push("--status", f.status);
+	for (const l of f.labels ?? []) args.push("-l", l);
+	for (const l of f.excludeLabels ?? []) args.push("--exclude-label", l);
+	if (f.all) args.push("--all");
+	if (f.limit !== void 0) args.push("-n", String(f.limit));
+	if (f.type) args.push("--type", f.type);
+	return args;
+}
+function createArgs(i) {
+	const args = [
+		"create",
+		"--title",
+		i.title
+	];
+	if (i.description) args.push("-d", i.description);
+	if (i.type) args.push("-t", i.type);
+	if (i.priority !== void 0) args.push("-p", String(i.priority));
+	for (const l of i.labels ?? []) args.push("-l", l);
+	if (i.deps?.length) args.push("--deps", i.deps.join(","));
+	if (i.parent) args.push("--parent", i.parent);
+	if (i.ephemeral) args.push("--ephemeral");
+	if (i.noInheritLabels) args.push("--no-inherit-labels");
+	if (i.externalRef) args.push("--external-ref", i.externalRef);
+	if (i.metadata) args.push("--metadata", JSON.stringify(i.metadata));
+	return args;
+}
+/** The beads-backed TaskStore. `dir` selects the store via cwd —
+*  callers that need the global store resolve it themselves
+*  (`resolveGlobalDir` lives in the cli layer). */
+function taskStore(dir) {
+	return {
+		list: (f = {}) => bdJson([
+			"list",
+			"--json",
+			...filterArgs(f)
+		], dir),
+		ready: (f = {}) => bdJson(["ready", ...filterArgs(f)], dir),
+		get: (id) => {
+			const r = bdJson(["show", id], dir);
+			return (Array.isArray(r) ? r[0] : r) ?? void 0;
+		},
+		create: (i) => {
+			const r = bdJson(createArgs(i), dir);
+			const row = Array.isArray(r) ? r[0] : r;
+			if (!row) throw new Error("task create returned no row — backend contract broken");
+			return row;
+		},
+		update: (id, patch) => {
+			const args = ["update", id];
+			for (const [k, v] of Object.entries(patch)) args.push(...v === "true" ? [`--${k}`] : [`--${k}`, String(v)]);
+			bd(args, dir);
+		},
+		claim: (id) => {
+			bd([
+				"update",
+				id,
+				"--claim"
+			], dir);
+		},
+		reopen: (id) => {
+			bd(["reopen", id], dir);
+		},
+		close: (id, reason) => {
+			bd([
+				"close",
+				id,
+				...reason ? ["--reason", reason] : []
+			], dir);
+		},
+		remove: (id) => {
+			bd([
+				"delete",
+				id,
+				"--force"
+			], dir);
+		},
+		note: (id, text) => {
+			bd([
+				"note",
+				id,
+				text
+			], dir);
+		},
+		children: (id) => bdJson(["children", id], dir),
+		deps: (ids, opts = {}) => bdJson([
+			"dep",
+			"list",
+			...ids,
+			...opts.type ? ["-t", opts.type] : [],
+			...opts.direction ? [`--direction=${opts.direction}`] : []
+		], dir),
+		link: (from, to, type = "related") => {
+			bd([
+				"link",
+				from,
+				to,
+				"--type",
+				type
+			], dir);
+		},
+		prefix: () => {
+			const probe = bdTry([
+				"config",
+				"get",
+				"issue_prefix"
+			], 15e3, dir);
+			if (probe.code !== 0) throw new Error(`task store unreachable — ${probe.err || "bd error"}`);
+			const line = probe.out.trim().split("\n").pop()?.trim() ?? "";
+			if (line === "" || /not set/i.test(line)) return;
+			const eq = line.indexOf("=");
+			const v = (eq >= 0 ? line.slice(eq + 1) : line).trim().replace(/^['"]|['"]$/g, "");
+			return v === "" ? void 0 : v;
+		}
+	};
+}
+const shortTitle = (t) => {
+	const flat = (t ?? "").replace(/\s+/g, " ").trim();
+	return flat.length > 60 ? `${flat.slice(0, 60)}…` : flat;
+};
+/** Bead ids this session claimed — the `task` aspect marker records one
+*  claim per detail line (line 1 is the timestamp). No session or no
+*  marker → nothing is "mine". Exported for policy connectors (sdd)
+*  that scope their nudges to the session's own claims. */
+function sessionTaskClaims(ctx) {
+	const mine = /* @__PURE__ */ new Set();
+	if (!ctx.sessionId) return mine;
+	try {
+		const gd = gitTry([
+			"-C",
+			ctx.dir,
+			"rev-parse",
+			"--git-common-dir"
+		]);
+		if (gd.code !== 0) return mine;
+		const safe = ctx.sessionId.replace(/[^\w.-]/g, "_");
+		const marker = join(resolve(ctx.dir, gd.out.trim()), "bro", "hooks", `${safe}.task`);
+		for (const d of readFileSync(marker, "utf8").split("\n").slice(1)) {
+			const id = d.trim();
+			if (id) mine.add(id);
+		}
+	} catch {}
+	return mine;
+}
+const registry = [{
+	name: "beads",
+	tasks: (ctx) => taskStore(ctx.dir),
+	hooks: () => ({
+		sessionStart(ctx) {
+			try {
+				const ready = taskStore(ctx.dir).ready().slice(0, 8).map((r) => `  ${r.id} ${shortTitle(r.title)}`.trimEnd());
+				return ready.length > 0 ? [`bd ready:\n${ready.join("\n")}`] : [];
+			} catch {
+				return [];
+			}
+		},
+		parallelWork(ctx) {
+			try {
+				const mine = sessionTaskClaims(ctx);
+				const claimed = taskStore(ctx.dir).list({ status: "in_progress" }).filter((r) => !mine.has(r.id)).slice(0, 5).map((r) => `${r.id} ${shortTitle(r.title)}`.trim());
+				return claimed.length > 0 ? [`claimed beads: ${claimed.join(", ")}`] : [];
+			} catch {
+				return [];
+			}
+		},
+		stopGate(ctx) {
+			try {
+				const claimed = taskStore(ctx.dir).list({ status: "in_progress" });
+				if (claimed.length === 0) return [];
+				const mine = sessionTaskClaims(ctx);
+				const own = claimed.filter((r) => mine.has(r.id));
+				const foreign = claimed.filter((r) => !mine.has(r.id));
+				const fmt = (r) => `${r.id} ${shortTitle(r.title)}`.trim();
+				const out = [];
+				if (own.length > 0) out.push({
+					aspect: "task",
+					block: `bro: claimed beads open: ${own.slice(0, 5).map(fmt).join(", ")} — close (\`bd close <id>\`) or release the claim before stopping`
+				});
+				if (foreign.length > 0) out.push({
+					aspect: "task",
+					passive: `bro: claimed beads open: ${foreign.slice(0, 5).map(fmt).join(", ")}`
+				});
+				return out;
+			} catch {
+				return [];
+			}
+		}
+	})
+}];
+/** Plugin connectors register here (BroPlugin.connectors). Duplicate
+*  names are skipped — a plugin cannot shadow a built-in system. */
+function registerConnector(c) {
+	if (registry.some((x) => x.name === c.name)) {
+		console.error(`warning: connector "${c.name}" already registered — skipped`);
+		return;
+	}
+	registry.push(c);
+}
+function remoteUrl(dir) {
+	const r = gitTry([
+		"-C",
+		dir,
+		"remote",
+		"get-url",
+		"origin"
+	]);
+	return r.code === 0 && r.out.trim() !== "" ? r.out.trim() : void 0;
+}
+/** The connector chosen to serve `kind` — shared by facade() and auth
+*  probing so both resolve through the same precedence. */
+function pickConnector(kind, ctx, opts) {
+	const providers = registry.filter((c) => typeof c[kind] === "function");
+	const named = opts.connector ?? opts.prefer?.[kind];
+	let pick;
+	if (named !== void 0) {
+		pick = providers.find((c) => c.name === named);
+		if (!pick) throw new Error(`connector "${named}" does not provide "${kind}"`);
+	} else {
+		const url = remoteUrl(ctx.dir);
+		const remote = url === void 0 ? void 0 : providers.find((c) => c.matchRemote?.(url));
+		pick = remote ?? providers[0];
+		if (!pick) throw new Error(`no connector provides "${kind}"`);
+		if (remote === void 0 && providers.length > 1) console.error(`warning: ${providers.map((c) => c.name).join(", ")} all provide "${kind}" — using ${pick.name}; set connectors.${kind} in bro.config.json`);
+	}
+	return pick;
+}
+/** Resolve the facade a command needs. Throws when nothing provides it —
+*  callers that probe rather than require should catch or pre-check
+*  `connectors()`. */
+function facade(kind, ctx, opts = {}) {
+	const provides = pickConnector(kind, ctx, opts)[kind];
+	return provides(ctx);
+}
+/** The serving connector's auth probe — null when ready, else the
+*  remediation line. Resolution failures surface as the message: a
+*  missing provider is as unusable as a missing credential. */
+function facadeAuth(kind, ctx, opts = {}) {
+	try {
+		return pickConnector(kind, ctx, opts).auth?.(ctx) ?? null;
+	} catch (err) {
+		return err instanceof Error ? err.message : String(err);
+	}
+}
+/** Hard auth gate for commands — exits(1) with the remediation line when
+*  the resolved connector isn't usable. */
+function ensureAuth(kind, ctx, opts = {}) {
+	const msg = facadeAuth(kind, ctx, opts);
+	if (msg) {
+		console.error(`error: ${msg}`);
+		process.exit(1);
+	}
+}
+/** facade('reviews') bound to a dir — the common resolution path for
+*  review-host commands (act/debt/hooks). */
+function reviewHost(dir = process.cwd(), prefer) {
+	return facade("reviews", { dir }, { prefer });
+}
+/** Every registered connector's hook probes — hooks collect, never pick:
+*  each system reports its own ambient state. */
+function connectorHooks(ctx) {
+	const out = [];
+	for (const c of registry) try {
+		const h = c.hooks?.(ctx);
+		if (h) out.push(h);
+	} catch {}
+	return out;
+}
+/** Per-probe budget — a hung connector (dead network, wedged CLI) must
+*  not stall the whole hook. Racing the probe means the output goes out
+*  on time even if a spawned child lingers. */
+const PROBE_TIMEOUT_MS = 4e3;
+async function probeWithTimeout(p, fallback) {
+	let timer;
+	const timeout = new Promise((resolve$1) => {
+		timer = setTimeout(() => resolve$1(fallback), PROBE_TIMEOUT_MS);
+		timer.unref?.();
+	});
+	try {
+		return await Promise.race([Promise.resolve(p), timeout]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** Collect a line-producing probe across all connectors — fail-open
+*  per connector, one wedged system must not starve the rest. */
+async function collectLines(ctx, probe) {
+	const out = [];
+	for (const h of connectorHooks(ctx)) try {
+		out.push(...await probeWithTimeout(probe(h), void 0) ?? []);
+	} catch {}
+	return out;
+}
+/** Collect session-start context lines from all connectors. */
+function sessionStartLines(ctx) {
+	return collectLines(ctx, (h) => h.sessionStart?.(ctx));
+}
+/** Collect parallel-work signals from all connectors. */
+function parallelWorkLines(ctx) {
+	return collectLines(ctx, (h) => h.parallelWork?.(ctx));
+}
+/** Collect prompt-submit context from all connectors. */
+function promptContextLines(ctx, prompt) {
+	return collectLines(ctx, (h) => h.promptSubmit?.(ctx, prompt));
+}
+/** Collect stop-gate contributions from all connectors — the caller
+*  applies the session-arming policy to each. */
+async function stopGateContributions(ctx) {
+	const out = [];
+	for (const h of connectorHooks(ctx)) try {
+		out.push(...await probeWithTimeout(h.stopGate?.(ctx), void 0) ?? []);
+	} catch {}
+	return out;
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Reads + TOML-parses a plan file. Throws with the file path in the
+*  message — callers never add context of their own. */
+function readPlanDoc(file) {
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`${file}: cannot read plan — ${msg}`);
+	}
+	let doc;
+	try {
+		doc = parse(text);
+	} catch (err) {
+		throw new Error(`${file}: invalid TOML — ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!isRecord(doc)) throw new Error(`${file}: plan must be a TOML table`);
+	return doc;
+}
+/** The envelope's routing key — undefined when absent or non-string. */
+function planKind(doc) {
+	return typeof doc.kind === "string" ? doc.kind : void 0;
+}
+function makePrinter(_personality) {
+	return {
+		info: (msg) => console.error(msg),
+		warn: (msg) => console.error(`warning: ${msg}`),
+		data: (line) => console.log(line)
+	};
+}
+
+//#endregion
+export { parallelWorkLines as A, stackSection as B, ghJson as C, initBeadsStealth as D, gitTry as E, registerConnector as F, syncSection as H, reviewHost as I, sddSection as L, promptContextLines as M, readPlanDoc as N, loadConfig as O, refKind as P, sessionStartLines as R, gh as S, git as T, taskStore as U, stopGateContributions as V, verbMethod as W, docTypeNamed as _, bd as a, evidenceKind as b, beadsSection as c, dataRefPull as d, dataRefPush as f, definePlugin as g, defineConfig as h, actSection as i, planKind as j, makePrinter as k, checkBeads as l, debtSection as m, PERSONALITIES as n, bdJson as o, dataRefRoot as p, STANDARD_VERBS as r, bdTry as s, DEFAULT_GLOBAL_BEADS_DIR as t, dataRefCommit as u, docVerbs as v, ghTry as w, facade as x, ensureAuth as y, sessionTaskClaims as z };