balladeer 1.0.1 → 1.0.3

package/dist/codex-config.js

@@ -0,0 +1,159 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { join } from "node:path";
+import { parse } from "@iarna/toml";
+import { isOurEntry } from "./mcp-config.js";
+export const CODEX_CONFIG_FILE = ".codex/config.toml";
+const START = "# balladeer:mcp:start";
+const END = "# balladeer:mcp:end";
+function render(entry) {
+    return [
+        START,
+        "[mcp_servers.balladeer]",
+        `command = ${JSON.stringify(entry.command)}`,
+        `args = ${JSON.stringify(entry.args)}`,
+        ...(entry.env
+            ? [
+                "[mcp_servers.balladeer.env]",
+                ...Object.entries(entry.env).map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`),
+            ]
+            : []),
+        END,
+        "",
+    ].join("\n");
+}
+function withoutOurs(value) {
+    const copy = structuredClone(value);
+    const servers = copy.mcp_servers;
+    if (servers &&
+        typeof servers === "object" &&
+        !Array.isArray(servers) &&
+        !(servers instanceof Date)) {
+        delete servers.balladeer;
+        if (Object.keys(servers).length === 0)
+            delete copy.mcp_servers;
+    }
+    return JSON.stringify(copy);
+}
+export function readCodexEntry(root) {
+    try {
+        const config = parse(readFileSync(join(root, CODEX_CONFIG_FILE), "utf8"));
+        const servers = config.mcp_servers;
+        return servers &&
+            typeof servers === "object" &&
+            !Array.isArray(servers) &&
+            !(servers instanceof Date)
+            ? servers.balladeer
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A client hint only when the complete file and our exact fenced table agree. */
+export function hasManagedCodexEntry(root, controlPlane) {
+    try {
+        const text = readFileSync(join(root, CODEX_CONFIG_FILE), "utf8");
+        const starts = [...text.matchAll(/^# balladeer:mcp:start\r?$/gm)];
+        const ends = [...text.matchAll(/^# balladeer:mcp:end\r?$/gm)];
+        if (starts.length !== 1 ||
+            ends.length !== 1 ||
+            !starts[0] ||
+            !ends[0] ||
+            starts[0].index >= ends[0].index)
+            return false;
+        const block = parse(text.slice(starts[0].index + starts[0][0].length, ends[0].index));
+        const servers = block.mcp_servers;
+        if (Object.keys(block).length !== 1 ||
+            !servers ||
+            typeof servers !== "object" ||
+            Array.isArray(servers) ||
+            servers instanceof Date ||
+            Object.keys(servers).length !== 1)
+            return false;
+        const own = readCodexEntry(root);
+        return (isOurEntry(own, controlPlane) && JSON.stringify(own) === JSON.stringify(servers.balladeer));
+    }
+    catch {
+        return false;
+    }
+}
+/** Only our fenced table is replaced; every unrelated byte and parsed setting survives. */
+export function mergeCodexConfig(root, entry, controlPlane) {
+    const block = render(entry);
+    const refused = (reason) => ({
+        kind: "refused",
+        reason: `${CODEX_CONFIG_FILE}: ${reason} No configuration was changed.`,
+        block,
+    });
+    const directory = join(root, ".codex");
+    const path = join(root, CODEX_CONFIG_FILE);
+    if (existsSync(directory) &&
+        (!lstatSync(directory).isDirectory() || lstatSync(directory).isSymbolicLink()))
+        return refused("the directory is not an ordinary project directory.");
+    if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()))
+        return refused("the file is not an ordinary project file.");
+    let previous = "";
+    let parsed;
+    try {
+        if (existsSync(path))
+            previous = readFileSync(path, "utf8");
+        parsed = parse(previous);
+    }
+    catch {
+        return refused("could not read valid TOML; repair the file before running setup again.");
+    }
+    const starts = [...previous.matchAll(/^# balladeer:mcp:start\r?$/gm)];
+    const ends = [...previous.matchAll(/^# balladeer:mcp:end\r?$/gm)];
+    if (starts.length !== ends.length ||
+        starts.length > 1 ||
+        (starts[0] && ends[0] && starts[0].index >= ends[0].index))
+        return refused("the Balladeer markers are damaged; repair them before running setup again.");
+    const servers = parsed.mcp_servers;
+    if (servers !== undefined &&
+        (servers === null ||
+            typeof servers !== "object" ||
+            Array.isArray(servers) ||
+            servers instanceof Date))
+        return refused("mcp_servers must be a table.");
+    const own = servers && typeof servers === "object" && !Array.isArray(servers) && !(servers instanceof Date)
+        ? servers.balladeer
+        : undefined;
+    if (own !== undefined && (!starts[0] || !isOurEntry(own, controlPlane)))
+        return refused("an unmanaged or unrecognized balladeer table already exists. Review it and merge the supplied block yourself; setup will not replace it.");
+    if (starts[0] && own === undefined)
+        return refused("the marked block does not contain a Balladeer server; review the markers first.");
+    const next = starts[0] && ends[0]
+        ? previous.slice(0, starts[0].index) +
+            block.trimEnd() +
+            previous.slice(ends[0].index + ends[0][0].length)
+        : previous + (previous.endsWith("\n") || previous === "" ? "" : "\n") + "\n" + block;
+    try {
+        const result = parse(next);
+        if (withoutOurs(parsed) !== withoutOurs(result))
+            return refused("the marked replacement would change another setting; review the block manually.");
+    }
+    catch {
+        return refused("the proposed block conflicts with existing TOML tables; merge the supplied block manually.");
+    }
+    if (next === previous)
+        return { kind: "written", changed: false };
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.balladeer.${randomBytes(8).toString("hex")}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, "wx", existsSync(path) ? lstatSync(path).mode & 0o777 : 0o600);
+        writeSync(descriptor, next);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temporary, path);
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+    return { kind: "written", changed: true };
+}

package/dist/commands/affected.js

@@ -1,7 +1,7 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { TOUCH_MAP_FILE, affectedPaths, readLocalPackages, readTouchMap, verifierDigest, } from "../touch-map.js";
 import { formatInstant } from "../local-time.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 import { promiseRoot } from "./touch-map.js";
 /** How many promises one path lists before the report says how many more. */
 const NAMED_LIMIT = 20;
@@ -36,7 +36,7 @@ export async function runAffected(options) {
             options.write(`${text}\n`);
     };
     if (options.paths.length === 0) {
-        const message = "Name at least one path: balladeer affected src/orders/total.ts";
+        const message = `Name at least one path: ${CLI_INVOCATION} affected src/orders/total.ts`;
         if (options.json)
             emit({ step: "error", reason: "usage", message, changed: false, exitCode: 4 });
         else
@@ -55,8 +55,8 @@ export async function runAffected(options) {
     const reading = readTouchMap(root);
     if (reading.kind !== "map") {
         const message = reading.kind === "absent"
-            ? `There is no touch map in this checkout yet. Build one with: balladeer touch-map`
-            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: balladeer touch-map`;
+            ? `There is no touch map in this checkout yet. Build one with: ${CLI_INVOCATION} touch-map`
+            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: ${CLI_INVOCATION} touch-map`;
         emit({ step: "affected", mapped: false, paths: [], changed: false });
         say(message);
         // Zero, because having no map is not a fault in the change somebody is
@@ -115,8 +115,8 @@ export async function runAffected(options) {
     say("");
     if (stale > 0) {
         say(stale === 1
-            ? "One answer above is stale. Run balladeer touch-map to measure it again."
-            : `${stale} of those answers are stale. Run balladeer touch-map to measure them again.`);
+            ? `One answer above is stale. Run ${CLI_INVOCATION} touch-map to measure it again.`
+            : `${stale} of those answers are stale. Run ${CLI_INVOCATION} touch-map to measure them again.`);
     }
     say("This came from your own checkout. Balladeer was not asked, and was told nothing.");
     return 0;

package/dist/commands/check-seals.js

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import { runCommand } from "../gh.js";
 import { repositoryRoot } from "../git.js";
 import { promiseForPath, sealedPromises } from "../seals.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 /**
  * Where the pinned runner sits once setup's instructions have been followed.
  *
@@ -258,17 +258,17 @@ function installPrePushHook(root, options, emit, say) {
     const hookPath = join(root, ".git", "hooks", "pre-push");
     if (existsSync(hookPath)) {
         const message = `${hookPath} already exists, so nothing was written. Add this line to it yourself if you ` +
-            "want the check: balladeer check-seals";
+            `want the check: ${CLI_INVOCATION} check-seals`;
         emit({ step: "error", reason: "hook_exists", message, changed: false, exitCode: 4 });
         say(message);
         return 4;
     }
     const script = [
         "#!/bin/sh",
-        "# Installed by: balladeer check-seals --install-hook",
+        `# Installed by: ${CLI_INVOCATION} check-seals --install-hook`,
         "# It stops a push that would break a promise's seal, and says nothing otherwise.",
         "# Delete this file to remove it.",
-        "balladeer check-seals || exit 1",
+        `${CLI_INVOCATION} check-seals || exit 1`,
         "",
     ].join("\n");
     try {

package/dist/commands/discover.js

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs";
-import { callAgentTool, selectAgent, structuredString } from "../agent.js";
+import { callAgentTool, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
 import { batchProposalReviewLink, proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 import { readTeachBackFile } from "./propose.js";
 /**
  * Ten promises at 64 KiB each, which is the per-promise cap `propose` already
@@ -197,7 +197,7 @@ export async function runDiscover(options) {
         return exitCode;
     };
     if (!options.file) {
-        return fail("usage", "Give a catalog file: balladeer discover --file <path>.", 4);
+        return fail("usage", `Give a catalog file: ${CLI_INVOCATION} discover --file <path>.`, 4);
     }
     let raw;
     try {
@@ -232,6 +232,7 @@ export async function runDiscover(options) {
             `Run \`${commandLine(null, "setup")}\` here again to pair this machine, which records who you are, or name the owner yourself with --owner <membership id> from the members list on the Balladeer MCP server's setup tool.`, 4);
     }
     const setup = await callAgentTool(agent, "get_promise_setup", {});
+    reportAgentEnforcementWarning(setup, options);
     if (setup.kind !== "result") {
         return fail("owner_unverified", `${memberListRefusal(setup.kind, options.controlPlane)} Nothing was sent.`, 5);
     }
@@ -254,7 +255,7 @@ export async function runDiscover(options) {
                 index: index + 1,
                 title,
                 candidateId: outcome.candidateId,
-                reviewUrl: proposalReviewLink(options.controlPlane, outcome.candidateId),
+                reviewUrl: proposalReviewLink(options.controlPlane, outcome.candidateId, agent.workspaceId),
             };
             filed.push(entry);
             emit({

package/dist/commands/prepare.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { callAgentTool, noAgentCredentialSentence, selectAgent } from "../agent.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, } from "../agent.js";
 import { inReadersZone } from "../local-time.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
@@ -150,6 +150,7 @@ export async function runPrepare(options) {
         promiseId: options.promiseId,
         again: options.again,
     });
+    reportAgentEnforcementWarning(call, options);
     switch (call.kind) {
         case "endpoint_refused":
             return fail("agent_endpoint_unsafe", `${call.reason} Nothing was prepared.`, 4);

package/dist/commands/propose.js

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs";
-import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
 import { proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 const MAX_FILE_BYTES = 64 * 1024;
 /**
  * Every field the server's schema requires with no default. It is every
@@ -190,7 +190,7 @@ export async function runPropose(options) {
         return exitCode;
     };
     if (!options.file) {
-        return fail("usage", "Give a proposal file: balladeer propose --file <path>.", 4);
+        return fail("usage", `Give a proposal file: ${CLI_INVOCATION} propose --file <path>.`, 4);
     }
     let raw;
     try {
@@ -240,6 +240,7 @@ export async function runPropose(options) {
             ? {}
             : { leastSure: parsed.value.teachBack.leastSure }),
     });
+    reportAgentEnforcementWarning(call, options);
     switch (call.kind) {
         case "endpoint_refused":
             return fail("agent_endpoint_unsafe", `${call.reason} Nothing was sent.`, 4);
@@ -273,7 +274,7 @@ export async function runPropose(options) {
     // The review link is built from the address this copy paired with. The tool
     // answers with an id and no link at all, so there is nothing here a
     // misconfigured public base URL could redirect.
-    const review = proposalReviewLink(options.controlPlane, candidateId);
+    const review = proposalReviewLink(options.controlPlane, candidateId, agent.workspaceId);
     emit({ step: "promise", status: "proposed", candidateId, reviewUrl: review });
     if (!options.json) {
         options.write("Proposed. You will own it unless you named someone else; the owner reads it and clicks Agree, and nothing else can.\n");

package/dist/commands/repositories.js

@@ -94,6 +94,7 @@ function report(options, rows, workspaceKnown) {
     say(options, workspaceKnown
         ? "Repositories your GitHub account can see. Ones already in Balladeer are marked."
         : "Repositories your GitHub account can see. Nothing is stored for this Balladeer, so which of them are already added is unknown.");
+    say(options, "These are GitHub repositories, not local directories or git worktrees.");
     say(options, "");
     for (const row of rows) {
         const marks = [

package/dist/commands/session.js

@@ -1,9 +1,9 @@
-import { callAgentTool, noAgentCredentialSentence, selectAgent } from "../agent.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, } from "../agent.js";
 import { headCommit } from "../git.js";
 import { repositoryHint } from "../repository.js";
 import { AGENT_SESSION_TRAILER, agentSessionTrailerLine, currentSession, readAgentSessionTrailer, } from "../session.js";
 import { StoreError, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 /**
  * The id that joins what an agent was told to what it then wrote.
  *
@@ -63,6 +63,18 @@ export async function runSession(options) {
         });
     }
     catch (error) {
+        // This catch follows successful credential selection and covers only the
+        // local marker write. It must never turn an auth or --record refusal into
+        // permission to continue, or print the freshly generated but unsaved ID.
+        const filesystemError = error instanceof StoreError && error.code === "credential_store_unwritable"
+            ? error.cause
+            : error;
+        const permissionCode = filesystemError instanceof Error && "code" in filesystemError
+            ? filesystemError.code
+            : undefined;
+        if (permissionCode === "EPERM" || permissionCode === "EACCES") {
+            return fail("session_store_permission_denied", `No session stamp was saved: local file permissions refused the write (${permissionCode}). Your saved authenticated connection is unchanged; this command has not checked it with the server. Continue already-authorized MCP reads, coding and explicitly requested capture without the optional session field. Do not invent an ID, add a session trailer, or run session --record for this unsaved stamp. Do not broaden filesystem access or move credentials to retry this write. Capture still requires the person's request or accepted offer, and human meaning approval is unchanged.`, 4);
+        }
         return fail(error instanceof StoreError ? error.code : "session_store_unwritable", error instanceof StoreError ? error.message : String(error), 4);
     }
     const trailer = agentSessionTrailerLine(session.sessionId);
@@ -83,7 +95,7 @@ export async function runSession(options) {
     say("");
     say(`    ${trailer}`);
     say("");
-    say(`and run \`balladeer session --record\` once the commit exists, so a check that goes red on it can be read back against what you were told before you started. Balladeer is sent the session id and the commit SHA, and nothing else.`);
+    say(`and run \`${CLI_INVOCATION} session --record\` once the commit exists, so a check that goes red on it can be read back against what you were told before you started. Balladeer is sent the session id and the commit SHA, and nothing else.`);
     return 0;
 }
 async function recordCommit(options, agent, emit, say, fail) {
@@ -96,12 +108,13 @@ async function recordCommit(options, agent, emit, say, fail) {
         // Said in full rather than as a code. The likeliest reader of this line is
         // an agent that forgot the trailer, and the remedy is one line it can add
         // to the commit it just made.
-        return fail("no_session_trailer", `The commit at HEAD carries no ${AGENT_SESSION_TRAILER} line this release recognises, so there is nothing to record. Add \`${AGENT_SESSION_TRAILER}: <the id balladeer session prints>\` to the commit message and run this again. A commit carrying two different session ids is refused rather than guessed at.`, 4);
+        return fail("no_session_trailer", `The commit at HEAD carries no ${AGENT_SESSION_TRAILER} line this release recognises, so there is nothing to record. Add \`${AGENT_SESSION_TRAILER}: <the id ${CLI_INVOCATION} session prints>\` to the commit message and run this again. A commit carrying two different session ids is refused rather than guessed at.`, 4);
     }
     const call = await callAgentTool(agent, "record_session_commit", {
         session: sessionId,
         commitSha: head.sha,
     });
+    reportAgentEnforcementWarning(call, options);
     if (call.kind !== "result") {
         return fail(call.kind === "tool_refusal" ? "refused" : call.kind, call.kind === "tool_refusal"
             ? call.text

package/dist/commands/setup.d.ts

@@ -4,6 +4,8 @@ export type SetupOptions = Readonly<{
     wait: boolean;
     repo?: string;
     createWorkspace?: string;
+    client?: "codex" | "claude";
+    chooseWorkspace?: boolean;
     /**
      * Every repository this run was told to set up, in the order they were named.
      *
@@ -14,6 +16,12 @@ export type SetupOptions = Readonly<{
      * one checkout can honestly do from here, and the run says so per repository.
      */
     repositories?: readonly string[];
+    /**
+     * Connect an invited teammate to a repository the workspace already holds.
+     * This is deliberately a refusal boundary: if the repository is absent, the
+     * run stops rather than turning an invitation into authority to enroll it.
+     */
+    existingOnly?: boolean;
     /**
      * Repair the two files a previous setup wrote in this repository, and do
      * nothing else. No pairing, no enrollment, no credential, no network: a