balladeer 1.0.6 → 1.0.7

package/dist/guidance-install.d.ts

@@ -0,0 +1,29 @@
+type Host = "codex" | "claude";
+export type GuidanceInstallResult = Readonly<{
+    status: "installed_needs_host_trust" | "installed_trust_unverified" | "unavailable" | "not_applicable";
+    reason?: string;
+    changed: boolean;
+    hosts: readonly Host[];
+}>;
+export declare function guidanceHookCommand(host: Host, repositoryId: string, controlPlane: string): string;
+/** Migrate only the current checkout's already-bound integration. No disk search or pairing. */
+export declare function installGuidanceLoader(options: {
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    repositoryId: string;
+    controlPlane: string;
+    /** Explicit setup targets one host; automatic MCP startup may inspect both. */
+    host?: Host;
+    /** Deterministic race injection for acceptance, never used by CLI. */
+    beforeCommit?: () => void;
+    /** Deterministic interrupted-rename acceptance injection, never used by CLI. */
+    beforeRename?: (index: number) => void;
+}): GuidanceInstallResult;
+/** A project hook is inert outside the exact repository integration which installed it. */
+export declare function validateProjectGuidanceScope(options: {
+    cwd: string;
+    hook: Host;
+    repositoryId: string;
+    controlPlane: string;
+}): boolean;
+export {};

package/dist/guidance-install.js

