vouchington-tooling 0.45.0 → 0.46.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,6 +7,8 @@ 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

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

@@ -21,7 +21,6 @@ export function renderPullRequestBody(input, provenance, noSourceStatement) {
                 ? '- None'
                 : (noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason)),
         ];
-    const agent = input.model === undefined ? input.agent : `${input.agent} (${input.model})`;
     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

@@ -16,7 +16,8 @@ export type PullRequestInput = {
     };
     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

@@ -70,7 +70,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

@@ -41,8 +41,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 +55,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 +75,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;

package/dist/private-files/log-file.mjs

@@ -0,0 +1,53 @@
+import { closeSync, constants, fstatSync, openSync, readSync, writeSync } from 'node:fs';
+import { decodeUtf8 } from "./utf8.mjs";
+export function openLogFile(path, flags) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ELOOP' || error.code === 'EISDIR' || error.code === 'ENOTDIR'))
+            throw new Error('log file must be a regular file');
+        throw error;
+    }
+    try {
+        const status = fstatSync(descriptor);
+        if (!status.isFile() || status.nlink !== 1)
+            throw new Error('log file must be a regular file');
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+export function readLogContent(descriptor, maximumBytes) {
+    if (fstatSync(descriptor).size > maximumBytes)
+        throw new Error('log file is too large');
+    const buffer = Buffer.alloc(maximumBytes + 1);
+    let length = 0;
+    while (length < buffer.length) {
+        const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
+        if (bytes === 0)
+            break;
+        length += bytes;
+    }
+    /* v8 ignore next -- detects external growth after the descriptor size check. */
+    if (length > maximumBytes)
+        throw new Error('log file is too large');
+    return decodeUtf8(buffer.subarray(0, length));
+}
+export function writeAll(descriptor, value) {
+    const buffer = Buffer.from(value);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const written = writeSync(descriptor, buffer, offset, buffer.length - offset);
+        /* v8 ignore next -- a zero-byte synchronous file write is an external I/O failure. */
+        if (written === 0)
+            throw new Error('log file write made no progress');
+        offset += written;
+    }
+}

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

@@ -3,6 +3,6 @@ export function decodeUtf8(value) {
         return new TextDecoder('utf-8', { fatal: true }).decode(value);
     }
     catch {
-        throw new Error('session-friction log is not valid UTF-8');
+        throw new Error('log file is not valid UTF-8');
     }
 }

package/dist/retrospective-facts/exec.mjs

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
+import { ghSpawnEnv } from "../gh-cli/env.mjs";
 export const shell = (command, args) => new Promise((resolve) => {
-    const child = spawn(command, args);
+    const child = command === 'gh' ? spawn(command, args, { env: ghSpawnEnv() }) : spawn(command, args);
     let stdout = '';
     let stderr = '';
     child.stdout.setEncoding('utf8');

package/docs/mcp-server.md

@@ -287,7 +287,7 @@ retrospective tools. All three take `sessionId` (required) and `worktree` (optio
 launched inside a repository worktree (they run the checkout policy), and share this structured
 input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
 (`[{ number, relation: "closes" | "refs", reason }]`, may be empty), optional `noSourceIssue`
-(`{ reason }`, see below), `details` (string array), `base` (default `main`), `agent`, optional
+(`{ reason }`, see below), `details` (string array), `base` (default `main`), optional `agent`, optional
 `model`, optional `mode` (`interactive` | `autonomous`) and `workspaceSetup`. `pr_update` also
 requires `pr`; `pr_validate` accepts an optional `pr`.
 
@@ -305,6 +305,18 @@ argument can only narrow `interactive` to `autonomous` (it never widens), so an
 cannot unlock an interactive-only policy exception. The policy child receives no env markers, so it
 relies on this value.
 
+### Agent provenance
+
+The `Agent:` line is derived by the server, never taken from the caller. The agent is the harness
+that launched the server: `CODEX_THREAD_ID` (codex), `CLAUDECODE=1` or `CLAUDE_CODE_SESSION_ID`
+(claude), `CURSOR_AGENT` or `CURSOR_SESSION_ID` (cursor), `GROK_AGENT`, `GROK_HOOK_EVENT` or
+`GROK_SESSION_ID` (grok), in that order; failing those, the MCP client's `initialize`
+`clientInfo.name` when it contains one of those names. The server has no source for the model.
+`agent` is optional: a value naming the derived agent is ignored, any other value is rendered as
+`(caller-claimed agent: <value>)`, and `model` as `(caller-claimed model: <value>)`. When no agent
+is derivable the line says `unknown`. Making `agent` optional is compatible with existing callers,
+which may keep sending it.
+
 ### Pull requests with no source issue
 
 Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`; a non-empty
@@ -335,7 +347,7 @@ rule) and `pullRequestDefaults`.
 <details joined by blank lines>
 
 Workspace setup: <workspaceSetup>
-Agent: <agent>[ (<model>)] session <sessionId>
+Agent: <derived agent | unknown>[ (caller-claimed ...)] session <sessionId>
 Device: <os user>@<lowercased hostname>
 Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
 ```
@@ -357,8 +369,10 @@ with the repository's stack tooling instead.
   and `project`. It checks the head is pushed and current, writes the body to a mode 0600 temp file
   (removed afterwards) and runs `gh pr create --draft` with the labels, `--milestone` and
   `--project`. Returns `{ number, url, warnings }`.
-- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,baseRefName,state`,
-  rejects a pull request that is not `OPEN` or whose head is not the worktree branch, and validates
+- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,headRefOid,baseRefName,state`,
+  rejects a pull request that is not `OPEN` or whose head is neither the worktree branch nor the
+  worktree `HEAD` commit (an alias branch at the live head SHA is accepted and the live head name is
+  used), and validates
   against the live base (an explicit `base` must equal it). It renders, appends the live Shepherd
   Journal (a `<details><summary>Shepherd Journal</summary>` block, or a legacy `## Shepherd Journal`
   section to the next H2 or the end; examples in fenced code blocks are ignored), validates with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -71,11 +71,6 @@
       "default": "./dist/agent-blackboard/index.mjs"
     },
     "./mcp-server/bin": "./bin/vouchington-mcp.mjs",
-    "./session-friction": {
-      "types": "./dist/session-friction/index.d.mts",
-      "import": "./dist/session-friction/index.mjs",
-      "default": "./dist/session-friction/index.mjs"
-    },
     "./sql-ast": {
       "types": "./dist/sql-ast/index.d.mts",
       "import": "./dist/sql-ast/index.mjs",

package/dist/session-friction/ci-failures.d.mts

@@ -1,13 +0,0 @@
-import type { FrictionLogReadResult, JournalEntry } from './types.mts';
-import { type AuditRedactor } from './text.mts';
-export declare function isConformingCiFailureBlock(markdown: string): boolean;
-export declare function getConformingGroups(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
-export declare function incompleteCiSection(markdownBlocks: string[]): string;
-export declare function buildCiFailuresSection(sessionId: string, journal: {
-    status: 'ok';
-    markdownBlocks: string[];
-    truncated: boolean;
-} | {
-    status: 'unreachable';
-    diagnostic: string;
-}, frictionStatus: FrictionLogReadResult['status'] | 'journal-only'): string;

package/dist/session-friction/classify.d.mts

@@ -1,2 +0,0 @@
-import type { FrictionEvent, FrictionObservation } from './types.mts';
-export declare function classifyFrictionObservation(observation: FrictionObservation): Omit<FrictionEvent, 'timestamp'> | null;