vouchington-tooling 0.45.0 → 0.47.0

package/dist/gh-cli/exec.d.mts

@@ -1,16 +1,19 @@
 /** A text-mode command runner: argv in, stdout out. Rejects on a non-zero exit. */
 export type RunTextCommand = (args: string[]) => Promise<string>;
 /** The `child_process.execFile` shape `createCommandRunner` wraps — injectable for tests. */
-export type ExecFileText = (command: string, args: string[]) => Promise<{
+export type ExecFileText = (command: string, args: string[], options?: {
+    env: NodeJS.ProcessEnv;
+}) => Promise<{
     stdout: string;
 }>;
 /**
  * Builds a `RunTextCommand` bound to a fixed binary. The default `exec` wraps `execFile` via
  * `promisify` so a test can inject a fake without spawning a real process; `runGh`/`runGit` below
- * are this factory applied to the two binaries this module cares about.
+ * are this factory applied to the two binaries this module cares about. `buildEnv` maps the
+ * parent environment to the one the child is spawned with (identity by default).
  */
-export declare function createCommandRunner(command: string, exec?: ExecFileText): RunTextCommand;
-/** Runs `gh` and returns its stdout. */
+export declare function createCommandRunner(command: string, exec?: ExecFileText, buildEnv?: (env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv): RunTextCommand;
+/** Runs `gh` and returns its stdout, with `CLICOLOR_FORCE` removed so `--json` output stays plain. */
 export declare const runGh: RunTextCommand;
 /** Runs `git` and returns its stdout. */
 export declare const runGit: RunTextCommand;

package/dist/gh-cli/exec.mjs

@@ -1,18 +1,20 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { ghSpawnEnv } from "./env.mjs";
 const execFileAsync = promisify(execFile);
 /**
  * Builds a `RunTextCommand` bound to a fixed binary. The default `exec` wraps `execFile` via
  * `promisify` so a test can inject a fake without spawning a real process; `runGh`/`runGit` below
- * are this factory applied to the two binaries this module cares about.
+ * are this factory applied to the two binaries this module cares about. `buildEnv` maps the
+ * parent environment to the one the child is spawned with (identity by default).
  */
-export function createCommandRunner(command, exec = (cmd, args) => execFileAsync(cmd, args)) {
+export function createCommandRunner(command, exec = (cmd, args, options) => execFileAsync(cmd, args, { ...options, encoding: 'utf8' }), buildEnv = (env) => env) {
     return async (args) => {
-        const { stdout } = await exec(command, args);
+        const { stdout } = await exec(command, args, { env: buildEnv(process.env) });
         return stdout;
     };
 }
-/** Runs `gh` and returns its stdout. */
-export const runGh = createCommandRunner('gh');
+/** Runs `gh` and returns its stdout, with `CLICOLOR_FORCE` removed so `--json` output stays plain. */
+export const runGh = createCommandRunner('gh', undefined, ghSpawnEnv);
 /** Runs `git` and returns its stdout. */
 export const runGit = createCommandRunner('git');

package/dist/gh-cli/index.d.mts

@@ -1,4 +1,5 @@
 export { createCommandRunner, runGh, runGit } from './exec.mts';
+export { ghSpawnEnv } from './env.mts';
 export type { ExecFileText, RunTextCommand } from './exec.mts';
 export { DiffCommandError, processDiffCommand } from './diff.mts';
 export type { DiffBlockCallback, DiffCommand } from './diff.mts';

package/dist/gh-cli/index.mjs

@@ -1,4 +1,5 @@
 export { createCommandRunner, runGh, runGit } from "./exec.mjs";
+export { ghSpawnEnv } from "./env.mjs";
 export { DiffCommandError, processDiffCommand } from "./diff.mjs";
 export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./body-length.mjs";
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./pr-create.mjs";

package/dist/gha-post-review/github.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { appendFileSync } from 'node:fs';
+import { ghSpawnEnv } from "../gh-cli/env.mjs";
 import { ReviewPayloadError } from "../gha-review-payload/index.mjs";
 import { readRegularReviewPayload } from "../gha-review-payload/index.mjs";
 import { createActionsClaudeTokenIo, withClaudeAppToken } from "./claude-token.mjs";
@@ -11,7 +12,7 @@ export function createGhExec(exec = execFileSync) {
     return (args, options) => exec('gh', [...args], {
         encoding: 'utf8',
         input: options?.input,
-        env: options?.env ?? process.env,
+        env: ghSpawnEnv(options?.env ?? process.env),
     }).trim();
 }
 export function writePostedOutput(posted, commentCount, outputPath = process.env.GITHUB_OUTPUT) {

package/dist/index.d.mts

@@ -8,8 +8,8 @@ export { runRetrospectiveFacts } from './retrospective-facts/index.mts';
 export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions, } from './retrospective-facts/index.mts';
 export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from './agent-blackboard/index.mts';
 export type { BlackboardConnection, SnapshotChecksum, SnapshotCleanupReceipt, SnapshotCleanupOptions, SnapshotCounts, SnapshotManifest, SnapshotPartition, SnapshotPartitionOptions, SnapshotPartitionResult, SnapshotSelection, } from './agent-blackboard/index.mts';
-export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mts';
-export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoader, JournalLoadResult, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './session-friction/index.mts';
+export { isConformingCiFailureBlock } from './audit-journal/ci-failures.mts';
+export type { JournalEntry, JournalLoader, JournalLoadResult } from './audit-journal/types.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
 export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
 export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
@@ -95,7 +95,7 @@ export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
 export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';
 export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from './vitest-diagnostics/index.mts';
 export type { DiagnosticReportLimitOptions, DiagnosticReportSummary, } from './vitest-diagnostics/index.mts';
-export { createCommandRunner, runGh, runGit } from './gh-cli/index.mts';
+export { createCommandRunner, ghSpawnEnv, runGh, runGit } from './gh-cli/index.mts';
 export type { ExecFileText, RunTextCommand } from './gh-cli/index.mts';
 export { DiffCommandError, processDiffCommand } from './gh-cli/index.mts';
 export type { DiffBlockCallback, DiffCommand } from './gh-cli/index.mts';

package/dist/index.mjs

@@ -4,7 +4,7 @@ export { HARNESS_IDS, inspectHarnessEnvironment, selectHarnessSession, } from ".
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from "./retrospective-transcript/index.mjs";
 export { runRetrospectiveFacts } from "./retrospective-facts/index.mjs";
 export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from "./agent-blackboard/index.mjs";
-export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from "./session-friction/index.mjs";
+export { isConformingCiFailureBlock } from "./audit-journal/ci-failures.mjs";
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from "./runner-port-policy/index.mjs";
 export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from "./sql-ast/index.mjs";
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from "./sql-scanner/index.mjs";
@@ -52,7 +52,7 @@ export { normalizeSwiftSource } from "./swift-semantic-equal/index.mjs";
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from "./swift-source-offset/index.mjs";
 export { validateResolvedPinDelta } from "./swift-resolved-pin-delta/index.mjs";
 export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from "./vitest-diagnostics/index.mjs";
-export { createCommandRunner, runGh, runGit } from "./gh-cli/index.mjs";
+export { createCommandRunner, ghSpawnEnv, runGh, runGit } from "./gh-cli/index.mjs";
 export { DiffCommandError, processDiffCommand } from "./gh-cli/index.mjs";
 export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./gh-cli/index.mjs";
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./gh-cli/index.mjs";

package/dist/mcp-server/context.d.mts

@@ -21,6 +21,8 @@ export type ToolContext = {
     runGit: RunTextCommand;
     /** Test seam: replaces locating and running gh. */
     runGh?: GhRunner;
+    /** The connected MCP client's `clientInfo.name`, once `initialize` has completed. */
+    clientName?: () => string | undefined;
     /** Test seam: replaces the operating system user and host name. */
     device?: () => {
         user: string;

package/dist/mcp-server/dispatch.d.mts

@@ -16,6 +16,8 @@ export type ServerEnvironment = {
     spawnPolicy?: PolicySpawner;
     /** Test seam: replaces locating and running gh. */
     runGh?: GhRunner;
+    /** The connected MCP client's `clientInfo.name`, once `initialize` has completed. */
+    clientName?: () => string | undefined;
     /** Test seam: replaces the operating system user and host name. */
     device?: () => {
         user: string;

package/dist/mcp-server/dispatch.mjs

@@ -67,6 +67,7 @@ export async function callTool(name, rawArguments, environment) {
             runGit: environment.runGit,
             snapshots: environment.snapshots ?? PROCESS_SNAPSHOTS,
             ...(environment.runGh === undefined ? {} : { runGh: environment.runGh }),
+            ...(environment.clientName === undefined ? {} : { clientName: environment.clientName }),
             ...(environment.device === undefined ? {} : { device: environment.device }),
             ...(environment.spawnPolicy === undefined ? {} : { spawnPolicy: environment.spawnPolicy }),
             // The client resolves from this package's install, like the SDK, never from the worktree.

package/dist/mcp-server/harness.test-helpers.d.mts

@@ -23,6 +23,7 @@ export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
         host: string;
     };
     snapshots?: SnapshotRegistry;
+    clientName?: () => string | undefined;
 }): Harness;
 export declare function textOf(result: ToolCallResult): string;
 export declare function jsonOf(result: ToolCallResult): Record<string, unknown>;

package/dist/mcp-server/harness.test-helpers.mjs

@@ -28,6 +28,7 @@ export function harness(fixture, options = {}) {
         ...(options.runGh === undefined ? {} : { runGh: options.runGh }),
         ...(options.device === undefined ? {} : { device: options.device }),
         ...(options.snapshots === undefined ? {} : { snapshots: options.snapshots }),
+        ...(options.clientName === undefined ? {} : { clientName: options.clientName }),
     };
     return { fake, call: (name, args) => callTool(name, args, environment) };
 }

package/dist/mcp-server/pr-agent.d.mts

@@ -0,0 +1,12 @@
+import { type HarnessId } from '../agent-harness-identity/index.mts';
+/**
+ * The harness that launched this server, from the launch environment first and the MCP client's
+ * `initialize` `clientInfo.name` second. Neither comes from a tool argument.
+ */
+export declare function deriveAgent(env: NodeJS.ProcessEnv, clientName?: string): HarnessId | undefined;
+/**
+ * The text of the `Agent:` line before the session. The agent is the derived harness; a caller
+ * `agent` that does not name it, or any `model`, is shown as caller-claimed and never replaces it.
+ * With nothing derivable the agent is `unknown`.
+ */
+export declare function agentLabel(derived: HarnessId | undefined, claimedAgent: string | undefined, claimedModel: string | undefined): string;

package/dist/mcp-server/pr-agent.mjs

@@ -0,0 +1,34 @@
+import { inspectHarnessEnvironment } from "../agent-harness-identity/index.mjs";
+const PRECEDENCE = ['codex', 'claude', 'cursor', 'grok'];
+/**
+ * The harness that launched this server, from the launch environment first and the MCP client's
+ * `initialize` `clientInfo.name` second. Neither comes from a tool argument.
+ */
+export function deriveAgent(env, clientName) {
+    const found = inspectHarnessEnvironment(env);
+    const present = {
+        codex: Boolean(found.codex.sessionId),
+        claude: found.claude.compatMode || Boolean(found.claude.sessionId),
+        cursor: found.cursor.agentMarker || Boolean(found.cursor.sessionId),
+        grok: found.grok.agentMarker || found.grok.hookEvent || Boolean(found.grok.sessionId),
+    };
+    const fromEnv = PRECEDENCE.find((id) => present[id]);
+    if (fromEnv !== undefined)
+        return fromEnv;
+    const name = clientName?.toLowerCase() ?? '';
+    return PRECEDENCE.find((id) => name.includes(id));
+}
+/**
+ * The text of the `Agent:` line before the session. The agent is the derived harness; a caller
+ * `agent` that does not name it, or any `model`, is shown as caller-claimed and never replaces it.
+ * With nothing derivable the agent is `unknown`.
+ */
+export function agentLabel(derived, claimedAgent, claimedModel) {
+    const notes = [];
+    const claim = claimedAgent?.trim();
+    if (claim && !(derived !== undefined && claim.toLowerCase().includes(derived)))
+        notes.push(`caller-claimed agent: ${claim}`);
+    if (claimedModel)
+        notes.push(`caller-claimed model: ${claimedModel}`);
+    return `${derived ?? 'unknown'}${notes.length ? ` (${notes.join('; ')})` : ''}`;
+}

package/dist/mcp-server/pr-body.d.mts

@@ -7,12 +7,14 @@ export type PullRequestProvenance = {
     host: string;
     /** The checkout label, see {@link worktreeLabel}. */
     worktree: string;
+    /** The Agent line text before the session, see `agentLabel`. */
+    agent: string;
 };
 /**
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
- * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
- * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
- * device and worktree facts.
+ * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
+ * the caller supplies the device and worktree facts.
  */
 export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance, noSourceStatement?: string): string;
 /**

package/dist/mcp-server/pr-body.mjs

@@ -1,7 +1,9 @@
 import { basename } from 'node:path';
+import { formatReferenceKey } from "../gh-cli/closing-refs.mjs";
 function relatedLine(issue) {
     const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
-    return `- ${verb} #${issue.number} — ${issue.reason}`;
+    const [owner, repo] = issue.repository?.split('/') ?? [];
+    return `- ${verb} ${formatReferenceKey({ number: issue.number, owner, repo })} — ${issue.reason}`;
 }
 /** The default no-source statement; a policy `renderNoSourceIssue` export may replace it. */
 function defaultNoSourceStatement(reason) {
@@ -9,19 +11,16 @@ function defaultNoSourceStatement(reason) {
 }
 /**
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
- * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
- * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
- * device and worktree facts.
+ * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
+ * the caller supplies the device and worktree facts.
  */
 export function renderPullRequestBody(input, provenance, noSourceStatement) {
-    const related = input.relatedIssues.length
-        ? input.relatedIssues.map(relatedLine)
-        : [
-            input.noSourceIssue === undefined
-                ? '- None'
-                : (noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason)),
-        ];
-    const agent = input.model === undefined ? input.agent : `${input.agent} (${input.model})`;
+    const related = input.relatedIssues.map(relatedLine);
+    if (input.noSourceIssue !== undefined)
+        related.push(noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason));
+    if (!related.length)
+        related.push('- None');
     return [
         '## Summary',
         '',
@@ -40,7 +39,7 @@ export function renderPullRequestBody(input, provenance, noSourceStatement) {
         input.details.join('\n\n'),
         '',
         `Workspace setup: ${input.workspaceSetup}`,
-        `Agent: ${agent} session ${provenance.sessionId}`,
+        `Agent: ${provenance.agent} session ${provenance.sessionId}`,
         `Device: ${provenance.user}@${provenance.host.toLowerCase()}`,
         `Worktree: ${provenance.worktree}`,
         '',

package/dist/mcp-server/pr-gh.mjs

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import { access, stat } from 'node:fs/promises';
 import { delimiter, isAbsolute, join } from 'node:path';
 import { promisify } from 'node:util';
+import { ghSpawnEnv } from "../gh-cli/env.mjs";
 const execFileAsync = promisify(execFile);
 const FALLBACKS = ['/opt/homebrew/bin/gh', '/usr/local/bin/gh', '/usr/bin/gh'];
 const MAX_BUFFER_BYTES = 16_000_000;
@@ -36,7 +37,7 @@ export async function locateGh(env, fallbacks = FALLBACKS) {
  * GH_REPO, which would point gh at a repository other than the validated worktree's.
  */
 export function ghEnvironment(env) {
-    const { AGENT_BLACKBOARD_URL: _url, AGENT_BLACKBOARD_TOKEN: _token, GH_REPO: _repo, ...rest } = env;
+    const { AGENT_BLACKBOARD_URL: _url, AGENT_BLACKBOARD_TOKEN: _token, GH_REPO: _repo, ...rest } = ghSpawnEnv(env);
     return rest;
 }
 /** A runner that locates gh once, on first use, from the server's environment. */

package/dist/mcp-server/pr-input.d.mts

@@ -4,19 +4,22 @@ export type RelatedIssue = {
     number: number;
     relation: 'closes' | 'refs';
     reason: string;
+    /** `owner/name` of a cross-repository issue (rendered lowercase); absent for this repository. */
+    repository?: string;
 };
 export type PullRequestInput = {
     title: string;
     summary: string;
     impact: string;
     relatedIssues: RelatedIssue[];
-    /** Set instead of relatedIssues when the pull request has no source issue. */
+    /** Declares no source issue; relatedIssues beside it must all be `refs`. */
     noSourceIssue?: {
         reason: string;
     };
     details: string[];
     base: string;
-    agent: string;
+    /** The caller's claim only; the rendered Agent line comes from `agentLabel`. */
+    agent?: string;
     model?: string;
     /** The trusted mode, see {@link trustedMode}; never the caller's word alone. */
     mode: PullRequestMode;

package/dist/mcp-server/pr-input.mjs

@@ -1,3 +1,4 @@
+import { hasClosingIssueReference } from "../gh-cli/closing-refs.mjs";
 import { optionalString, rejectUnknown, requireObject, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
 import { trustedMode } from "./pr-mode.mjs";
 const PR_MODES = ['interactive', 'autonomous'];
@@ -9,17 +10,30 @@ export function positiveInteger(value, label) {
         throw new Error(`${label} must be a positive integer`);
     return value;
 }
+// The owner is a GitHub login: alphanumerics and single hyphens, at most 39 characters.
+const REPOSITORY_RE = /^(?=[^/]{1,39}\/)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*\/[\w.-]+$/;
+function readRepository(issue, label) {
+    if (issue.repository === undefined)
+        return undefined;
+    // Not lowercased here: redaction runs on this value first, and rendering lowercases it.
+    const value = singleLine(issue, 'repository');
+    if (!REPOSITORY_RE.test(value))
+        throw new Error(`${label} must be a single owner/name`);
+    return value;
+}
 function readRelatedIssues(args) {
     const value = args.relatedIssues;
     if (!Array.isArray(value))
         throw new Error('relatedIssues is required and must be an array');
     return value.map((item, index) => {
         const issue = requireObject(item);
-        rejectUnknown(issue, ['number', 'relation', 'reason']);
+        rejectUnknown(issue, ['number', 'relation', 'reason', 'repository']);
+        const repository = readRepository(issue, `relatedIssues[${index}].repository`);
         return {
             number: positiveInteger(issue.number, `relatedIssues[${index}].number`),
             relation: requiredChoice(issue, 'relation', RELATIONS),
             reason: requiredString(issue, 'reason'),
+            ...(repository === undefined ? {} : { repository }),
         };
     });
 }
@@ -28,8 +42,12 @@ function readNoSourceIssue(args, related) {
         return undefined;
     const value = requireObject(args.noSourceIssue);
     rejectUnknown(value, ['reason']);
-    if (related.length)
-        throw new Error('noSourceIssue and a non-empty relatedIssues are mutually exclusive');
+    if (related.some((issue) => issue.relation === 'closes'))
+        throw new Error('noSourceIssue cannot be combined with a relatedIssues entry that closes');
+    related.forEach((issue, index) => {
+        if (hasClosingIssueReference(issue.reason))
+            throw new Error(`relatedIssues[${index}].reason must not contain a closing reference beside noSourceIssue`);
+    });
     return { reason: singleLine(value, 'reason') };
 }
 function readDetails(args) {
@@ -70,7 +88,7 @@ export function readPullRequestInput(args, env) {
         ...(noSourceIssue === undefined ? {} : { noSourceIssue }),
         details: readDetails(args),
         base: optionalString(args, 'base') ?? 'main',
-        agent: singleLine(args, 'agent'),
+        ...(args.agent === undefined ? {} : { agent: singleLine(args, 'agent') }),
         ...(model === undefined ? {} : { model }),
         mode: trustedMode(env, requested),
         // It renders on its own provenance line; a newline would forge the lines after it.

package/dist/mcp-server/pr-live.d.mts

@@ -2,6 +2,7 @@ import type { RunTextCommand } from '../gh-cli/exec.mts';
 export type LivePullRequest = {
     body: string;
     headRefName: string;
+    headRefOid: string;
     baseRefName: string;
     state: string;
 };

package/dist/mcp-server/pr-live.mjs

@@ -1,5 +1,5 @@
 import { findShepherdJournal } from "./pr-journal.mjs";
-const FIELDS = ['body', 'headRefName', 'baseRefName', 'state'];
+const FIELDS = ['body', 'headRefName', 'headRefOid', 'baseRefName', 'state'];
 /** The live pull request as gh reports it, whatever its state. */
 export async function readLivePullRequest(gh, pr) {
     const output = await gh(['pr', 'view', String(pr), '--json', FIELDS.join(',')]);

package/dist/mcp-server/pr-prepare.mjs

@@ -1,6 +1,7 @@
 import { hostname, userInfo } from 'node:os';
 import { validateGitHubBodyLength } from "../gh-cli/body-length.mjs";
 import { assertPolicyAllowed } from "./context.mjs";
+import { agentLabel, deriveAgent } from "./pr-agent.mjs";
 import { renderPullRequestBody, worktreeLabel } from "./pr-body.mjs";
 import { createGhRunner, ghEnvironment } from "./pr-gh.mjs";
 import { checkTitleLength, readPullRequestInput } from "./pr-input.mjs";
@@ -41,6 +42,20 @@ async function liveFor(kind, context, pr) {
         ? livePullRequest(ghIn(context), pr)
         : readLivePullRequest(ghIn(context), pr);
 }
+/**
+ * The head to validate. An update accepts the worktree branch, or an alias branch whose HEAD is
+ * the live head commit, and then uses the live head name; anything else is rejected.
+ */
+async function headFor(kind, git, live, pr, worktreeHead) {
+    if (worktreeHead === undefined)
+        return live.headRefName;
+    if (live === undefined || kind !== 'update' || live.headRefName === worktreeHead)
+        return worktreeHead;
+    const sha = (await git(['rev-parse', 'HEAD'])).trim();
+    if (sha !== live.headRefOid)
+        throw new Error(`pull request ${pr} has head ${live.headRefName} at ${live.headRefOid}, not the worktree branch ${worktreeHead} at ${sha}`);
+    return live.headRefName;
+}
 /** Renders the body, preserves the live journal for an update, and runs the policy validator. */
 export async function prepare(args, context, kind, pr) {
     assertPolicyAllowed(context);
@@ -53,14 +68,15 @@ export async function prepare(args, context, kind, pr) {
     const live = await liveFor(kind, context, pr);
     // A read-only validation of an existing pull request judges the head that pull request has.
     const worktreeHead = live !== undefined && kind === 'validate' ? undefined : await currentBranch(git);
-    const head = worktreeHead ?? live.headRefName;
+    // The local branch is checked before any diagnostic or alias resolution can echo or drop it.
+    if (worktreeHead !== undefined && secrets.some((secret) => worktreeHead.includes(secret)))
+        throw new Error('the worktree branch name contains a server credential: rename the branch');
+    const head = await headFor(kind, git, live, pr, worktreeHead);
     // Branch names are refs passed to gh as is: redacting one would name a branch that does not exist.
     if (secrets.some((secret) => head.includes(secret)))
         throw new Error('the worktree branch name contains a server credential: rename the branch');
     if (secrets.some((secret) => args.base?.includes(secret)))
         throw new Error('base contains a server credential: use another base branch');
-    if (live !== undefined && kind === 'update' && live.headRefName !== head)
-        throw new Error(`pull request ${pr} has head ${live.headRefName}, not the worktree branch ${head}`);
     const base = live === undefined
         ? given.base
         : liveBase(pr, live, redactCredentials(args.base, secrets));
@@ -70,7 +86,12 @@ export async function prepare(args, context, kind, pr) {
         throw new Error(`head branch ${head} must differ from base ${base}`);
     const device = (context.device ?? (() => ({ user: userInfo().username, host: hostname() })))();
     const statement = await noSourceStatement(policyFor(context), input);
-    let body = renderPullRequestBody(input, { sessionId: context.sessionId, ...device, worktree: await label(context, git) }, statement);
+    let body = renderPullRequestBody(input, {
+        sessionId: context.sessionId,
+        ...device,
+        worktree: await label(context, git),
+        agent: agentLabel(deriveAgent(context.env, context.clientName?.()), input.agent, input.model),
+    }, statement);
     if (live !== undefined)
         body = preserveShepherdJournal(body, live.body);
     body = redactCredentials(body, secrets);

package/dist/mcp-server/server.mjs

@@ -15,6 +15,7 @@ const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consu
  */
 export function createMcpServer(sdk, environment, version) {
     const mcp = new sdk.McpServer({ name: SERVER_NAME, version }, { instructions: INSTRUCTIONS });
+    environment.clientName ??= () => mcp.server.getClientVersion()?.name;
     mcp.server.registerCapabilities({ tools: {} });
     mcp.server.setRequestHandler(sdk.ListToolsRequestSchema, async () => ({ tools: [...TOOLS] }));
     mcp.server.setRequestHandler(sdk.CallToolRequestSchema, async (request) => callTool(request.params.name, request.params.arguments, environment));

package/dist/mcp-server/tools-pr.mjs

@@ -12,14 +12,20 @@ const FIELDS = {
     impact: text('Who or what is affected, as markdown.'),
     relatedIssues: {
         type: 'array',
-        description: 'Issues this pull request closes or refs. Empty when it has none; with no source issue ' +
-            'at all, give noSourceIssue as well (it is rejected beside a non-empty list).',
+        description: 'Issues this pull request closes or refs. Empty when it has none; with no source issue, ' +
+            'give noSourceIssue as well (beside a non-empty list every entry must be refs).',
         items: {
             type: 'object',
             properties: {
                 number: { type: 'integer', minimum: 1 },
                 relation: { enum: ['closes', 'refs'] },
                 reason: text('Why the issue is related.'),
+                repository: {
+                    type: 'string',
+                    pattern: '^(?=[^/]{1,39}/)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*/[\\w.-]+$',
+                    description: 'Optional owner/name (lowercased) of the issue repository, rendered as ' +
+                        'owner/name#N; omit for an issue in this repository. Allowed for closes and refs.',
+                },
             },
             required: ['number', 'relation', 'reason'],
             additionalProperties: false,
@@ -27,9 +33,10 @@ const FIELDS = {
     },
     noSourceIssue: {
         type: 'object',
-        description: 'Declares a pull request with no source issue, mutually exclusive with a non-empty ' +
-            'relatedIssues. Rendered inside Related issues (the policy may supply the wording) and ' +
-            'passed to the policy, which may allow it only in interactive mode.',
+        description: 'Declares a pull request with no source issue; rejected beside a closes relatedIssues ' +
+            'entry, allowed beside refs-only ones. Rendered inside Related issues after any Refs ' +
+            'lines (the policy may supply the wording) and passed to the policy, which may allow it ' +
+            'only in interactive mode.',
         properties: { reason: text('Single-line reason there is no source issue.') },
         required: ['reason'],
         additionalProperties: false,
@@ -41,8 +48,12 @@ const FIELDS = {
         description: 'Markdown paragraphs or bullets, joined by blank lines.',
     },
     base: { type: 'string', minLength: 1, description: 'Base branch. Default: main.' },
-    agent: text('Agent name for the Agent line.'),
-    model: text('Optional model name, rendered in parentheses after the agent.'),
+    agent: text('Optional, and never trusted. The server derives the Agent line from its own launch ' +
+        'environment (harness markers) and the MCP client name; a value that does not name the ' +
+        'derived agent is rendered as "caller-claimed", and with nothing derivable the agent is ' +
+        '"unknown".'),
+    model: text('Optional, and never trusted. The server cannot derive the model, so it is rendered as ' +
+        '"caller-claimed model: <model>" in parentheses after the agent.'),
     mode: {
         enum: ['interactive', 'autonomous'],
         description: 'Optional. The server derives the mode from its own launch environment and fails closed: ' +
@@ -51,15 +62,7 @@ const FIELDS = {
     },
     workspaceSetup: text('Text for the Workspace setup line, such as how the worktree was prepared.'),
 };
-const REQUIRED = [
-    'title',
-    'summary',
-    'impact',
-    'relatedIssues',
-    'details',
-    'agent',
-    'workspaceSetup',
-];
+const REQUIRED = ['title', 'summary', 'impact', 'relatedIssues', 'details', 'workspaceSetup'];
 const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
     'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
     'policy validatePullRequest export in a child process; the head branch is the ' +
@@ -79,7 +82,7 @@ export const PR_TOOLS = [
         "repository's stack tooling. Returns { number, url, warnings }.", openWorld(ADDITIVE), FIELDS, REQUIRED),
     tool('pr_update', "Replaces an open pull request's title and body. " +
         RENDERING +
-        "The pull request's head branch must be the worktree branch. The live Shepherd Journal is " +
+        "The pull request's head must be the worktree branch, or the worktree HEAD must be the pull request's head commit (an alias branch); the live head name is then used. The live Shepherd Journal is " +
         'preserved and nothing else is carried over from the live body. Validation errors block ' +
         'the update. Returns { number, url, warnings }.', openWorld(MUTATING), { ...FIELDS, pr: PR_NUMBER }, [...REQUIRED, 'pr']),
 ];

package/dist/{session-friction → private-files}/lock.mjs

@@ -131,6 +131,7 @@ function removeStaleLock(lockPath) {
             return true;
         }
         catch {
+            /* v8 ignore next -- requires an unexpected filesystem failure during stale-lock recovery. */
             return false;
         }
     });
@@ -174,7 +175,7 @@ export function withFileLock(path, action) {
                 throw statusError;
             }
             if (!lockStatus.isFile())
-                throw new Error('session-friction log lock must be a regular file');
+                throw new Error('log lock must be a regular file');
             if (removeStaleLock(lockPath))
                 continue;
             waitForLock();
@@ -189,5 +190,5 @@ export function withFileLock(path, action) {
             unlinkSync(lockPath);
         }
     }
-    throw new Error(`could not acquire session-friction log lock for ${basename(path)}`);
+    throw new Error(`could not acquire file lock for ${basename(path)}`);
 }

package/dist/private-files/log-file.d.mts

@@ -0,0 +1,3 @@
+export declare function openLogFile(path: string, flags: number): number;
+export declare function readLogContent(descriptor: number, maximumBytes: number): string;
+export declare function writeAll(descriptor: number, value: string): void;