balladeer 1.0.0 → 1.0.2

package/dist/git.d.ts

@@ -1,5 +1,20 @@
 export declare const CI_BRANCH = "balladeer/connect-ci";
 export declare function repositoryRoot(cwd: string): Promise<string | undefined>;
+/**
+ * The commit at HEAD, and the whole of its message.
+ *
+ * Both are read here, on the customer's machine, and only the pair of a SHA and
+ * a session id ever leaves it. That is the boundary this feature turns on:
+ * Balladeer receives commit SHAs from CI and never a commit message, so the
+ * trailer has to be read where the text already is.
+ *
+ * Absent on a repository with no commits, or on a directory that is not a
+ * checkout, which is an answer rather than a fault.
+ */
+export declare function headCommit(cwd: string): Promise<Readonly<{
+    sha: string;
+    message: string;
+}> | undefined>;
 /**
  * A repository in the middle of a merge or a rebase is not a repository to open
  * a pull request from. The person is mid-operation, and anything this command

package/dist/git.js

@@ -8,6 +8,29 @@ export async function repositoryRoot(cwd) {
     const answer = await runCommand("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
     return answer.ok ? answer.stdout.trim() : undefined;
 }
+/**
+ * The commit at HEAD, and the whole of its message.
+ *
+ * Both are read here, on the customer's machine, and only the pair of a SHA and
+ * a session id ever leaves it. That is the boundary this feature turns on:
+ * Balladeer receives commit SHAs from CI and never a commit message, so the
+ * trailer has to be read where the text already is.
+ *
+ * Absent on a repository with no commits, or on a directory that is not a
+ * checkout, which is an answer rather than a fault.
+ */
+export async function headCommit(cwd) {
+    const sha = await runCommand("git", ["-C", cwd, "rev-parse", "HEAD"]);
+    if (!sha.ok)
+        return undefined;
+    const trimmed = sha.stdout.trim();
+    if (!/^[0-9a-f]{40}$/.test(trimmed))
+        return undefined;
+    const message = await runCommand("git", ["-C", cwd, "log", "-1", "--pretty=%B", trimmed]);
+    if (!message.ok)
+        return undefined;
+    return { sha: trimmed, message: message.stdout };
+}
 async function gitDirectory(root) {
     const answer = await runCommand("git", ["-C", root, "rev-parse", "--absolute-git-dir"]);
     return answer.ok ? answer.stdout.trim() : undefined;

package/dist/legacy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The earlier Balladeer, still installed, found before this one writes anything.
+ *
+ * A team that used the July client has a program on their machine that this one
+ * knows nothing about: it updates itself from its own server rather than from
+ * npm, it registers an MCP server named `balladeer` for the whole machine, and
+ * it installs a session hook and a conventions block of its own. This product
+ * registers an MCP server under the same name, per repository. Nothing breaks
+ * loudly when both are present, which is the problem: the older session hook
+ * keeps firing inside the repository somebody enrolled today, one file ends up
+ * carrying two conventions blocks, and the person reads the result as this
+ * product misbehaving.
+ *
+ * The older client can take itself off, reversibly, with `balladeer uninstall`
+ * followed by the removal command it prints. So this is a warning that stops
+ * rather than a refusal that stands: the sentence names the one thing to do,
+ * and `--force` is there for whoever has decided to run both anyway.
+ */
+export type LegacyInstall = Readonly<{
+    /** Which file said so, in the form a person can go and open. */
+    where: string;
+    /** What was found there, bounded, so a config file cannot become an essay. */
+    detail: string;
+}>;
+/**
+ * The instruction, in the same words `docs/didero-day-one.md` and
+ * `docs/didero-mcp-walkthrough.md` print. A person who hits this in the terminal
+ * and a person who read the document ahead of time are told to do the same
+ * thing, by the same sentence.
+ */
+export declare const UNINSTALL_INSTRUCTION = "If you used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it prints, then continue.";
+/**
+ * The older install this machine still carries, or nothing.
+ *
+ * Two places, because those are the two the older client owns that reach into a
+ * session in a repository enrolled today: the machine-wide MCP entry under our
+ * own name, and the hook that fires at session start.
+ */
+export declare function findLegacyInstall(environment: NodeJS.ProcessEnv, controlPlane: string): LegacyInstall | undefined;
+/** What the person reads, whichever of the two files said so. */
+export declare function legacyMessage(found: LegacyInstall): string;

package/dist/legacy.js

@@ -0,0 +1,143 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isOurEntry } from "./mcp-config.js";
+/**
+ * The instruction, in the same words `docs/didero-day-one.md` and
+ * `docs/didero-mcp-walkthrough.md` print. A person who hits this in the terminal
+ * and a person who read the document ahead of time are told to do the same
+ * thing, by the same sentence.
+ */
+export const UNINSTALL_INSTRUCTION = "If you used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it prints, then continue.";
+/** How much of a foreign command line is worth printing back. */
+const DETAIL_LIMIT = 120;
+/**
+ * Where the agent host keeps its configuration, read from the environment this
+ * command was handed and never from the ambient process.
+ *
+ * Every command in this package takes its configuration as a parameter, which is
+ * what lets a test plant a whole home directory. When the environment names no
+ * home there is nothing to read, and a check that cannot read cannot warn: it
+ * stays silent rather than guessing at a path.
+ */
+function agentHome(environment) {
+    const home = environment.HOME?.trim() || environment.USERPROFILE?.trim() || "";
+    return home.length > 0 ? home : undefined;
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // Absent, unreadable, or somebody's hand-edited file mid-save. None of those
+        // is evidence of an older install, and none of them is this command's to fix.
+        return undefined;
+    }
+}
+function bounded(text) {
+    const flattened = text.replace(/\s+/g, " ").trim();
+    return flattened.length > DETAIL_LIMIT ? `${flattened.slice(0, DETAIL_LIMIT)}...` : flattened;
+}
+/** The command line an MCP entry runs, in the shape a person would recognise. */
+function describeEntry(entry) {
+    const record = entry;
+    if (record !== null && typeof record?.url === "string")
+        return bounded(record.url);
+    const command = typeof record?.command === "string" ? record.command : "";
+    const args = Array.isArray(record?.args)
+        ? record.args.filter((value) => typeof value === "string")
+        : [];
+    const line = [command, ...args].join(" ").trim();
+    return line.length > 0 ? bounded(line) : "a command this copy does not recognise";
+}
+/**
+ * Whether a hook's command line is one of ours.
+ *
+ * This product installs no agent-host hook at all, so in practice every hook
+ * naming `balladeer` belongs to the older client. The exception is written down
+ * anyway: a team that wired one of our own published or checkout invocations
+ * into a hook of their own must not be told their own line is somebody else's
+ * program.
+ */
+function isOurCommandLine(command) {
+    if (/balladeer@(?:latest|\d+\.\d+\.\d+)\b/.test(command))
+        return true;
+    return /\bnode\b[^\n]*\bpackages[/\\]cli[/\\]dist[/\\]cli\.js\b/.test(command);
+}
+/** Every `command` string anywhere under an agent host's `hooks` setting. */
+function hookCommands(value, found = []) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            hookCommands(item, found);
+        return found;
+    }
+    if (value === null || typeof value !== "object")
+        return found;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "command" && typeof child === "string")
+            found.push(child);
+        else
+            hookCommands(child, found);
+    }
+    return found;
+}
+/**
+ * The older Balladeer's own MCP entry, if the agent host still carries one.
+ *
+ * Only the machine-wide block counts. This product writes its entry into the
+ * repository's `.mcp.json`, and a host that also records a per-project entry
+ * under `projects` records ours there: reading those as foreign would stop
+ * setup on the very install it just performed. Under the machine-wide key, an
+ * entry named `balladeer` that is not one of our recognised shapes is the older
+ * client, because nothing else has reason to claim that name.
+ */
+function legacyMcpEntry(home, controlPlane) {
+    const parsed = readJson(join(home, ".claude.json"));
+    const servers = parsed?.mcpServers;
+    if (servers === null || typeof servers !== "object")
+        return undefined;
+    const entry = servers.balladeer;
+    if (entry === undefined || entry === null)
+        return undefined;
+    if (isOurEntry(entry, controlPlane))
+        return undefined;
+    return {
+        where: join(home, ".claude.json"),
+        detail: `an MCP server named balladeer, registered for the whole machine, running ${describeEntry(entry)}`,
+    };
+}
+/** The older Balladeer's session hook, if the agent host still runs one. */
+function legacyHook(home) {
+    const parsed = readJson(join(home, ".claude", "settings.json"));
+    const hooks = parsed?.hooks;
+    if (hooks === undefined)
+        return undefined;
+    const command = hookCommands(hooks).find((line) => /balladeer/i.test(line) && !isOurCommandLine(line));
+    if (command === undefined)
+        return undefined;
+    return {
+        where: join(home, ".claude", "settings.json"),
+        detail: `a hook that runs ${bounded(command)}`,
+    };
+}
+/**
+ * The older install this machine still carries, or nothing.
+ *
+ * Two places, because those are the two the older client owns that reach into a
+ * session in a repository enrolled today: the machine-wide MCP entry under our
+ * own name, and the hook that fires at session start.
+ */
+export function findLegacyInstall(environment, controlPlane) {
+    const home = agentHome(environment);
+    if (home === undefined)
+        return undefined;
+    return legacyMcpEntry(home, controlPlane) ?? legacyHook(home);
+}
+/** What the person reads, whichever of the two files said so. */
+export function legacyMessage(found) {
+    return [
+        `An earlier Balladeer is still installed on this machine: ${found.where} carries ${found.detail}.`,
+        "Both products register an MCP server named balladeer and the earlier one keeps firing its own session hook, so leaving it in place puts two Balladeers in the sessions you open in this repository.",
+        UNINSTALL_INSTRUCTION,
+        "Nothing was changed. Run this command again with --force to set up anyway.",
+    ].join("\n");
+}

