dorfl 0.0.0 → 0.1.1

package/src/harness.ts

@@ -0,0 +1,355 @@
+import {spawnSync} from 'node:child_process';
+
+/**
+ * The **harness seam** (ADR §5): how a job's command is launched and how its
+ * liveness is observed is pluggable behind an adapter; the core never hard-codes
+ * a specific tool.
+ *
+ * Crucially, **liveness is reported by the harness, NOT inferred from filesystem
+ * mtime**: a live agent can think for minutes without writing any files, so
+ * mtime would mistake a thinking agent for a dead one. Adapters answer liveness
+ * from the real signal (the PID, a session handle, …) — never mtime.
+ *
+ * This task ships the **null adapter** (records a PID, runs a configured
+ * command) so the substrate is testable standalone. The first real target (the
+ * `pi` adapter: liveness via PID + a pointer to the pi session dir/log,
+ * invocation via the pi CLI) is its own task.
+ */
+
+/**
+ * The persisted harness block in a job's `.dorfl-job.json` record. It
+ * captures which adapter launched the job + the liveness pointer the adapter
+ * needs to answer `isAlive` later (so `gc`/`status` can re-derive liveness from
+ * a fresh process without re-launching). Adapter-specific fields are optional.
+ */
+export interface HarnessRecord {
+	/** Which harness adapter owns this job (`null`, later `pi`, …). */
+	adapter: string;
+	/** OS process id of the launched command (the liveness anchor). */
+	pid?: number;
+	/** The command the adapter ran (for audit / re-launch). */
+	command?: string;
+	/** Adapter-specific session pointer (e.g. the pi session dir/log path). */
+	session?: string;
+}
+
+/** What a harness needs to launch one job's command. */
+export interface LaunchInput {
+	/** The job's working directory (the worktree) — the command runs here. */
+	dir: string;
+	/** The slug being processed (for adapters that name/log per slug). */
+	slug: string;
+	/** The command to run (e.g. the configured `agentCmd`). */
+	command: string;
+	/** Optional prompt fed on the command's stdin. */
+	prompt?: string;
+	/**
+	 * The model the agent should run on (the harness-agnostic routing intent, ADR
+	 * §13). `undefined` ⇒ dorfl forces no model. The ADAPTER decides HOW
+	 * this reaches its tool: the pi adapter passes `--model <model>` natively; the
+	 * null/shell adapter substitutes a `{model}` placeholder in `command` (see
+	 * {@link substituteModel}). auth/keys are NEVER carried here — they stay the
+	 * harness's job.
+	 */
+	model?: string;
+	/**
+	 * The full pi session-FILE path the adapter passes as `--session <path>` (the
+	 * caller generates it ONCE — before launch, so the `do --watch` tailer can tail
+	 * the KNOWN path — via {@link generateSessionPath} from the resolved
+	 * `sessionsDir` + cwd). Adapter-agnostic: the pi adapter uses it verbatim and
+	 * records it in `PiHarnessRecord.session`; the null/shell adapter ignores it.
+	 * `undefined` ⇒ the pi adapter falls back to a generated default for its cwd.
+	 */
+	session?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * What a harness needs to launch one item's harness INTERACTIVELY (task
+ * `agent-interactive-launch`): a FOREGROUND human session in `dir`, inherited
+ * stdio, NO prepared prompt. This is the OPPOSITE shape to {@link LaunchInput}
+ * (which feeds a prompt on stdin and captures output for the autonomous path):
+ * here the human drives the agent, so there is nothing to feed and nothing to
+ * capture. A NEW seam intent, NOT a flag on {@link Harness.launch} (decision #1):
+ * `launch` is fundamentally spawnSync + prompt-on-stdin + capture-output, and a
+ * boolean would make its `LaunchResult` lie.
+ */
+export interface InteractiveLaunchInput {
+	/** The onboarded working tree to start the session in (the command runs here). */
+	dir: string;
+	/** The slug being worked on (for adapters that name/log per slug). */
+	slug: string;
+	/**
+	 * The resolved model the human starts pinned to (ADR §13 routing: flag > env
+	 * > per-repo > global). `undefined` ⇒ no model forced. The pi adapter passes
+	 * `--model <model>`; the human may still switch models inside the session.
+	 */
+	model?: string;
+	/**
+	 * The full pi session-FILE path passed as `--session <path>` so the human
+	 * session is still recorded/visible (audit trail + the pi dashboard, decision
+	 * #2). `undefined` ⇒ the pi adapter generates a default for `dir`.
+	 */
+	session?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The result of an interactive launch — there is NOTHING to capture (the human
+ * drove a foreground session; no prepared prompt, no piped output, no PID record
+ * to persist; it is NOT a tracked job, decision #3). The only useful signal is
+ * the harness's exit code, returned here. Callers may ignore it.
+ */
+export interface InteractiveLaunchResult {
+	/** The harness process's exit code (0 = clean exit). */
+	exitCode: number;
+}
+
+/**
+ * What the human-face verbs (`start`/`work-on`) hand a launcher: just the
+ * onboarded WORKING TREE + the slug + env. The model + the pi `--session` path
+ * are resolved at the CLI boundary (where config lives) and BOUND INTO the
+ * injected closure, so the git-logic modules stay decoupled from `createHarness`
+ * / config resolution. The CLI's closure calls
+ * {@link Harness.launchInteractive} with the resolved model/session.
+ */
+export interface InteractiveLaunchSite {
+	/** The slug being worked on. */
+	slug: string;
+	/** The onboarded working tree to start the foreground session in. */
+	dir: string;
+	/** Environment for the launched harness process. */
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The injectable interactive launcher the human-face verbs call AFTER
+ * onboarding. The CLI binds the resolved harness + model + sessions-dir into it;
+ * tests inject a spy. A thin seam so `start.ts`/`work-on.ts` never import
+ * `createHarness` or resolve config.
+ */
+export type InteractiveLauncher = (site: InteractiveLaunchSite) => void;
+
+/** The `{model}` placeholder the null/shell adapter substitutes in `agentCmd`. */
+export const MODEL_PLACEHOLDER = '{model}';
+
+/**
+ * Inject the model ROUTING intent (ADR §13) into a shell `command` for the
+ * null/shell adapter, with three degradation rules so model routing is OFFERED,
+ * never FORCED:
+ *
+ *  1. `{model}` present + `model` set ⇒ substitute every occurrence.
+ *  2. `{model}` present + `model` unset ⇒ a clear config error (we never emit a
+ *     literal `{model}` to the shell — that would silently misroute).
+ *  3. `{model}` absent ⇒ return `command` as-is (a user who bakes the model into
+ *     `agentCmd`, or relies on the harness's own default, is untouched).
+ *
+ * dorfl only moves the model INTENT; auth/keys stay the harness's job.
+ */
+export function substituteModel(
+	command: string,
+	model: string | undefined,
+): string {
+	if (!command.includes(MODEL_PLACEHOLDER)) {
+		return command; // rule 3: no placeholder ⇒ run as-is.
+	}
+	if (model === undefined || model === '') {
+		throw new Error(
+			`agentCmd contains a ${MODEL_PLACEHOLDER} placeholder but no model is ` +
+				`configured. Set a model (--model, DORFL_MODEL, per-repo, or ` +
+				`global config) or remove ${MODEL_PLACEHOLDER} from agentCmd.`,
+		);
+	}
+	return command.split(MODEL_PLACEHOLDER).join(model); // rule 1: substitute.
+}
+
+export interface LaunchResult {
+	/** True iff the launched command completed successfully. */
+	ok: boolean;
+	/** The harness block to persist in the job record (PID, command, …). */
+	record: HarnessRecord;
+	/** Failure detail when `ok` is false (the stderr/failure channel). */
+	detail?: string;
+	/**
+	 * The agent's final ANSWER (task `harness-agent-output`): the concatenated
+	 * `text` of the LAST assistant turn the invocation produced. This is the
+	 * channel for the agent's OUTPUT on success — DISTINCT from {@link detail},
+	 * which is the failure/`stderr` channel. `undefined` when the invocation
+	 * produced no parseable assistant text.
+	 *
+	 * Per-adapter EXTRACTION from each tool's native channel (Option C, decided
+	 * 2026-06-06): pi reads the last assistant message from the session `.jsonl`
+	 * it wrote (via `watch-session.ts`'s shared reader); the null/shell adapter
+	 * returns its captured (synchronous) command stdout. The forward-contract for
+	 * an opencode adapter (not built yet) is to take the last assistant `text`
+	 * part from its `--format json` stream — the SAME `output` field.
+	 */
+	output?: string;
+}
+
+/**
+ * The harness seam. `launch` starts the job's command + returns the record (with
+ * the liveness anchor); `isAlive` answers liveness FROM THE HARNESS (PID/session
+ * — never mtime, ADR §5).
+ */
+export interface Harness {
+	/** A stable adapter name (`null`, `pi`, …) stamped into the record. */
+	readonly adapter: string;
+	/** Launch the job's command; record the PID + liveness pointer. */
+	launch(input: LaunchInput): LaunchResult;
+	/**
+	 * Launch the harness INTERACTIVELY (task `agent-interactive-launch`): a
+	 * FOREGROUND human session in `input.dir` with INHERITED stdio and NO prepared
+	 * prompt — the human drives it, and control returns when they exit. This is
+	 * the human-facing counterpart to the autonomous {@link launch}; it is NOT a
+	 * tracked job (no `.dorfl-job.json`, no PID/liveness record, no gate,
+	 * decision #3), so it returns only an exit code. pi-only: the null adapter
+	 * throws a clear pi-only error (decision #2).
+	 */
+	launchInteractive(input: InteractiveLaunchInput): InteractiveLaunchResult;
+	/** Is the job still alive? Answered from the record's anchor, NOT mtime. */
+	isAlive(record: HarnessRecord): boolean;
+}
+
+/**
+ * Is this `spawnSync.error` a BENIGN failure of the prompt write, safe to
+ * ignore? The null/shell adapter feeds `input.prompt` to the child on stdin
+ * (`spawnSync('bash', …, {input})`). When the prompt is EMPTY — the autonomous
+ * review/arbiter launches that just shell out and capture stdout — a child that
+ * closes its stdin before the parent's (zero-byte) write surfaces as `EPIPE`
+ * under concurrent test load. That write failing is harmless: there was nothing
+ * to deliver, and the child's stdout/exit status are still captured normally.
+ * So we treat ONLY `EPIPE` as benign and let every OTHER spawn error (`ENOENT`,
+ * `EACCES`, buffer overflow, …) throw — those are real launch failures.
+ */
+export function isBenignPromptWriteError(error: Error): boolean {
+	return (error as NodeJS.ErrnoException).code === 'EPIPE';
+}
+
+/**
+ * The **null adapter**: runs the configured command synchronously to completion
+ * in the job dir, recording the PID. Liveness is `process.kill(pid, 0)` against
+ * the recorded PID (the OS process table) — explicitly NOT a file mtime. Because
+ * it runs synchronously, the process has already exited by the time `launch`
+ * returns, so a finished job reads as not-alive (which is correct).
+ */
+export class NullHarness implements Harness {
+	readonly adapter = 'null';
+
+	launch(input: LaunchInput): LaunchResult {
+		// BACKSTOP (config error, NOT a spawn failure): an empty/whitespace command
+		// resolves the null adapter to `bash -c ''`, which exits 0 with no output — a
+		// "successful" build that ran NOTHING. The `do`/`run`/`--remote` CLI sites
+		// already refuse this up-front (doNeedsAgentCmd), but THIS seam can be reached
+		// by other callers (tests, embeddings, future paths), so it must refuse too.
+		// Distinct from the `result.error` spawn-failure throw below: this names the
+		// config cause + the fix, in the voice of `launchInteractive`/`substituteModel`.
+		if (input.command.trim() === '') {
+			throw new Error(
+				'no command to run: the null/shell adapter was launched with an empty ' +
+					'agentCmd — nothing would run. Set `agentCmd` (--agent-cmd, per-repo, or ' +
+					'global config) or configure `harness: pi`.',
+			);
+		}
+		// Inject the model routing intent into the shell command via the `{model}`
+		// placeholder (ADR §13) — offered, never forced (see substituteModel).
+		const command = substituteModel(input.command, input.model);
+		const result = spawnSync('bash', ['-c', command], {
+			cwd: input.dir,
+			encoding: 'utf8',
+			input: input.prompt,
+			env: input.env ?? process.env,
+			maxBuffer: 64 * 1024 * 1024,
+		});
+		if (result.error && !isBenignPromptWriteError(result.error)) {
+			throw new Error(
+				`failed to spawn harness command: ${result.error.message}`,
+			);
+		}
+		// Record the CHILD's PID (the liveness anchor) — not the runner's. The null
+		// adapter runs synchronously, so by the time we return the child has
+		// exited, and `isAlive` correctly reads it as not-alive (from the PID
+		// table, NOT a file mtime).
+		const record: HarnessRecord = {
+			adapter: this.adapter,
+			pid: result.pid,
+			command,
+		};
+		const status = result.status ?? -1;
+		// The null/shell adapter's OUTPUT is its captured stdout (trimmed): a
+		// synchronous spawn, so there is no stream-fragility caveat — the command's
+		// stdout IS its answer. `undefined` when empty (no answer to surface).
+		const stdout = (result.stdout ?? '').trim();
+		return {
+			ok: status === 0,
+			record,
+			detail: status === 0 ? undefined : (result.stderr ?? '').trim(),
+			output: stdout === '' ? undefined : stdout,
+		};
+	}
+
+	/**
+	 * Interactive launch is NOT supported by the null/shell adapter (decision #2):
+	 * its `agentCmd` is shaped for the captured, prompt-fed AUTONOMOUS path, so
+	 * "interactive" has no clean meaning here. Throw a CLEAR pi-only error
+	 * (mirroring `do --watch`'s fail-on-null decision) rather than silently
+	 * shelling out the wrong way.
+	 */
+	launchInteractive(_input: InteractiveLaunchInput): InteractiveLaunchResult {
+		throw new Error(
+			'interactive launch requires the pi harness; configure `harness: pi` ' +
+				'(the null/shell adapter only supports the captured autonomous launch).',
+		);
+	}
+
+	isAlive(record: HarnessRecord): boolean {
+		return pidAlive(record.pid);
+	}
+}
+
+/**
+ * Resolve the harness adapter that OWNS a given job record, keyed off the
+ * record's `adapter` field. The core (`status`, `watch`, `gc`) reads liveness
+ * for a heterogeneous set of jobs (some null, some pi) from their persisted
+ * records, so it must ask the RIGHT adapter per job — a pi job's liveness is the
+ * pi adapter's responsibility (PID + session pointer), not the null adapter's.
+ *
+ * Adapters register here lazily via {@link registerHarness}; an unknown adapter
+ * falls back to the null adapter (PID-only liveness — never mtime), which is a
+ * safe superset for any PID-anchored record.
+ */
+export function resolveHarness(record: HarnessRecord): Harness {
+	return HARNESS_REGISTRY.get(record.adapter) ?? FALLBACK_HARNESS;
+}
+
+/**
+ * Register a harness adapter under its `adapter` name so {@link resolveHarness}
+ * can dispatch liveness to it. Idempotent (last registration wins). The pi
+ * adapter registers itself on import; tests may register stubs.
+ */
+export function registerHarness(harness: Harness): void {
+	HARNESS_REGISTRY.set(harness.adapter, harness);
+}
+
+const FALLBACK_HARNESS = new NullHarness();
+const HARNESS_REGISTRY = new Map<string, Harness>([
+	[FALLBACK_HARNESS.adapter, FALLBACK_HARNESS],
+]);
+
+/**
+ * Is `pid` a live process? Uses signal 0 (`process.kill(pid, 0)`), which checks
+ * for existence/permission WITHOUT delivering a signal — the OS process table,
+ * never a filesystem mtime. Unknown/undefined PID ⇒ not alive.
+ */
+export function pidAlive(pid: number | undefined): boolean {
+	if (pid === undefined || pid <= 0) {
+		return false;
+	}
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		// EPERM means the process exists but we may not signal it ⇒ still alive.
+		return (err as NodeJS.ErrnoException).code === 'EPERM';
+	}
+}

package/src/identity.ts

@@ -0,0 +1,322 @@
+/**
+ * The **identity** feature: run the runner's git + provider operations as a
+ * configured entity (a bot), without mutating the user's global git/`gh` config.
+ *
+ * The mechanism is process-scoped environment overrides on the child processes
+ * the runner spawns (`git`, `gh`) — never a global mutation. So if the runner
+ * crashes mid-run the user's machine is untouched, and an absent identity is
+ * byte-for-byte today's ambient behaviour.
+ *
+ * # The three axes (keep these distinct — they are different concerns)
+ *
+ *   1. **commit label** (`name` / `email`) — the git author/committer strings
+ *      stamped into the commit object. These are NOT authenticated: git never
+ *      checks them against anything. Driven by `GIT_CONFIG_PARAMETERS`.
+ *   2. **git transport auth** (`auth`) — WHO pushes. Per-transport policy: an
+ *      SSH key (or ambient ssh) drives `GIT_SSH_COMMAND`; HTTPS uses the ambient
+ *      credential. This is the substrate concern — meaningful with NO provider.
+ *   3. **provider API auth** (`providers.github`) — WHO opens the PR / posts the
+ *      comment, via `GH_TOKEN`. NEVER used as a git credential (git is SSH-first;
+ *      GitHub is an additive layer). Optional: absent ⇒ `gh` degrades.
+ *
+ * The three axes SHOULD point at the same entity for a coherent bot (the token's
+ * GitHub account should be the account the SSH key is registered to), but nothing
+ * can verify that automatically — it is a documented coherence note, not a check.
+ *
+ * # Why `auth` is mandatory-explicit (no silent omission)
+ *
+ * `auth.ssh` and `auth.https` are BOTH required, each an explicit small union, so
+ * the dangerous "I set a bot provider token but left git auth ambient — and my
+ * remote is HTTPS, so I silently push as the human" misconfig is UNSPELLABLE by
+ * accident: pushing over ambient HTTPS requires literally writing
+ * `https: "ambient"`. A bot setup naturally writes `https: "never"`, which makes
+ * the leak a hard push-time failure instead of a silent wrong-account push.
+ */
+
+/** The conventional `agents.alt` TLD never resolves to a real account (deliberate). */
+export const DEFAULT_IDENTITY_NAME = 'dorfl';
+export const DEFAULT_IDENTITY_EMAIL = 'dorfl@agents.alt';
+
+/**
+ * Per-transport git-auth policy for SSH. A filesystem path PINS that key
+ * (`GIT_SSH_COMMAND -i <path>`); `"ambient"` lets ssh-agent / `~/.ssh/config`
+ * resolve the key; `"never"` FORBIDS the SSH transport (a hard push-time failure
+ * if the arbiter is an SSH remote). A `union of more` later (e.g. host options).
+ */
+export type SshAuth = string | 'ambient' | 'never';
+
+/**
+ * Per-transport git-auth policy for HTTPS. `"ambient"` uses whatever HTTPS
+ * credential the environment supplies (credential helper / cached PAT — e.g. the
+ * CI `actions/checkout` token); `"never"` FORBIDS the HTTPS transport (a hard
+ * push-time failure if the arbiter is an HTTPS remote). A token-pin member (the
+ * explicit HTTPS-push credential, distinct from the provider token) is a planned
+ * future addition — keep this a union so it grows without churn.
+ */
+export type HttpsAuth = 'ambient' | 'never';
+
+/** Git TRANSPORT auth — both transports stated, no silent-omission state. */
+export interface GitAuth {
+	/** Policy for SSH pushes: a key path, `"ambient"`, or `"never"`. */
+	ssh: SshAuth;
+	/** Policy for HTTPS pushes: `"ambient"` or `"never"`. */
+	https: HttpsAuth;
+}
+
+/** Provider API auth — the `gh` token, by literal value OR an env-var name. */
+export type GitHubProviderAuth = {token: string} | {tokenEnv: string};
+
+/** The optional, pluggable review-request providers (matches `ProviderName`). */
+export interface IdentityProviders {
+	/** GitHub provider API auth (`gh`). Absent ⇒ `gh` runs unauthenticated. */
+	github?: GitHubProviderAuth;
+}
+
+/**
+ * A configured runner identity (a bot). The WHOLE block is optional — absent ⇒
+ * fully ambient (today's behaviour, byte-for-byte). When present, `auth` is
+ * MANDATORY (both transports stated); `name`/`email` default in; `providers` is
+ * optional. HOST-ONLY: rejected in a per-repo `.dorfl.json` (it carries
+ * secrets and is per-machine), so it lives only in the global config.
+ */
+export interface Identity {
+	/** Commit author/committer LABEL. Default {@link DEFAULT_IDENTITY_NAME}. */
+	name?: string;
+	/** Commit author/committer LABEL. Default {@link DEFAULT_IDENTITY_EMAIL}. */
+	email?: string;
+	/** Git transport auth (mandatory when identity present). */
+	auth: GitAuth;
+	/** Optional pluggable providers (GitHub today). */
+	providers?: IdentityProviders;
+}
+
+/** Which transport an arbiter remote URL pushes over. */
+export type ArbiterTransport = 'ssh' | 'https' | 'local';
+
+/**
+ * Classify the git transport an arbiter remote URL uses — the fact that selects
+ * WHICH `auth` policy (`ssh` vs `https`) applies at push time. Mirrors the four
+ * URL shapes `repo-mirror`/`github` already handle:
+ *
+ *  - scp-like ssh (`git@host:org/repo.git`) and `ssh://` ⇒ `ssh`
+ *  - `https://` / `http://` ⇒ `https`
+ *  - `file://` / a plain local path ⇒ `local` (no transport auth applies)
+ */
+export function arbiterTransport(url: string): ArbiterTransport {
+	const trimmed = url.trim();
+	if (!trimmed.includes('://')) {
+		// scp-like ssh: [user@]host:path (a `:` before the path, NOT a local path).
+		const scp = /^(?:[^@/]+@)?([^/:]+):(.+)$/;
+		if (scp.test(trimmed) && !trimmed.startsWith('/')) {
+			return 'ssh';
+		}
+		return 'local'; // a plain absolute path has no transport
+	}
+	const scheme = trimmed.slice(0, trimmed.indexOf('://')).toLowerCase();
+	if (scheme === 'ssh') {
+		return 'ssh';
+	}
+	if (scheme === 'https' || scheme === 'http') {
+		return 'https';
+	}
+	return 'local'; // file:// (or anything else) — no transport auth
+}
+
+/** A validation failure naming the offending field (load-time config error). */
+export class IdentityConfigError extends Error {}
+
+/** A push-time transport-coherence failure (forbidden transport for the arbiter). */
+export class IdentityTransportError extends Error {}
+
+/**
+ * Validate a present `identity` block at config-LOAD time (dumb — does NOT
+ * resolve any arbiter URL; the transport-coherence check is push-time). Throws
+ * an {@link IdentityConfigError} naming the offending field. The structural
+ * "auth mandatory / ssh+https stated" guarantee mostly rides on the type, but a
+ * JSON file is untyped, so we re-check it here for a human-facing message.
+ */
+export function validateIdentity(identity: Identity): void {
+	if (identity.auth === undefined || identity.auth === null) {
+		throw new IdentityConfigError(
+			'identity.auth is required when an identity is configured ' +
+				'(state both `ssh` and `https`).',
+		);
+	}
+	const {ssh, https} = identity.auth;
+	if (ssh === undefined || ssh === null || ssh === '') {
+		throw new IdentityConfigError(
+			'identity.auth.ssh is required (a key path, "ambient", or "never").',
+		);
+	}
+	if (https !== 'ambient' && https !== 'never') {
+		throw new IdentityConfigError(
+			'identity.auth.https must be "ambient" or "never".',
+		);
+	}
+	const github = identity.providers?.github;
+	if (github !== undefined) {
+		const hasToken = 'token' in github && github.token !== undefined;
+		const hasEnv = 'tokenEnv' in github && github.tokenEnv !== undefined;
+		if (hasToken && hasEnv) {
+			throw new IdentityConfigError(
+				'identity.providers.github must set exactly one of `token` or ' +
+					'`tokenEnv`, not both.',
+			);
+		}
+		if (!hasToken && !hasEnv) {
+			throw new IdentityConfigError(
+				'identity.providers.github must set `token` or `tokenEnv`.',
+			);
+		}
+	}
+}
+
+/**
+ * Resolve the `gh` token for the GitHub provider from the identity, or
+ * `undefined` when no GitHub provider auth is configured. A `tokenEnv` is read
+ * from `env` at USE-time (so a missing env var surfaces here with a clear
+ * message), `token` is the literal value. `env` defaults to `process.env`.
+ */
+export function resolveGitHubToken(
+	identity: Identity | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+	const github = identity?.providers?.github;
+	if (github === undefined) {
+		return undefined;
+	}
+	if ('token' in github && github.token !== undefined) {
+		return github.token;
+	}
+	if ('tokenEnv' in github && github.tokenEnv !== undefined) {
+		const value = env[github.tokenEnv];
+		if (value === undefined || value === '') {
+			throw new IdentityConfigError(
+				`identity.providers.github.tokenEnv names env var ` +
+					`"${github.tokenEnv}", which is unset or empty.`,
+			);
+		}
+		return value;
+	}
+	return undefined;
+}
+
+/**
+ * Build the process-scoped environment overrides for `identity`, merged over
+ * `base` (default `process.env`). Returns `base` UNCHANGED (same reference) when
+ * `identity` is `undefined` — the absent-identity path is byte-for-byte today's
+ * behaviour, so callers can pass the result straight through.
+ *
+ * When present it sets, on a COPY of `base`:
+ *   - `GIT_CONFIG_PARAMETERS` — quoted `'user.name=…' 'user.email=…'` (defaults
+ *     applied). Properly single-quoted (with `'\''` escaping) so a name/email
+ *     containing a space or quote cannot break the parse.
+ *   - `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`/`GIT_COMMITTER_NAME`/
+ *     `GIT_COMMITTER_EMAIL` — set to the SAME bot name/email. This is
+ *     LOAD-BEARING: the per-commit `GIT_AUTHOR_*`/`GIT_COMMITTER_*` env vars take
+ *     PRECEDENCE over `user.name`/`user.email` (and thus over
+ *     `GIT_CONFIG_PARAMETERS`). If the AMBIENT env already has them (some CI /
+ *     tooling sets them), `GIT_CONFIG_PARAMETERS` alone would be SILENTLY ignored
+ *     and the commit would be authored by the ambient identity — exactly the
+ *     silent-fallback this feature exists to prevent. So we pin all four to the
+ *     identity, making it win UNCONDITIONALLY over any ambient git identity.
+ *   - `GIT_SSH_COMMAND` — `ssh -i <path> -o IdentitiesOnly=yes -o
+ *     IdentityAgent=none` ONLY when `auth.ssh` is a key path. `"ambient"`/`"never"`
+ *     set nothing (ambient ssh resolution; `"never"` is enforced by the push-time
+ *     transport guard).
+ *
+ *     `IdentityAgent=none` is LOAD-BEARING, NOT decoration: `IdentitiesOnly=yes`
+ *     ALONE does NOT stop a running ssh-agent from offering its OWN keys — it only
+ *     restricts which keys are tried to those whose public file is named, and an
+ *     agent key matching a discoverable `~/.ssh/*.pub` is still offered FIRST. So
+ *     with a personal key in the agent, the push could silently authenticate as
+ *     the HUMAN (the wrong account) despite `-i <bot key>` — the exact silent-
+ *     wrong-account failure mode this feature exists to prevent (the SSH-axis twin
+ *     of the `GIT_AUTHOR_*` pinning below). `IdentityAgent=none` detaches the
+ *     agent entirely, so ONLY the pinned key is offered — it wins unconditionally.
+ *   - `GH_TOKEN` — ONLY when a GitHub provider token is configured (resolved at
+ *     use-time). NEVER fed to git (the token is provider-API only).
+ */
+export function identityEnv(
+	identity: Identity | undefined,
+	base: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+	if (identity === undefined) {
+		return base;
+	}
+	const name = identity.name ?? DEFAULT_IDENTITY_NAME;
+	const email = identity.email ?? DEFAULT_IDENTITY_EMAIL;
+	const env: NodeJS.ProcessEnv = {...base};
+
+	// Commit LABEL (always set when an identity is present). GIT_CONFIG_PARAMETERS
+	// is a space-separated list of shell-quoted `key=value` pairs.
+	env.GIT_CONFIG_PARAMETERS = [
+		shellQuote(`user.name=${name}`),
+		shellQuote(`user.email=${email}`),
+	].join(' ');
+	// Pin the per-commit author/committer env too — these OUTRANK `user.name`/
+	// `user.email`, so without them an ambient `GIT_AUTHOR_*`/`GIT_COMMITTER_*`
+	// would silently beat the identity (the silent-fallback failure mode). Setting
+	// them makes the identity win unconditionally.
+	env.GIT_AUTHOR_NAME = name;
+	env.GIT_AUTHOR_EMAIL = email;
+	env.GIT_COMMITTER_NAME = name;
+	env.GIT_COMMITTER_EMAIL = email;
+
+	// Git TRANSPORT auth — only a PINNED ssh key sets GIT_SSH_COMMAND.
+	// `IdentityAgent=none` is REQUIRED for the pin to actually hold: without it a
+	// running ssh-agent (e.g. with the human's personal key) can offer its own keys
+	// FIRST and silently push as the wrong account, despite `-i <bot key>`.
+	const ssh = identity.auth.ssh;
+	if (ssh !== 'ambient' && ssh !== 'never') {
+		env.GIT_SSH_COMMAND = `ssh -i ${shellQuote(ssh)} -o IdentitiesOnly=yes -o IdentityAgent=none`;
+	}
+
+	// Provider API auth — the gh token, NEVER a git credential.
+	const token = resolveGitHubToken(identity, base);
+	if (token !== undefined) {
+		env.GH_TOKEN = token;
+	}
+
+	return env;
+}
+
+/**
+ * Enforce the push-time transport-coherence rule: the `auth` policy for the
+ * arbiter's actual transport must not be `"never"`. Throws an
+ * {@link IdentityTransportError} with an actionable message (use a matching
+ * remote, or unset `identity`) when the transport is forbidden. A `local`
+ * arbiter (or an absent identity) has nothing to enforce.
+ */
+export function assertTransportAllowed(
+	identity: Identity | undefined,
+	arbiterUrl: string,
+): void {
+	if (identity === undefined) {
+		return;
+	}
+	const transport = arbiterTransport(arbiterUrl);
+	if (transport === 'ssh' && identity.auth.ssh === 'never') {
+		throw new IdentityTransportError(
+			`identity forbids SSH (auth.ssh: "never") but arbiter ` +
+				`"${arbiterUrl}" is an SSH remote. Use an HTTPS remote, set ` +
+				`auth.ssh to a key path or "ambient", or unset identity.`,
+		);
+	}
+	if (transport === 'https' && identity.auth.https === 'never') {
+		throw new IdentityTransportError(
+			`identity forbids HTTPS (auth.https: "never") but arbiter ` +
+				`"${arbiterUrl}" is an HTTPS remote. Use an SSH remote, set ` +
+				`auth.https to "ambient", or unset identity.`,
+		);
+	}
+}
+
+/**
+ * Single-quote a string for safe inclusion in a `GIT_CONFIG_PARAMETERS` /
+ * `GIT_SSH_COMMAND` value: wrap in single quotes and escape any embedded single
+ * quote as `'\''` (close-quote, escaped-quote, re-open-quote — the POSIX idiom).
+ */
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}