@@ -0,0 +1,420 @@
+import { DEFAULT_CONTROL_PLANE } from "./wire.js";
+import { guidanceRuntimeCommand, installGuidanceRuntime } from "./guidance-runtime.js";
+import { createHash, randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { constants, closeSync, fstatSync, openSync, existsSync, lstatSync, linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { parse } from "@iarna/toml";
+import { readCodexEntry, hasManagedCodexEntry } from "./codex-config.js";
+import { CONVENTIONS_END, CONVENTIONS_START, CONVENTIONS_VERSION, managedByLine, } from "./conventions.js";
+import { CONVENTIONS_BLOCK } from "./copy.js";
+import { currentEntry, entryRepositoryId, isOurEntry, readMcpConfig } from "./mcp-config.js";
+const KNOWN_POLICIES = new Set([
+    "9c3a271aaeadb2c6543faa23c2a870212fecaaa56dc1dfd2fccf112b5041900d",
+    "a8527de805c81003ff5f9f6abaf7a2852911384393cc444fcd50e36bf911289d",
+    "3c40ead350a3dc57f0d9f8317fbca273f0c27cd38754cdae47d96f86455a14e2",
+]);
+const HOOK_START = "# balladeer:guidance:start";
+const HOOK_END = "# balladeer:guidance:end";
+const EVENTS = ["SessionStart", "UserPromptSubmit", "SubagentStart"];
+const OWNER = "Balladeer current guidance (loader 1)";
+const MAX_FILE = 262144;
+function hash(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function lockOwner(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let owner;
+    let stat;
+    try {
+        stat = fstatSync(fd);
+        if (!stat.isFile() ||
+            stat.size > 1024 ||
+            (typeof process.getuid === "function" && stat.uid !== process.getuid()))
+            throw new Error("lock_owner_unverifiable");
+        owner = JSON.parse(readFileSync(fd, "utf8"));
+    }
+    catch {
+        throw new Error("lock_owner_unverifiable");
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (owner.schemaVersion !== 1 ||
+        !Number.isSafeInteger(owner.pid) ||
+        owner.pid <= 0 ||
+        owner.host !== hostname() ||
+        !/^[a-f0-9]{32}$/.test(owner.nonce))
+        throw new Error("lock_owner_unverifiable");
+    return { owner, identity: `${stat.dev}:${stat.ino}:${owner.nonce}` };
+}
+function ownerIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        // EPERM and unknown process errors never authorize stealing a lock.
+        return true;
+    }
+}
+/** Initialized metadata is linked atomically: process death cannot leave an empty owned lock. */
+function acquireMigrationLock(path) {
+    const nonce = randomBytes(16).toString("hex");
+    const temporary = `${path}.${nonce}.tmp`;
+    const owner = { schemaVersion: 1, pid: process.pid, host: hostname(), nonce };
+    let recovery;
+    let ownsRecovery = false;
+    let identity;
+    writeFileSync(temporary, JSON.stringify(owner), { flag: "wx", mode: 0o600 });
+    try {
+        try {
+            linkSync(temporary, path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const stale = lockOwner(path);
+            if (ownerIsAlive(stale.owner.pid))
+                throw new Error("migration_in_progress");
+            // One reaper per immutable old identity. A second reaper cannot unlink a
+            // replacement live lock. An interrupted reaper remains explicitly blocked.
+            recovery = `${path}.recovery-${stale.owner.nonce}`;
+            try {
+                linkSync(temporary, recovery);
+                ownsRecovery = true;
+            }
+            catch (claimError) {
+                if (claimError.code === "EEXIST")
+                    throw new Error("lock_recovery_unavailable");
+                throw claimError;
+            }
+            if (lockOwner(path).identity !== stale.identity || ownerIsAlive(stale.owner.pid))
+                throw new Error("migration_in_progress");
+            unlinkSync(path);
+            // A competing normal acquirer may win here; never remove its lock.
+            try {
+                linkSync(temporary, path);
+            }
+            catch (claimError) {
+                if (claimError.code === "EEXIST")
+                    throw new Error("migration_in_progress");
+                throw claimError;
+            }
+        }
+        identity = lockOwner(path).identity;
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* Already absent. */
+        }
+        if (ownsRecovery && recovery) {
+            try {
+                unlinkSync(recovery);
+            }
+            catch {
+                /* Interrupted recovery stays conservative. */
+            }
+        }
+    }
+    return () => {
+        try {
+            if (lockOwner(path).identity === identity)
+                unlinkSync(path);
+        }
+        catch {
+            /* Never remove an unverified replacement lock. */
+        }
+    };
+}
+function readRegular(path, allowMissing = false, writable = true) {
+    if (!existsSync(path)) {
+        try {
+            lstatSync(path);
+        }
+        catch (e) {
+            if (e.code === "ENOENT" && allowMissing)
+                return undefined;
+        }
+        throw new Error("file_unavailable");
+    }
+    const stat = lstatSync(path);
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        stat.size > MAX_FILE ||
+        (writable && (stat.mode & 0o222) === 0))
+        throw new Error("file_not_safely_writable");
+    return readFileSync(path, "utf8");
+}
+function safeParent(root, path) {
+    let at = dirname(path);
+    while (at !== root) {
+        if (relative(root, at).startsWith(".."))
+            throw new Error("outside_repository");
+        try {
+            const stat = lstatSync(at);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error("unsafe_directory");
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        at = dirname(at);
+    }
+}
+function policyEdit(path) {
+    const before = readRegular(path);
+    const starts = [...before.matchAll(/<!-- balladeer:conventions:start(?: v\d{1,4})? -->/g)];
+    const ends = [...before.matchAll(/<!-- balladeer:conventions:end -->/g)];
+    if (starts.length !== 1 || ends.length !== 1 || starts[0].index >= ends[0].index)
+        throw new Error("managed_block_ambiguous");
+    const start = starts[0], end = ends[0];
+    const interior = before.slice(start.index + start[0].length, end.index).trim();
+    const body = interior
+        .replace(/^Managed by Balladeer \(conventions v\d+\)\.[^\n]*\n\s*/, "")
+        .trim();
+    if (body !== CONVENTIONS_BLOCK.trim() && !KNOWN_POLICIES.has(hash(body)))
+        throw new Error("managed_block_customized_or_unknown");
+    const after = before.slice(0, start.index) +
+        `${CONVENTIONS_START}\n${managedByLine(CONVENTIONS_VERSION)}\n\n${CONVENTIONS_BLOCK.trim()}\n${CONVENTIONS_END}` +
+        before.slice(end.index + end[0].length);
+    return { path, before, after, mode: lstatSync(path).mode & 0o777 };
+}
+export function guidanceHookCommand(host, repositoryId, controlPlane) {
+    return guidanceRuntimeCommand(host, repositoryId, controlPlane);
+}
+function hookEdit(root, host, repositoryId, controlPlane) {
+    const command = guidanceHookCommand(host, repositoryId, controlPlane);
+    const path = join(root, host === "codex" ? ".codex/config.toml" : ".claude/settings.json");
+    safeParent(root, path);
+    const before = readRegular(path, true);
+    let after;
+    if (host === "codex") {
+        const base = before ?? "";
+        const starts = [...base.matchAll(/^# balladeer:guidance:start$/gm)], ends = [...base.matchAll(/^# balladeer:guidance:end$/gm)];
+        if (starts.length !== ends.length ||
+            starts.length > 1 ||
+            (starts[0] && starts[0].index >= ends[0].index))
+            throw new Error("hook_block_ambiguous");
+        const block = [
+            HOOK_START,
+            ...EVENTS.flatMap((event) => [
+                `[[hooks.${event}]]`,
+                `[[hooks.${event}.hooks]]`,
+                'type = "command"',
+                `command = ${JSON.stringify(`${command} --event ${event}`)}`,
+                "timeout = 3",
+                "additionalContextLimit = 2200",
+            ]),
+            HOOK_END,
+        ].join("\n");
+        if (starts[0]) {
+            const old = base.slice(starts[0].index, ends[0].index + HOOK_END.length);
+            if (old !== block)
+                throw new Error("hook_block_customized_or_unknown");
+            after = base;
+        }
+        else
+            after = base + (base.endsWith("\n") || base === "" ? "" : "\n") + block + "\n";
+        parse(after);
+    }
+    else {
+        const obj = before === undefined ? {} : JSON.parse(before);
+        if (!obj || typeof obj !== "object" || Array.isArray(obj))
+            throw new Error("invalid_hook_config");
+        const hooks = obj.hooks === undefined ? {} : obj.hooks;
+        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+            throw new Error("invalid_hooks");
+        for (const event of EVENTS) {
+            const rows = hooks[event] === undefined ? [] : hooks[event];
+            if (!Array.isArray(rows))
+                throw new Error("invalid_hook_event");
+            const own = rows.filter((row) => row?.hooks?.some((h) => h.statusMessage === OWNER));
+            const expected = {
+                hooks: [
+                    {
+                        type: "command",
+                        command: `${command} --event ${event}`,
+                        timeout: 3,
+                        statusMessage: OWNER,
+                    },
+                ],
+            };
+            if (own.length > 1 ||
+                (own.length === 1 && JSON.stringify(own[0]) !== JSON.stringify(expected)))
+                throw new Error("hook_customized_or_unknown");
+            hooks[event] = own.length === 1 ? rows : [...rows, expected];
+        }
+        obj.hooks = hooks;
+        // If semantically unchanged, preserve formatting as well as settings.
+        after =
+            before !== undefined && JSON.stringify(JSON.parse(before)) === JSON.stringify(obj)
+                ? before
+                : JSON.stringify(obj, null, 2) + "\n";
+    }
+    return { path, before, after, mode: before === undefined ? 0o600 : lstatSync(path).mode & 0o777 };
+}
+/** Migrate only the current checkout's already-bound integration. No disk search or pairing. */
+export function installGuidanceLoader(options) {
+    let root;
+    try {
+        root = execFileSync("git", ["-C", options.cwd, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 1000,
+        }).trim();
+    }
+    catch {
+        return { status: "not_applicable", reason: "no_repository_root", changed: false, hosts: [] };
+    }
+    const lock = join(root, ".balladeer-guidance-migration.lock");
+    let releaseLock;
+    const hosts = [];
+    let changed = false;
+    const staged = [];
+    try {
+        releaseLock = acquireMigrationLock(lock);
+        for (const host of ["codex", "claude"]) {
+            if (options.host !== undefined && host !== options.host)
+                continue;
+            const config = join(root, host === "codex" ? ".codex/config.toml" : ".mcp.json");
+            safeParent(root, config);
+            if (!existsSync(config))
+                continue;
+            readRegular(config);
+            const entry = host === "codex" ? readCodexEntry(root) : currentEntry(readMcpConfig(root));
+            if (!isOurEntry(entry, options.controlPlane))
+                continue;
+            if (host === "codex" && !hasManagedCodexEntry(root, options.controlPlane))
+                throw new Error("codex_entry_unmanaged");
+            if (entryRepositoryId(entry) !== options.repositoryId)
+                throw new Error("repository_mapping_conflict");
+            const args = entry.args, at = args.indexOf("--control-plane");
+            if (at !== -1 && args[at + 1] !== options.controlPlane)
+                throw new Error("control_plane_mapping_conflict");
+            if (at === -1 && options.controlPlane !== DEFAULT_CONTROL_PLANE)
+                throw new Error("control_plane_mapping_conflict");
+            hosts.push(host);
+        }
+        if (hosts.length === 0)
+            return { status: "not_applicable", reason: "no_bound_managed_entry", changed: false, hosts };
+        const paths = new Set();
+        for (const host of hosts)
+            paths.add(join(root, host === "codex"
+                ? "AGENTS.md"
+                : existsSync(join(root, "CLAUDE.md"))
+                    ? "CLAUDE.md"
+                    : "AGENTS.md"));
+        // A second owned block is also loaded by some hosts; never leave conflicting policy behind.
+        for (const name of options.host === undefined ? ["AGENTS.md", "CLAUDE.md"] : []) {
+            const path = join(root, name);
+            if (existsSync(path) && readRegular(path).includes("balladeer:conventions:start"))
+                paths.add(path);
+        }
+        const edits = [...paths]
+            .map(policyEdit)
+            .concat(hosts.map((host) => hookEdit(root, host, options.repositoryId, options.controlPlane)));
+        const conflicts = execFileSync("git", ["-C", root, "ls-files", "--unmerged", "--", ...edits.map((e) => relative(root, e.path))], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 1000 });
+        if (conflicts.trim())
+            throw new Error("unresolved_merge");
+        for (const edit of edits.filter((e) => e.before !== e.after)) {
+            safeParent(root, edit.path);
+            mkdirSync(dirname(edit.path), { recursive: true });
+            const temporary = join(dirname(edit.path), `.balladeer-guidance-${randomBytes(8).toString("hex")}.tmp`);
+            writeFileSync(temporary, edit.after, { flag: "wx", mode: edit.mode });
+            staged.push({ edit, temporary });
+        }
+        options.beforeCommit?.();
+        for (const { edit } of staged) {
+            safeParent(root, edit.path);
+            if (readRegular(edit.path, true) !== edit.before)
+                throw new Error("concurrent_file_change");
+        }
+        for (const host of hosts) {
+            const config = join(root, host === "codex" ? ".codex/config.toml" : ".mcp.json");
+            const finalConfiguration = edits.find((edit) => edit.path === config)?.after ?? readRegular(config);
+            installGuidanceRuntime({
+                root,
+                host,
+                repositoryId: options.repositoryId,
+                controlPlane: options.controlPlane,
+                environment: options.environment,
+                configurationDigest: createHash("sha256").update(finalConfiguration).digest("hex"),
+            });
+        }
+        for (const [index, { edit, temporary }] of staged.entries()) {
+            options.beforeRename?.(index);
+            // Recheck immediately before each rename as well as before the batch.
+            safeParent(root, edit.path);
+            if (readRegular(edit.path, true) !== edit.before)
+                throw new Error("concurrent_file_change");
+            renameSync(temporary, edit.path);
+            changed = true;
+        }
+        return {
+            status: changed ? "installed_needs_host_trust" : "installed_trust_unverified",
+            changed,
+            hosts,
+        };
+    }
+    catch (e) {
+        const reason = e.code === "EEXIST"
+            ? "migration_in_progress"
+            : e instanceof Error && /^[a-z_]+$/.test(e.message)
+                ? e.message
+                : "migration_unavailable";
+        return {
+            status: "unavailable",
+            reason: changed ? "partial_migration_retry" : reason,
+            changed,
+            hosts,
+        };
+    }
+    finally {
+        for (const { temporary } of staged) {
+            try {
+                unlinkSync(temporary);
+            }
+            catch {
+                /* Renamed or already absent. */
+            }
+        }
+        releaseLock?.();
+    }
+}
+/** A project hook is inert outside the exact repository integration which installed it. */
+export function validateProjectGuidanceScope(options) {
+    try {
+        const root = execFileSync("git", ["-C", options.cwd, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 1000,
+        }).trim();
+        const path = join(root, options.hook === "codex" ? ".codex/config.toml" : ".mcp.json");
+        safeParent(root, path);
+        readRegular(path, false, false);
+        const entry = options.hook === "codex" ? readCodexEntry(root) : currentEntry(readMcpConfig(root));
+        if (!isOurEntry(entry, options.controlPlane) ||
+            entryRepositoryId(entry) !== options.repositoryId)
+            return false;
+        if (options.hook === "codex" && !hasManagedCodexEntry(root, options.controlPlane))
+            return false;
+        const args = entry.args;
+        if (!Array.isArray(args))
+            return false;
+        const at = args.indexOf("--control-plane");
+        return at === -1
+            ? options.controlPlane === DEFAULT_CONTROL_PLANE
+            : args[at + 1] === options.controlPlane;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/guidance-runtime-entry.d.ts

@@ -0,0 +1 @@
+export { runGuidance } from "./commands/guidance.js";

package/dist/guidance-runtime-entry.js

@@ -0,0 +1,2 @@
+// The published standalone hook has no npm/runtime-package dependency.
+export { runGuidance } from "./commands/guidance.js";

package/dist/guidance-runtime.d.ts

@@ -0,0 +1,15 @@
+type Scope = {
+    root: string;
+    host: "codex" | "claude";
+    repositoryId: string;
+    controlPlane: string;
+};
+export declare function guidanceRuntimeKey(scope: Scope): string;
+export declare function installGuidanceRuntime(options: Scope & {
+    environment: NodeJS.ProcessEnv;
+    /** Digest of the final, already-validated project MCP configuration. */
+    configurationDigest: string;
+}): void;
+/** Stable, dependency-free wrapper. Current policy exists only in the authenticated server response. */
+export declare function guidanceRuntimeCommand(host: "codex" | "claude", repositoryId: string, controlPlane: string): string;
+export {};

package/dist/guidance-runtime.js

@@ -0,0 +1,149 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureStoreDirectory } from "./store.js";
+import { GUIDANCE_UNAVAILABLE } from "./guidance.js";
+const OWNER = "balladeer-guidance-runtime/1";
+const HEX = /^[a-f0-9]{64}$/;
+const MAX_RUNTIME = 1_048_576;
+const sha = (value) => createHash("sha256").update(value).digest("hex");
+const quote = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+export function guidanceRuntimeKey(scope) {
+    return sha(JSON.stringify([
+        realpathSync(scope.root),
+        new URL(scope.controlPlane).origin,
+        scope.repositoryId,
+        scope.host,
+    ]));
+}
+function privateDirectory(path) {
+    mkdirSync(path, { mode: 0o700, recursive: false });
+}
+function checkDirectory(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0)
+        throw new Error("guidance_runtime_directory_unsafe");
+}
+function readPrivate(path, max) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > max || (stat.mode & 0o077) !== 0)
+            throw new Error("guidance_runtime_file_unsafe");
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function atomic(path, body) {
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temporary, body, { mode: 0o600, flag: "wx" });
+        renameSync(temporary, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* Already renamed. */
+        }
+    }
+}
+export function installGuidanceRuntime(options) {
+    if (!HEX.test(options.configurationDigest))
+        throw new Error("guidance_runtime_scope_invalid");
+    const home = ensureStoreDirectory(options.environment);
+    const key = guidanceRuntimeKey(options);
+    const base = join(home, "guidance-runtime-v1");
+    const directory = join(base, key);
+    for (const path of [base, directory]) {
+        try {
+            privateDirectory(path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        checkDirectory(path);
+    }
+    const manifestPath = join(directory, "current.json");
+    let previous;
+    try {
+        previous = JSON.parse(readPrivate(manifestPath, 4096).toString("utf8"));
+        if (previous?.owner !== OWNER || previous.scopeKey !== key || !HEX.test(previous.digest))
+            throw new Error("guidance_runtime_manifest_unknown");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    // Source execution tests use the freshly built published asset too; no alternate hook implementation.
+    const bodyPath = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../dist/guidance-hook.mjs" : "./guidance-hook.mjs", import.meta.url));
+    const body = readFileSync(bodyPath);
+    if (body.length === 0 || body.length > MAX_RUNTIME)
+        throw new Error("guidance_runtime_bundle_invalid");
+    const digest = sha(body);
+    const target = join(directory, `${digest}.mjs`);
+    try {
+        if (!readPrivate(target, MAX_RUNTIME).equals(body))
+            throw new Error("guidance_runtime_body_unknown");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        writeFileSync(target, body, { mode: 0o600, flag: "wx" });
+    }
+    atomic(manifestPath, JSON.stringify({
+        owner: OWNER,
+        scopeKey: key,
+        digest,
+        configurationDigest: options.configurationDigest,
+        generation: randomBytes(16).toString("hex"),
+    }) + "\n");
+    if (previous && previous.digest !== digest) {
+        try {
+            const old = join(directory, `${previous.digest}.mjs`);
+            if (sha(readPrivate(old, MAX_RUNTIME)) === previous.digest)
+                unlinkSync(old);
+        }
+        catch {
+            /* Retain unrecognized or concurrently removed files. */
+        }
+    }
+}
+/** Stable, dependency-free wrapper. Current policy exists only in the authenticated server response. */
+export function guidanceRuntimeCommand(host, repositoryId, controlPlane) {
+    // Keep this readable: it is the exact code the host asks a person to trust once.
+    const wrapper = `
+const fs = require("node:fs"), path = require("node:path"), crypto = require("node:crypto");
+const argv = process.argv.slice(1), get = name => argv[argv.indexOf(name) + 1];
+const hook = get("--hook"), repositoryId = get("--repository"), controlPlane = get("--control-plane"), event = get("--event");
+const sha = value => crypto.createHash("sha256").update(value).digest("hex");
+const read = (file, max, privateFile) => { const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); try { const s = fs.fstatSync(fd); if (!s.isFile() || s.size > max || (privateFile && (s.mode & 63))) throw Error("unsafe"); return fs.readFileSync(fd); } finally { fs.closeSync(fd); } };
+const checkDir = dir => { const s = fs.lstatSync(dir); if (!s.isDirectory() || s.isSymbolicLink() || (s.mode & 63)) throw Error("unsafe"); };
+(async () => {
+  if (!["codex", "claude"].includes(hook) || !["SessionStart", "SubagentStart", "UserPromptSubmit"].includes(event)) return;
+  const root = fs.realpathSync(require("node:child_process").execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 250, maxBuffer: 8192 }).trim());
+  const key = sha(JSON.stringify([root, new URL(controlPlane).origin, repositoryId, hook]));
+  const home = path.resolve(process.env.BALLADEER_CONFIG_HOME?.trim() || (process.env.XDG_CONFIG_HOME?.trim() ? path.join(process.env.XDG_CONFIG_HOME.trim(), "balladeer") : path.join(require("node:os").homedir(), ".config", "balladeer")));
+  const base = path.join(home, "guidance-runtime-v1"), directory = path.join(base, key); [home, base, directory].forEach(checkDir);
+  const manifest = JSON.parse(read(path.join(directory, "current.json"), 4096, true));
+  if (manifest.owner !== "${OWNER}" || manifest.scopeKey !== key || !/^[a-f0-9]{64}$/.test(manifest.digest) || !/^[a-f0-9]{64}$/.test(manifest.configurationDigest) || !/^[a-f0-9]{32}$/.test(manifest.generation)) return;
+  try {
+    const file = path.join(directory, manifest.digest + ".mjs");
+    if (sha(read(file, ${MAX_RUNTIME}, true)) !== manifest.digest) throw Error("integrity");
+    const runtime = await import(require("node:url").pathToFileURL(file).href);
+    await runtime.runGuidance({ hook, event, runtimeGeneration: manifest.generation, repositoryId, controlPlane, environment: process.env, cwd: process.cwd(), stdin: process.stdin, write: text => process.stdout.write(text) });
+  } catch {
+    const config = path.join(root, hook === "codex" ? ".codex/config.toml" : ".mcp.json");
+    if (hook === "codex") { const s = fs.lstatSync(path.dirname(config)); if (!s.isDirectory() || s.isSymbolicLink()) return; }
+    if (sha(read(config, 262144, false)) !== manifest.configurationDigest) return;
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: ${JSON.stringify(GUIDANCE_UNAVAILABLE)} } }) + "\\n");
+  }
+})().catch(() => {});
+`.trim();
+    return `node -e ${quote(wrapper)} -- --hook ${host} --repository ${quote(repositoryId)} --control-plane ${quote(controlPlane)}`;
+}

package/dist/guidance.d.ts

@@ -0,0 +1,39 @@
+import { type StoredAgent } from "./store.js";
+export type GuidanceDocument = Readonly<{
+    schemaVersion: 1;
+    revision: string;
+    digest: string;
+    workspaceId: string;
+    repositoryId: string;
+    captureStyle: "quiet" | "thorough" | "off";
+    instructions: string;
+}>;
+export type GuidanceEvent = "SessionStart" | "SubagentStart" | "UserPromptSubmit";
+export declare const GUIDANCE_UNAVAILABLE = "Balladeer could not verify the current workspace guidance and capture mode. Continue the user's authorized work, but do not make unsolicited capture offers or file inferred promises. Do not reuse earlier Quiet/Thorough permission or cached instructions as current. An explicit request to record still requires current Balladeer tool checks and named-human agreement to meaning; never invent approval. Retry current guidance at the next hook boundary.";
+export declare function parseGuidance(value: unknown, agent: StoredAgent): GuidanceDocument;
+export declare function guidanceEndpoint(agent: StoredAgent): URL;
+export declare function guidanceScopeKey(agent: StoredAgent): string;
+export type GuidanceLoad = Readonly<{
+    status: "fresh" | "revalidated" | "unavailable";
+    document?: GuidanceDocument;
+    scopeKey: string;
+}>;
+/** Never returns stale instructions: even a cache hit requires a fresh scoped server response. */
+export declare function loadGuidance(input: {
+    agent: StoredAgent;
+    environment: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<GuidanceLoad>;
+/** Writes context first, then records emission metadata; this never claims model receipt. */
+export declare function recordGuidanceContext(input: {
+    environment: NodeJS.ProcessEnv;
+    scopeKey: string;
+    hook: "codex" | "claude";
+    event: GuidanceEvent;
+    sessionId?: string;
+    agentId?: string;
+    runtimeGeneration?: string;
+    load: GuidanceLoad;
+    now?: number;
+}, write: () => void): boolean;