package/dist/local-time.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Every absolute time this command prints for a person, on the clock they read.
+ *
+ * Robert approved a pairing code that had already lapsed. The screen said the
+ * code stopped being approvable at a time four hours ahead of the one on his
+ * wall, and named no zone, so he read a moment that had gone as a moment still
+ * to come. `apps/control-plane/lib/local-time.ts` fixed that on the web pages
+ * and says why: an unlabelled time is not a shorter time, it is a different one.
+ *
+ * The terminal had no equivalent, and it prints the same deadlines: the pairing
+ * code, the setup session, the invitation, when a map was measured, when a run
+ * observed a failure. Every one of them was a UTC instant in a sentence a person
+ * reads. So nothing here formats an instant without saying which clock it is on.
+ *
+ * Unlike a server render, this one always knows: the command runs on the
+ * reader's own machine, so there is a single shape rather than the web's pair of
+ * them, and it is the shape the web already shows a signed-in viewer, so a
+ * person who reads a deadline in the terminal and again on the promise page
+ * reads it written the same way both times.
+ *
+ * It is a copy of the control plane's formatter rather than an import of it.
+ * This package is published to npm on its own and must not carry the web
+ * application behind it; the rule the two share is the one in the guard tests,
+ * which hold both surfaces to the same sentence.
+ *
+ * Machine-readable output is not this module's business. `--json` steps carry
+ * the ISO instant exactly as Balladeer sent it, because the reader there is a
+ * program with its own clock and its own zone.
+ */
+/** What a stored value that is not a time says, rather than "Invalid Date". */
+export declare const UNREADABLE_TIME = "an unrecorded time";
+/**
+ * The zone this machine is set to.
+ *
+ * Every reach for `Intl` in the command is in this one file, which is what lets
+ * the guard test state the rule as a scan rather than as a list of sentences
+ * somebody has to remember to extend.
+ */
+export declare function machineTimeZone(): string;
+/**
+ * One instant, in the reader's own zone, with the zone named beside it.
+ *
+ * `timeZoneName: "short"` is the load-bearing option. Remove it and every
+ * sentence below silently goes back to printing a bare wall clock, which is the
+ * bug this module exists for, so the guard test asserts a zone token on the end
+ * of the output in every zone it checks.
+ *
+ * The zone is a parameter so the tests can read one instant on several clocks.
+ * No caller passes one: the machine's own zone is the answer for a command that
+ * runs on the reader's machine.
+ */
+export declare function formatInstant(value: string, timeZone?: string): string;
+/**
+ * A sentence Balladeer wrote, with the instants in it moved onto the reader's
+ * clock.
+ *
+ * Some refusals are relayed to the terminal word for word, on purpose: the
+ * server's sentence names what to do next, and rewriting it here would lose the
+ * part the person has to act on. But the server has no idea where the reader is
+ * sitting, so it writes UTC, and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reaches somebody whose clock says 2:05 in the
+ * afternoon. This moves the instants and leaves every other word alone, so what
+ * an agent is told over the tool call and what a person is told at a terminal
+ * stay the same sentence.
+ */
+export declare function inReadersZone(text: string, timeZone?: string): string;

package/dist/local-time.js

@@ -0,0 +1,84 @@
+/**
+ * Every absolute time this command prints for a person, on the clock they read.
+ *
+ * Robert approved a pairing code that had already lapsed. The screen said the
+ * code stopped being approvable at a time four hours ahead of the one on his
+ * wall, and named no zone, so he read a moment that had gone as a moment still
+ * to come. `apps/control-plane/lib/local-time.ts` fixed that on the web pages
+ * and says why: an unlabelled time is not a shorter time, it is a different one.
+ *
+ * The terminal had no equivalent, and it prints the same deadlines: the pairing
+ * code, the setup session, the invitation, when a map was measured, when a run
+ * observed a failure. Every one of them was a UTC instant in a sentence a person
+ * reads. So nothing here formats an instant without saying which clock it is on.
+ *
+ * Unlike a server render, this one always knows: the command runs on the
+ * reader's own machine, so there is a single shape rather than the web's pair of
+ * them, and it is the shape the web already shows a signed-in viewer, so a
+ * person who reads a deadline in the terminal and again on the promise page
+ * reads it written the same way both times.
+ *
+ * It is a copy of the control plane's formatter rather than an import of it.
+ * This package is published to npm on its own and must not carry the web
+ * application behind it; the rule the two share is the one in the guard tests,
+ * which hold both surfaces to the same sentence.
+ *
+ * Machine-readable output is not this module's business. `--json` steps carry
+ * the ISO instant exactly as Balladeer sent it, because the reader there is a
+ * program with its own clock and its own zone.
+ */
+/** What a stored value that is not a time says, rather than "Invalid Date". */
+export const UNREADABLE_TIME = "an unrecorded time";
+/**
+ * The zone this machine is set to.
+ *
+ * Every reach for `Intl` in the command is in this one file, which is what lets
+ * the guard test state the rule as a scan rather than as a list of sentences
+ * somebody has to remember to extend.
+ */
+export function machineTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+/**
+ * One instant, in the reader's own zone, with the zone named beside it.
+ *
+ * `timeZoneName: "short"` is the load-bearing option. Remove it and every
+ * sentence below silently goes back to printing a bare wall clock, which is the
+ * bug this module exists for, so the guard test asserts a zone token on the end
+ * of the output in every zone it checks.
+ *
+ * The zone is a parameter so the tests can read one instant on several clocks.
+ * No caller passes one: the machine's own zone is the answer for a command that
+ * runs on the reader's machine.
+ */
+export function formatInstant(value, timeZone = machineTimeZone()) {
+    const when = new Date(value);
+    if (Number.isNaN(when.valueOf()))
+        return UNREADABLE_TIME;
+    return new Intl.DateTimeFormat("en-US", {
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        timeZone,
+        timeZoneName: "short",
+    }).format(when);
+}
+/** An instant as Balladeer writes one: ISO 8601, UTC, to the millisecond. */
+const ISO_INSTANT = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
+/**
+ * A sentence Balladeer wrote, with the instants in it moved onto the reader's
+ * clock.
+ *
+ * Some refusals are relayed to the terminal word for word, on purpose: the
+ * server's sentence names what to do next, and rewriting it here would lose the
+ * part the person has to act on. But the server has no idea where the reader is
+ * sitting, so it writes UTC, and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reaches somebody whose clock says 2:05 in the
+ * afternoon. This moves the instants and leaves every other word alone, so what
+ * an agent is told over the tool call and what a person is told at a terminal
+ * stay the same sentence.
+ */
+export function inReadersZone(text, timeZone = machineTimeZone()) {
+    return text.replace(ISO_INSTANT, (instant) => formatInstant(instant, timeZone));
+}

package/dist/mcp-config.d.ts

@@ -75,6 +75,16 @@ export declare function stdioEntry(repositoryId: string, publishedVersion: strin
  * Balladeer entry is foreign.
  */
 export declare function isOurEntry(entry: unknown, controlPlane: string): boolean;
+/**
+ * Atomic, and never through a path something could have pre-planted: the
+ * temporary file is opened with `wx` under a random name in the same directory,
+ * flushed, and renamed over the target.
+ *
+ * Exported because the Claude desktop configuration is written under the same
+ * rule and for a stronger reason: that file belongs to a running application,
+ * and a half-written one is a chat client that starts with no servers at all.
+ */
+export declare function writeJsonAtomically(path: string, contents: string): void;
 /**
  * Merges our entry into the repository's `.mcp.json`, or refuses.
  *

package/dist/mcp-config.js

@@ -112,9 +112,13 @@ function renderBlock(entry) {
  * Atomic, and never through a path something could have pre-planted: the
  * temporary file is opened with `wx` under a random name in the same directory,
  * flushed, and renamed over the target.
+ *
+ * Exported because the Claude desktop configuration is written under the same
+ * rule and for a stronger reason: that file belongs to a running application,
+ * and a half-written one is a chat client that starts with no servers at all.
  */
-function writeAtomically(path, contents) {
-    const temporary = join(dirname(path), `.mcp.${randomBytes(8).toString("hex")}.tmp`);
+export function writeJsonAtomically(path, contents) {
+    const temporary = join(dirname(path), `.balladeer.${randomBytes(8).toString("hex")}.tmp`);
     let descriptor;
     try {
         descriptor = openSync(temporary, "wx", 0o644);
@@ -157,7 +161,7 @@ export function mergeMcpConfig(repositoryRoot, entry, controlPlane) {
         existing = readFileSync(path, "utf8");
     }
     catch {
-        writeAtomically(path, `${JSON.stringify({ mcpServers: { balladeer: entry } }, null, 2)}\n`);
+        writeJsonAtomically(path, `${JSON.stringify({ mcpServers: { balladeer: entry } }, null, 2)}\n`);
         return { kind: "written", changed: true };
     }
     let parsed;
@@ -192,7 +196,7 @@ export function mergeMcpConfig(repositoryRoot, entry, controlPlane) {
     const next = `${JSON.stringify({ ...parsed, mcpServers: servers }, null, 2)}\n`;
     if (next === existing)
         return { kind: "written", changed: false };
-    writeAtomically(path, next);
+    writeJsonAtomically(path, next);
     return { kind: "written", changed: true };
 }
 /**

package/dist/session.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The id that ties what an agent was told to what it then wrote.
+ *
+ * A retrieval read happens before the commit exists, so nothing joins the two
+ * on its own. The agent's own working session is what spans them: it reads the
+ * index under this id, and writes the same id into the commit trailer. That is
+ * the whole mechanism, and it lives here rather than on the server because the
+ * server never sees a commit message.
+ *
+ * The id is opaque and says nothing about the work. It is not a secret either:
+ * it is written into commit messages, which is exactly where people will read
+ * it. What it must be is stable across one piece of work and different across
+ * two, which is what the marker file below is for.
+ */
+/**
+ * The shape of a session id, and the line that carries it into a commit.
+ *
+ * Written out here rather than imported. This command is published to npm on
+ * its own and depends on nothing, so the grammar it uses has to live inside it;
+ * a packaging test compares these three against the control plane's own
+ * definitions, so a drift fails here rather than as a token the server refuses
+ * out of a customer's commit message.
+ */
+export declare const AGENT_SESSION_ID_PATTERN: RegExp;
+/** The trailer key an agent writes into the commit or the pull-request body. */
+export declare const AGENT_SESSION_TRAILER = "Balladeer-Session";
+/** The exact line to paste, so every carrier spells the trailer one way. */
+export declare function agentSessionTrailerLine(sessionId: string): string;
+/**
+ * The session id a commit message or pull-request body carries, if it carries
+ * one this release would recognise.
+ *
+ * A body carrying two different session ids is refused rather than resolved:
+ * two answers to "which session wrote this" is not one answer, and guessing
+ * which of them to record would put an invented join in front of a number.
+ */
+export declare function readAgentSessionTrailer(text: string): string | undefined;
+/** Where the current session for a repository is remembered. */
+export declare const SESSION_FILE = "sessions.json";
+/**
+ * How long one session id stays current.
+ *
+ * A working session is a sitting, not a calendar day. Twelve hours is long
+ * enough that a morning's work and the commit that ends it share an id, and
+ * short enough that a machine left running overnight starts the next day's work
+ * under a new one rather than attributing tomorrow's commits to yesterday's
+ * reads. `--new` is the manual answer for anyone whose sitting ends earlier.
+ */
+export declare const SESSION_LIFETIME_MS: number;
+export type SessionMark = Readonly<{
+    /** Which repository this session belongs to, as the credential names it. */
+    repository: string;
+    sessionId: string;
+    startedAt: string;
+}>;
+type SessionFile = {
+    version: 1;
+    sessions: SessionMark[];
+};
+/** A fresh id: the prefix a person can recognise, and 128 bits of nothing else. */
+export declare function mintSessionId(): string;
+export declare function isSessionId(value: string): boolean;
+export declare function readSessionMarks(environment?: NodeJS.ProcessEnv): SessionFile;
+export type CurrentSession = Readonly<{
+    sessionId: string;
+    startedAt: string;
+    /** True when this call minted it, false when it was already current. */
+    minted: boolean;
+}>;
+/**
+ * The session id for this repository right now, minting one when there is none
+ * current.
+ *
+ * Reusing a live one is the point. An agent that asks twice in one sitting must
+ * get the same answer, or its reads and its commit end up under two ids and the
+ * join it exists to make is broken by the act of asking for it.
+ */
+export declare function currentSession(input: Readonly<{
+    repository: string;
+    now: string;
+    forceNew?: boolean;
+    environment?: NodeJS.ProcessEnv;
+}>): CurrentSession;
+export {};

package/dist/session.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertSafeStoreLocation, configHome, writeStoreFile } from "./store.js";
+/**
+ * The id that ties what an agent was told to what it then wrote.
+ *
+ * A retrieval read happens before the commit exists, so nothing joins the two
+ * on its own. The agent's own working session is what spans them: it reads the
+ * index under this id, and writes the same id into the commit trailer. That is
+ * the whole mechanism, and it lives here rather than on the server because the
+ * server never sees a commit message.
+ *
+ * The id is opaque and says nothing about the work. It is not a secret either:
+ * it is written into commit messages, which is exactly where people will read
+ * it. What it must be is stable across one piece of work and different across
+ * two, which is what the marker file below is for.
+ */
+/**
+ * The shape of a session id, and the line that carries it into a commit.
+ *
+ * Written out here rather than imported. This command is published to npm on
+ * its own and depends on nothing, so the grammar it uses has to live inside it;
+ * a packaging test compares these three against the control plane's own
+ * definitions, so a drift fails here rather than as a token the server refuses
+ * out of a customer's commit message.
+ */
+export const AGENT_SESSION_ID_PATTERN = /^bs_[0-9a-f]{32}$/;
+/** The trailer key an agent writes into the commit or the pull-request body. */
+export const AGENT_SESSION_TRAILER = "Balladeer-Session";
+/** The exact line to paste, so every carrier spells the trailer one way. */
+export function agentSessionTrailerLine(sessionId) {
+    return `${AGENT_SESSION_TRAILER}: ${sessionId}`;
+}
+/**
+ * The session id a commit message or pull-request body carries, if it carries
+ * one this release would recognise.
+ *
+ * A body carrying two different session ids is refused rather than resolved:
+ * two answers to "which session wrote this" is not one answer, and guessing
+ * which of them to record would put an invented join in front of a number.
+ */
+export function readAgentSessionTrailer(text) {
+    const pattern = new RegExp(`^[ \\t]*${AGENT_SESSION_TRAILER}[ \\t]*:[ \\t]*(\\S+)[ \\t]*$`, "gim");
+    const found = new Set();
+    for (const match of text.matchAll(pattern)) {
+        const value = match[1];
+        if (value !== undefined && isSessionId(value))
+            found.add(value);
+    }
+    if (found.size !== 1)
+        return undefined;
+    return [...found][0];
+}
+/** Where the current session for a repository is remembered. */
+export const SESSION_FILE = "sessions.json";
+/**
+ * How long one session id stays current.
+ *
+ * A working session is a sitting, not a calendar day. Twelve hours is long
+ * enough that a morning's work and the commit that ends it share an id, and
+ * short enough that a machine left running overnight starts the next day's work
+ * under a new one rather than attributing tomorrow's commits to yesterday's
+ * reads. `--new` is the manual answer for anyone whose sitting ends earlier.
+ */
+export const SESSION_LIFETIME_MS = 12 * 60 * 60 * 1000;
+const EMPTY = { version: 1, sessions: [] };
+/** A fresh id: the prefix a person can recognise, and 128 bits of nothing else. */
+export function mintSessionId() {
+    return `bs_${randomBytes(16).toString("hex")}`;
+}
+export function isSessionId(value) {
+    return AGENT_SESSION_ID_PATTERN.test(value);
+}
+function sessionPath(environment) {
+    return join(configHome(environment), SESSION_FILE);
+}
+export function readSessionMarks(environment = process.env) {
+    let raw;
+    try {
+        raw = readFileSync(sessionPath(environment), "utf8");
+    }
+    catch {
+        return { version: 1, sessions: [] };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const sessions = Array.isArray(parsed.sessions) ? parsed.sessions : [];
+        // A marker whose id this build would not recognise is dropped rather than
+        // repaired. It can only have come from a copy of this command that spelled
+        // ids differently, and reusing one would put a token the server refuses
+        // into a commit message where nobody would ever look for the cause.
+        return { version: 1, sessions: sessions.filter((mark) => isSessionId(mark.sessionId)) };
+    }
+    catch {
+        return { ...EMPTY, sessions: [] };
+    }
+}
+function writeSessionMarks(file, environment) {
+    assertSafeStoreLocation(configHome(environment), environment);
+    writeStoreFile(SESSION_FILE, `${JSON.stringify(file, null, 2)}\n`, environment);
+}
+/**
+ * The session id for this repository right now, minting one when there is none
+ * current.
+ *
+ * Reusing a live one is the point. An agent that asks twice in one sitting must
+ * get the same answer, or its reads and its commit end up under two ids and the
+ * join it exists to make is broken by the act of asking for it.
+ */
+export function currentSession(input) {
+    const environment = input.environment ?? process.env;
+    const file = readSessionMarks(environment);
+    const existing = file.sessions.find((mark) => mark.repository === input.repository);
+    const age = existing === undefined ? undefined : Date.parse(input.now) - Date.parse(existing.startedAt);
+    const usable = existing !== undefined &&
+        input.forceNew !== true &&
+        age !== undefined &&
+        Number.isFinite(age) &&
+        age >= 0 &&
+        age < SESSION_LIFETIME_MS;
+    if (usable && existing !== undefined) {
+        return { sessionId: existing.sessionId, startedAt: existing.startedAt, minted: false };
+    }
+    const minted = {
+        repository: input.repository,
+        sessionId: mintSessionId(),
+        startedAt: input.now,
+    };
+    writeSessionMarks({
+        version: 1,
+        sessions: [...file.sessions.filter((mark) => mark.repository !== input.repository), minted],
+    }, environment);
+    return { sessionId: minted.sessionId, startedAt: minted.startedAt, minted: true };
+}