dorfl 0.14.2 → 0.15.0

package/src/install-ci-core.ts

@@ -10,8 +10,7 @@
  * This module is the PROVIDER-AGNOSTIC half: the config model (`ProviderEntry` /
  * `AuthMode` / `CIConfigFile`), the `models.json` builder, the secret-orchestration
  * LOGIC (which secrets, dedup, prompt-or-take-from-config), the `--export-config`
- * (+ `--include-secrets`) round-trip, the composite-setup-action + OAuth-refresh-
- * script generators, the `--fake` snapshot mechanism (write to `.fake/` instead of
+ * (+ `--include-secrets`) round-trip, the composite-setup-action generators, the `--fake` snapshot mechanism (write to `.fake/` instead of
  * `.github/`), and the capability-emitter REGISTRY seam. It imports NOTHING
  * GitHub-specific: the thin GitHub adapter (`github-ci.ts`) plugs into the
  * {@link CIProviderContext} seam, so a second provider could slot in WITHOUT
@@ -25,24 +24,50 @@
  * `DORFL_*` env block, NOT a new config knob minted here.
  */
 
-import {readFileSync, writeFileSync, mkdirSync, readdirSync} from 'node:fs';
+import {
+	readFileSync,
+	writeFileSync,
+	mkdirSync,
+	readdirSync,
+	existsSync,
+} from 'node:fs';
 import {dirname, join, relative} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import type {HarnessAdapter} from './config.js';
+import {
+	ACTION_PINS,
+	pinnedUses,
+	preserveExistingPins,
+} from './install-ci-action-pins.js';
 
 // ─── Config model ──────────────────────────────────────────────────────────
 
 /**
- * The two auth modes, mirroring whitesmith:
- *   - `models-json` (DEFAULT): one GitHub secret per provider API key; the harness
- *     `models.json` is generated inline and references the env var names. No
- *     OAuth-refresh machinery, no `GH_PAT` — the conservative default.
- *   - `auth-json`: a single `PI_AUTH_JSON` secret + a `GH_PAT` for OAuth-token
- *     refresh + an OAuth-refresh script (the `pi-mono#2743` workaround, the SINGLE
- *     CI→repo mutation in the whole design). The known SHARP EDGE; default AWAY
- *     from it.
+ * The auth mode. `models-json` is the ONLY mode: one GitHub secret per provider
+ * API key; the harness `models.json` is generated inline and references the env
+ * vars (`$NAME`). Credential rotation (e.g. OAuth) is NOT done in CI: point a
+ * provider's `baseUrl` at a proxy that rotates credentials outside GitHub.
+ *
+ * The former `auth-json` mode (a `PI_AUTH_JSON` secret + an OAuth-refresh
+ * script that wrote the rotated token back with a write-capable `GH_PAT`) was
+ * REMOVED: its refresh needed a write token in the agent job, which ADR
+ * `ci-agent-job-holds-no-write-token` forbids, and without the refresh the
+ * OAuth token expires within hours. A config still naming it is refused by
+ * {@link loadCIConfigFile} with {@link AUTH_JSON_REMOVED_MESSAGE}. The type
+ * (and the `authMode` config key) is kept so existing `models-json` configs
+ * still parse and export unchanged.
+ */
+export type AuthMode = 'models-json';
+
+/**
+ * The refusal a config naming the removed `auth-json` mode gets: it says the
+ * mode is gone and names the replacement (`models-json` + a proxy `baseUrl`).
  */
-export type AuthMode = 'auth-json' | 'models-json';
+export const AUTH_JSON_REMOVED_MESSAGE =
+	'config file "authMode": "auth-json" is no longer supported (the mode was ' +
+	'removed: its OAuth refresh needed a write-capable GH_PAT in the agent job). ' +
+	'Use "authMode": "models-json" and point a provider\'s "baseUrl" at a proxy ' +
+	'that handles credential rotation outside GitHub.';
 
 /**
  * Where the composite setup action gets the `dorfl` CLI from:
@@ -84,7 +109,7 @@ export interface ProviderEntry {
 export interface CIConfigFile {
 	/** The auth mode (`models-json` default). */
 	authMode: AuthMode;
-	/** The configured providers (empty for `auth-json` mode). */
+	/** The configured providers (non-empty). */
 	providers: ProviderEntry[];
 	/** The default provider name. */
 	defaultProvider: string;
@@ -197,6 +222,20 @@ export const DEFAULT_INSTALL_SOURCE: InstallSource = 'registry';
 
 // ─── The CI-provider SEAM (provider-agnostic; GitHub is the first adapter) ───
 
+/**
+ * A repository's GitHub Actions workflow permissions, as
+ * `GET /repos/{owner}/{repo}/actions/permissions/workflow` answers them (the
+ * same two fields the PUT accepts). `defaultWorkflowPermissions` is `read` or
+ * `write` on GitHub; typed as a string so an unexpected value is carried
+ * through untouched rather than rewritten.
+ */
+export interface ActionsWorkflowPermissions {
+	/** The GITHUB_TOKEN's default scope (`read` / `write`); preserved on set. */
+	defaultWorkflowPermissions: string;
+	/** "Allow GitHub Actions to create and approve pull requests". */
+	canApprovePullRequestReviews: boolean;
+}
+
 /**
  * The thin CI-provider seam (whitesmith's proven `GitHubCIContext` shape,
  * generalised so a second provider could slot in without touching the core). A
@@ -277,6 +316,25 @@ export interface CIProviderContext {
 	 * GitHub provider. Throws on failure (caller catches + logs).
 	 */
 	setBranchRuleset?(ruleset: unknown): Promise<void>;
+	/**
+	 * OPTIONALLY read the repo's Actions workflow permissions (GitHub:
+	 * `GET /repos/{owner}/{repo}/actions/permissions/workflow`), whose
+	 * `can_approve_pull_request_reviews` is the "Allow GitHub Actions to create
+	 * and approve pull requests" setting propose mode needs. Returns `undefined`
+	 * when the read fails. Absent on a provider with no such setting.
+	 */
+	getActionsWorkflowPermissions?(): Promise<
+		ActionsWorkflowPermissions | undefined
+	>;
+	/**
+	 * OPTIONALLY set the repo's Actions workflow permissions (GitHub:
+	 * `PUT /repos/{owner}/{repo}/actions/permissions/workflow`). A field left
+	 * `undefined` is not sent, so GitHub keeps its current value. Throws on
+	 * failure (caller catches + logs). Absent on a provider with no such setting.
+	 */
+	setActionsWorkflowPermissions?(
+		permissions: Partial<ActionsWorkflowPermissions>,
+	): Promise<void>;
 	/**
 	 * OPTIONALLY render the user's project-setup payload (the value of
 	 * {@link CIConfigFile.projectSetup}[providerId]) to the NATIVE-SYNTAX
@@ -405,9 +463,12 @@ function pathToFileUrl(absPath: string): string {
 
 /**
  * Build the harness `models.json` object from the providers. Built-in providers
- * (`anthropic`/`openai`) get `{apiKey: <ENV_VAR>}` (the harness resolves the env
- * var at runtime); a custom provider carries its `baseUrl`/`api`/`models`/`compat`.
+ * (`anthropic`/`openai`) get `{apiKey: "$<ENV_VAR>"}` (the harness resolves the
+ * env var at runtime); a custom provider carries its `baseUrl`/`api`/`models`/`compat`.
  * Mirrors whitesmith's `buildModelsJson`.
+ *
+ * The `apiKey` is an env-var REFERENCE (see {@link modelsJsonEnvRef}), never the
+ * bare env-var name: pi treats a bare value as a LITERAL key.
  */
 export function buildModelsJson(providers: ProviderEntry[]): {
 	providers: Record<string, unknown>;
@@ -415,14 +476,16 @@ export function buildModelsJson(providers: ProviderEntry[]): {
 	const providersObj: Record<string, unknown> = {};
 	for (const p of providers) {
 		if (p.builtin) {
-			const entry: Record<string, unknown> = {apiKey: p.apiKeyEnvVar};
+			const entry: Record<string, unknown> = {
+				apiKey: modelsJsonEnvRef(p.apiKeyEnvVar),
+			};
 			if (p.baseUrl) entry.baseUrl = p.baseUrl;
 			providersObj[p.name] = entry;
 		} else {
 			const entry: Record<string, unknown> = {
 				baseUrl: p.baseUrl,
 				api: p.api,
-				apiKey: p.apiKeyEnvVar,
+				apiKey: modelsJsonEnvRef(p.apiKeyEnvVar),
 				models: p.models,
 			};
 			if (p.compat) entry.compat = p.compat;
@@ -432,19 +495,27 @@ export function buildModelsJson(providers: ProviderEntry[]): {
 	return {providers: providersObj};
 }
 
+/**
+ * The `models.json` config value that makes the pi harness read `envVarName`
+ * from the environment: `"$NAME"`. The pinned harness
+ * (`@earendil-works/pi-coding-agent`, `dist/core/resolve-config-value.js`)
+ * resolves a config value as a shell command when it starts with `!`, as an env
+ * var when it is `$NAME` / `${NAME}`, and as a LITERAL otherwise. Writing the bare
+ * name therefore sent the string `ANTHROPIC_API_KEY` as the token (`401
+ * Unauthorized` on every CI launch).
+ */
+export function modelsJsonEnvRef(envVarName: string): string {
+	return `$${envVarName}`;
+}
+
 // ─── secret-orchestration LOGIC (which secrets, dedup) ───────────────────────
 
 /**
  * The DEDUPLICATED set of secret env-var names the config requires, in first-seen
- * order. For `models-json` mode it is one per distinct provider `apiKeyEnvVar`;
- * for `auth-json` mode it is the fixed `PI_AUTH_JSON` + `GH_PAT` pair (the sharp
- * edge). This is the pure secret-orchestration LOGIC the adapter's setter
+ * order: one per distinct provider `apiKeyEnvVar`. This is the pure secret-orchestration LOGIC the adapter's setter
  * consumes — which secrets, deduped — separated from any provider I/O.
  */
 export function requiredSecretNames(config: ResolvedCIConfig): string[] {
-	if (config.authMode === 'auth-json') {
-		return ['PI_AUTH_JSON', 'GH_PAT'];
-	}
 	const seen = new Set<string>();
 	const names: string[] = [];
 	for (const p of config.providers) {
@@ -457,13 +528,13 @@ export function requiredSecretNames(config: ResolvedCIConfig): string[] {
 
 /**
  * The GitHub secret the propose/merge CI legs read as `GH_TOKEN` to open PRs
- * under a CHOSEN identity (a PAT / App token). It is the PR-IDENTITY token, a
- * distinct purpose from `auth-json` mode's `GH_PAT` (which exists only to rotate
- * the OAuth `PI_AUTH_JSON` secret). The generated workflows reference it as
+ * under a CHOSEN identity (a PAT / App token). The generated workflows reference it as
  * `${{ secrets.DORFL_GH_TOKEN || secrets.GITHUB_TOKEN }}` so it is
  * OPTIONAL: unset ⇒ the legs fall back to the built-in `GITHUB_TOKEN` (PRs are
- * `github-actions[bot]` and do not trigger downstream `on: pull_request`
- * workflows); set ⇒ PRs carry the token's identity and DO trigger them.
+ * `github-actions[bot]`, and GitHub holds their `on: pull_request` runs in
+ * `action_required` until someone approves them); set ⇒ PRs carry the token's
+ * identity and trigger those workflows on their own. `intake.yml` never passes
+ * it, so intake PRs always need the approval (`docs/ci/README.md`).
  */
 export const PR_IDENTITY_SECRET_NAME = 'DORFL_GH_TOKEN';
 
@@ -490,14 +561,13 @@ export function optionalSecretNames(config: ResolvedCIConfig): string[] {
  * entry). Each entry maps the action input (named identically to the secret) to
  * `${{ secrets.<NAME> }}`.
  *
- * Empty string when there are no provider keys (auth-json mode, or no providers),
+ * Empty string when there are no provider keys (no providers),
  * so the `uses:` line is emitted bare and unchanged. This is the SINGLE place the
  * provider→`with:` shape lives, shared by every capability workflow generator, so
  * no template re-derives it.
  */
 export function providerSecretsWithBlock(config: ResolvedCIConfig): string {
-	const names =
-		config.authMode === 'models-json' ? requiredSecretNames(config) : [];
+	const names = providerSecretNames(config);
 	if (names.length === 0) {
 		return '';
 	}
@@ -507,6 +577,17 @@ export function providerSecretsWithBlock(config: ResolvedCIConfig): string {
 	return `\n        with:\n${entries}`;
 }
 
+/**
+ * The provider API key secrets the AGENT-running jobs forward to the setup
+ * action: one per distinct provider key (the same set as
+ * {@link requiredSecretNames}). The split item workflow declares exactly these (plus
+ * {@link PR_IDENTITY_SECRET_NAME}) as its `workflow_call` secrets, and hands
+ * them to its agent job only.
+ */
+export function providerSecretNames(config: ResolvedCIConfig): string[] {
+	return requiredSecretNames(config);
+}
+
 /** The outcome of orchestrating one secret through the provider seam. */
 export interface SecretSetResult {
 	/** The secret env-var name. */
@@ -604,12 +685,17 @@ export function loadCIConfigFile(filePath: string): CIConfigFile {
 				(err instanceof Error ? err.message : String(err)),
 		);
 	}
-	const authMode = data.authMode ?? 'models-json';
-	if (authMode !== 'models-json' && authMode !== 'auth-json') {
-		throw new CIConfigError(
-			`config file "authMode" must be "models-json" or "auth-json"`,
-		);
+	// `authMode` is kept as a key (so existing configs still parse) but the only
+	// accepted value is `models-json`. The removed `auth-json` mode gets a refusal
+	// that names its replacement rather than the generic "must be" message.
+	const rawAuthMode: unknown = (data as {authMode?: unknown}).authMode;
+	if (rawAuthMode === 'auth-json') {
+		throw new CIConfigError(AUTH_JSON_REMOVED_MESSAGE);
+	}
+	if (rawAuthMode !== undefined && rawAuthMode !== 'models-json') {
+		throw new CIConfigError(`config file "authMode" must be "models-json"`);
 	}
+	const authMode: AuthMode = 'models-json';
 	if (!data.defaultProvider) {
 		throw new CIConfigError('config file must contain "defaultProvider"');
 	}
@@ -638,20 +724,18 @@ export function loadCIConfigFile(filePath: string): CIConfigFile {
 			);
 		}
 	}
-	if (authMode === 'models-json') {
-		if (
-			!data.providers ||
-			!Array.isArray(data.providers) ||
-			data.providers.length === 0
-		) {
-			throw new CIConfigError(
-				'config file (models-json) must contain a non-empty "providers" array',
-			);
-		}
+	if (
+		!data.providers ||
+		!Array.isArray(data.providers) ||
+		data.providers.length === 0
+	) {
+		throw new CIConfigError(
+			'config file (models-json) must contain a non-empty "providers" array',
+		);
 	}
 	return {
 		authMode,
-		providers: data.providers ?? [],
+		providers: data.providers,
 		defaultProvider: data.defaultProvider,
 		defaultModel: data.defaultModel,
 		harness: data.harness,
@@ -707,7 +791,7 @@ export function exportCIConfig(
 	return JSON.stringify(file, null, 2) + '\n';
 }
 
-// ─── composite setup action + OAuth-refresh script generation ────────────────
+// ─── composite setup action generation ───────────────────────────────────────
 
 /** Indent every non-blank line of `text` by `spaces` spaces. */
 function indent(text: string, spaces: number): string {
@@ -750,6 +834,55 @@ export const PI_HARNESS_PACKAGE = '@earendil-works/pi-coding-agent';
  */
 export const PI_HARNESS_VERSION = '0.80.6';
 
+/**
+ * The `pi` packages the harness LOADS besides itself, each pinned to an exact
+ * version that is known to load with {@link PI_HARNESS_VERSION}.
+ *
+ * `pi-coding-agent` declares its sibling packages with a caret range
+ * (`@earendil-works/pi-ai: ^0.80.6`), which on a `0.x` version floats within
+ * the minor. `pi-ai@0.80.10` removed the `getOAuthApiKey` export that
+ * `pi-coding-agent@0.80.6` imports, so a resolver that honours the caret kills
+ * `pi` on start. npm happens to be protected by the `npm-shrinkwrap.json` the
+ * package publishes; pnpm ignores that file and was broken. Pinning the family
+ * explicitly (as npm `overrides`, see {@link piHarnessManifest}) makes the
+ * install reproducible whatever the resolver.
+ *
+ * The set is `pi-coding-agent`'s own `@earendil-works/*` dependencies plus
+ * theirs (`npm view @earendil-works/pi-coding-agent@<v> dependencies`,
+ * recursively): at 0.80.6 that is pi-ai, pi-agent-core (which depends on pi-ai)
+ * and pi-tui. Re-derive it on every {@link PI_HARNESS_VERSION} bump: a newer
+ * harness may add a package (0.87 adds `@earendil-works/chord`).
+ */
+export const PI_HARNESS_PINNED_DEPENDENCIES: Readonly<Record<string, string>> =
+	{
+		'@earendil-works/pi-agent-core': PI_HARNESS_VERSION,
+		'@earendil-works/pi-ai': PI_HARNESS_VERSION,
+		'@earendil-works/pi-tui': PI_HARNESS_VERSION,
+	};
+
+/**
+ * The throwaway `package.json` the setup action installs the harness from: the
+ * harness at {@link PI_HARNESS_VERSION} as the only dependency, and every pi
+ * package it loads forced to its exact pin through npm `overrides`.
+ *
+ * A project-local install (not `npm install -g`) because `overrides` only apply
+ * to the ROOT project, and a global install makes each package its own root. The
+ * same file is used in `registry` and `workspace` mode: pnpm 11 also isolates
+ * every global package, so listing the pins next to the harness in
+ * `pnpm add -g` would not constrain the harness's own tree either.
+ */
+export function piHarnessManifest(): {
+	private: true;
+	dependencies: Record<string, string>;
+	overrides: Record<string, string>;
+} {
+	return {
+		private: true,
+		dependencies: {[PI_HARNESS_PACKAGE]: PI_HARNESS_VERSION},
+		overrides: {...PI_HARNESS_PINNED_DEPENDENCIES},
+	};
+}
+
 /**
  * The version of THIS dorfl package, read at runtime from its own
  * `package.json` (the single source changesets bumps on release). The composite
@@ -787,29 +920,48 @@ export function dorflPackageVersion(): string {
 	return version;
 }
 
+/** Where the setup action installs the harness (under the job's temp dir). */
+const PI_HARNESS_DIR = '$RUNNER_TEMP/dorfl-harness';
+
 /**
- * The install step for the configured harness (the `pi` CLI; `''` ⇒ none).
- * `registry` mode installs via `npm install -g`; `workspace` mode installs via
- * `pnpm add -g` so the harness lands on the pnpm global bin already on
- * `$GITHUB_PATH` (mirroring whitesmith's dev mode).
+ * The install + smoke steps for the configured harness (the `pi` CLI; `''` ⇒
+ * none). Identical in `registry` and `workspace` mode: the harness is installed
+ * with npm from {@link piHarnessManifest} into a job-local directory whose
+ * `node_modules/.bin` is added to `$GITHUB_PATH`, so every pi package it loads
+ * is pinned whatever package manager the repository uses. The smoke step then
+ * runs `pi --version`, which imports the harness's whole module graph, so a
+ * broken install fails setup with a clear message instead of failing inside a
+ * dorfl agent launch.
  */
-function harnessInstallStep(
-	harness: HarnessAdapter,
-	installSource: InstallSource,
-): string {
+function harnessInstallStep(harness: HarnessAdapter): string {
 	if (harness === 'pi') {
-		const spec = `${PI_HARNESS_PACKAGE}@${PI_HARNESS_VERSION}`;
-		const run =
-			installSource === 'workspace'
-				? `pnpm add -g ${spec}`
-				: `npm install -g ${spec}`;
+		const manifest = JSON.stringify(piHarnessManifest(), null, 2);
 		return `
     # Pinned to the exact harness version this dorfl release declares
-    # (PI_HARNESS_VERSION): the job holds write access and a provider key, so the
-    # version must not move on its own. Re-run \`dorfl install-ci\` to upgrade.
+    # (PI_HARNESS_VERSION), with every pi package it loads pinned too (npm
+    # \`overrides\`; a caret range on a 0.x version floats within the minor): the
+    # job holds a provider key, so no version may move on its own. Re-run
+    # \`dorfl install-ci\` to upgrade.
     - name: Install agent harness (pi)
       shell: bash
-      run: ${run}`;
+      run: |
+        mkdir -p "${PI_HARNESS_DIR}"
+        cd "${PI_HARNESS_DIR}"
+        cat > package.json << 'HARNESS_EOF'
+${indent(manifest, 8)}
+        HARNESS_EOF
+        npm install --no-audit --no-fund
+        echo "${PI_HARNESS_DIR}/node_modules/.bin" >> "$GITHUB_PATH"
+
+    # \`pi --version\` loads the harness's module graph, so an install whose pi
+    # packages do not load together fails HERE, not inside a dorfl agent launch.
+    - name: Check the agent harness loads (pi)
+      shell: bash
+      run: |
+        if ! pi --version; then
+          echo "::error title=dorfl-setup::The agent harness (pi) is installed but cannot start, so its pi packages do not load together. Re-run dorfl install-ci with a dorfl release that pins a working harness."
+          exit 1
+        fi`;
 	}
 	return '';
 }
@@ -822,14 +974,11 @@ function harnessInstallStep(
  * `uses: ./.github/actions/dorfl-setup`. The advance-loop seed template
  * already references this exact action name + path (`docs/ci/README.md`).
  *
- * The auth step branches on the mode: `models-json` writes a generated
- * `~/.pi/agent/models.json` inline (the conservative default) AND exports each
+ * The auth step writes a generated `~/.pi/agent/models.json` inline AND exports each
  * configured provider's API key from a same-named ACTION INPUT to `$GITHUB_ENV`,
  * so the agent step (`pi`) can resolve the env var `models.json` references; the
  * workflow passes the secrets ONCE via `with:` on the `uses:` line (no
- * per-step / per-capability provider enumeration). `auth-json` writes
- * `~/.pi/agent/auth.json` from `$PI_AUTH_JSON` + runs the OAuth-refresh script
- * (the sharp edge). Deterministic: the same config produces byte-identical output.
+ * per-step / per-capability provider enumeration). Deterministic: the same config produces byte-identical output.
  */
 export function generateSetupAction(
 	config: ResolvedCIConfig,
@@ -843,51 +992,32 @@ export function generateSetupAction(
 	 */
 	projectSetupSteps?: string,
 ): string {
-	let authStep: string;
-	// models-json mode declares one ACTION INPUT per distinct provider key (named
-	// identically to the secret / env var) and exports it to `$GITHUB_ENV`, so every
-	// later step inherits it. auth-json mode has no provider keys (it uses auth.json).
-	const providerKeyNames =
-		config.authMode === 'models-json' ? requiredSecretNames(config) : [];
-	if (config.authMode === 'auth-json') {
-		authStep = `\
-    - name: Configure agent auth (auth.json)
-      shell: bash
-      run: |
-        if [ -z "$PI_AUTH_JSON" ]; then
-          echo "ERROR: PI_AUTH_JSON secret is not set" >&2; exit 1
-        fi
-        mkdir -p ~/.pi/agent
-        echo "$PI_AUTH_JSON" > ~/.pi/agent/auth.json
-        chmod 600 ~/.pi/agent/auth.json
-
-    # Workaround for https://github.com/badlogic/pi-mono/issues/2743 — the SINGLE
-    # CI→repo mutation in the design; needs GH_PAT to rotate PI_AUTH_JSON.
-    - name: Refresh OAuth token
-      shell: bash
-      run: node .github/scripts/refresh-oauth-token.mjs`;
-	} else {
-		const modelsJsonStr = JSON.stringify(
-			buildModelsJson(config.providers),
-			null,
-			2,
-		);
-		// Map each provider-key INPUT into the step env, then append the non-empty
-		// ones to `$GITHUB_ENV` so the agent step inherits them. Values flow via env
-		// (never interpolated into the script body), and Actions masks the secret in
-		// logs. `models.json`'s `apiKey` is the env-var NAME; this puts the value there.
-		const exportEnvLines = providerKeyNames
-			.map((name) => `        ${name}: \${{ inputs.${name} }}`)
-			.join('\n');
-		const exportRunLines = providerKeyNames
-			.map(
-				(name) =>
-					`        if [ -n "\${${name}}" ]; then echo "${name}=\${${name}}" >> "$GITHUB_ENV"; fi`,
-			)
-			.join('\n');
-		const exportStep =
-			providerKeyNames.length > 0
-				? `\n
+	// models-json mode (the only mode) declares one ACTION INPUT per distinct
+	// provider key (named identically to the secret / env var) and exports it to
+	// `$GITHUB_ENV`, so every later step inherits it.
+	const providerKeyNames = providerSecretNames(config);
+	const modelsJsonStr = JSON.stringify(
+		buildModelsJson(config.providers),
+		null,
+		2,
+	);
+	// Map each provider-key INPUT into the step env, then append the non-empty
+	// ones to `$GITHUB_ENV` so the agent step inherits them. Values flow via env
+	// (never interpolated into the script body), and Actions masks the secret in
+	// logs. `models.json`'s `apiKey` is a `$NAME` env-var REFERENCE (pi resolves it at
+	// runtime; a bare name would be a literal key); this puts the value there.
+	const exportEnvLines = providerKeyNames
+		.map((name) => `        ${name}: \${{ inputs.${name} }}`)
+		.join('\n');
+	const exportRunLines = providerKeyNames
+		.map(
+			(name) =>
+				`        if [ -n "\${${name}}" ]; then echo "${name}=\${${name}}" >> "$GITHUB_ENV"; fi`,
+		)
+		.join('\n');
+	const exportStep =
+		providerKeyNames.length > 0
+			? `\n
     # Surface the configured provider API key(s) to the environment so the agent
     # step (\`pi\`) can resolve the env var \`models.json\` references. The workflow
     # passes the secret(s) via \`with:\` on the \`uses:\` line; we forward the
@@ -898,8 +1028,8 @@ export function generateSetupAction(
 ${exportEnvLines}
       run: |
 ${exportRunLines}`
-				: '';
-		authStep = `\
+			: '';
+	const authStep = `\
     - name: Configure agent models (models.json)
       shell: bash
       run: |
@@ -907,25 +1037,21 @@ ${exportRunLines}`
         cat > ~/.pi/agent/models.json << 'MODELS_EOF'
 ${indent(modelsJsonStr, 8)}
         MODELS_EOF${exportStep}`;
-	}
 
-	const installHarness = harnessInstallStep(
-		config.harness,
-		config.installSource,
-	);
+	const installHarness = harnessInstallStep(config.harness);
 
 	// The CLI-install block branches on installSource. `registry` installs the
 	// published CLI via `npm install -g dorfl` (the default for every
 	// consumer repo). `workspace` builds the CLI from the checked-out source and
 	// links it onto PATH — for the self-hosting dorfl monorepo, which is
 	// not published under that npm name. We add pnpm's global bin to $GITHUB_PATH
-	// so the linked `dorfl` (and the pnpm-installed harness) are on PATH in
-	// all subsequent steps; we always rebuild because source changes per commit.
+	// so the linked `dorfl` is on PATH in all subsequent steps (the harness adds
+	// its own bin dir, the same way in both modes); we always rebuild because source changes per commit.
 	let installSteps: string;
 	if (config.installSource === 'workspace') {
 		installSteps = `\
     - name: Setup pnpm
-      uses: pnpm/action-setup@v5
+      uses: ${pinnedUses(ACTION_PINS.pnpmSetup)}
 
     - name: Add pnpm global bin to PATH
       shell: bash
@@ -975,10 +1101,9 @@ ${indent(modelsJsonStr, 8)}
 	// double-resolution. The install step below leaves `dorfl` on `$PATH` as the
 	// bootstrap; the forward does the pinning.
 
-	// One optional ACTION INPUT per provider key (models-json mode), named
-	// identically to the secret/env var. Optional + default '' so a workflow that
-	// does not pass it (or auth-json mode, which declares none) is valid; the export
-	// step skips an empty value. auth-json mode declares no inputs.
+	// One optional ACTION INPUT per provider key, named identically to the
+	// secret/env var. Optional + default '' so a workflow that does not pass it is
+	// valid; the export step skips an empty value.
 	const inputsBlock =
 		providerKeyNames.length > 0
 			? `inputs:
@@ -1021,15 +1146,16 @@ runs:
   using: composite
   steps:
 ${projectSetupBlock}    - name: Setup Node.js
-      uses: actions/setup-node@v5
+      uses: ${pinnedUses(ACTION_PINS.setupNode)}
       with:
         node-version: '22'
-        # setup-node@v5 auto-enables package-manager caching, which probes the
-        # project package manager DURING its own run when a lockfile is present,
-        # before that manager is on PATH, so the probe crashes ("Unable to
-        # locate executable file"). dorfl provisions ONLY its own runtime and
-        # leaves the project package-manager cache to the project (toolchain
-        # boundary), so disable it explicitly.
+        # setup-node (v5 and later) auto-enables package-manager caching. In v5
+        # it probed whatever manager package.json's packageManager named, during
+        # its own run and before that manager was on PATH, and crashed ("Unable
+        # to locate executable file"). Since v6 it only fires when package.json
+        # declares npm, and then fails if there is no npm lockfile. Either way
+        # it is the project's cache, not dorfl's: dorfl provisions ONLY its own
+        # runtime (toolchain boundary), so disable it explicitly.
         package-manager-cache: false
 
     - name: Configure git identity
@@ -1044,111 +1170,128 @@ ${authStep}
 `;
 }
 
+/** The local path a workflow step `uses:` for the agent-role setup action. */
+export const SETUP_ACTION_USES = './.github/actions/dorfl-setup';
+
+/** The local path a workflow step `uses:` for the writer-role setup action. */
+export const WRITER_SETUP_ACTION_USES = './.github/actions/dorfl-setup-writer';
+
 /**
- * The OAuth-refresh script emitted ONLY in `auth-json` mode (whitesmith's
- * `pi-mono#2743` workaround): refreshes the Anthropic OAuth token in
- * `~/.pi/agent/auth.json` before the agent runs, then writes the rotated token
- * BACK via `gh secret set PI_AUTH_JSON` (the single CI→repo mutation, needing a
- * `GH_PAT`). This is the documented SHARP EDGE; `models-json` mode avoids it.
- */
-export const REFRESH_OAUTH_SCRIPT = `\
-#!/usr/bin/env node
-/**
- * Refresh OAuth tokens in the agent's auth.json before it runs.
+ * Generate the WRITER-ROLE composite setup action (`dorfl-setup-writer`, spec
+ * `ci-agent-job-without-write-token` §9, ADR
+ * `ci-agent-job-holds-no-write-token`; task `ci-split-generate-workflows`).
+ *
+ * The jobs that hold a write token and run no agent (the split item
+ * workflow's lock and apply jobs, `reap-merged-branches`, `close-job`, and the
+ * read-only `enumerate`) install Node and dorfl ONLY: no harness, no provider
+ * key, no `models.json`, no project-setup hook, no install of the project's
+ * dependencies, and no Actions cache. In `registry` mode the dorfl install runs
+ * from `$RUNNER_TEMP`, outside the checkout, with `--ignore-scripts`, so a
+ * repository `.npmrc` cannot redirect the registry and no install script runs.
  *
- * Workaround for https://github.com/badlogic/pi-mono/issues/2743.
- * After refreshing, updates the PI_AUTH_JSON GitHub secret so the next run has
- * the latest rotated refresh token (requires GH_PAT with repo scope). This is the
- * known SHARP EDGE of auth-json mode; models-json mode avoids it entirely.
+ * In `workspace` mode (dorfl's own repository) dorfl is built from source
+ * (decision 8): the tree of `source-ref` (default the checkout's `HEAD`) is
+ * exported with `git archive` into `$RUNNER_TEMP` and built there with
+ * `--ignore-scripts`. In merge mode that is code an earlier agent landed on
+ * `main`, which is the trust merge mode already implies.
  *
- * Remove this script once the upstream fix is released.
+ * It is a SIBLING action rather than a `role` input on `dorfl-setup`: the
+ * project-setup hook is an opaque fragment spliced first into `dorfl-setup`
+ * (ADR `install-ci-project-provisioning-native-passthrough`), and a composite
+ * action cannot skip an opaque block of steps by input. `dorfl-setup` stays the
+ * agent role, byte for byte.
  */
-import { readFileSync, writeFileSync, chmodSync } from "fs";
-import { join } from "path";
-import { execSync } from "child_process";
-
-const ANTHROPIC_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
-const ANTHROPIC_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+export function generateWriterSetupAction(config: ResolvedCIConfig): string {
+	let installSteps: string;
+	let inputsBlock = '';
+	if (config.installSource === 'workspace') {
+		inputsBlock = `inputs:
+  source-ref:
+    description: 'The commit to build dorfl from (workspace mode). Blank: the checkout HEAD.'
+    required: false
+    default: ''
 
-const authPath = join(process.env.HOME, ".pi", "agent", "auth.json");
-const auth = JSON.parse(readFileSync(authPath, "utf-8"));
-const cred = auth.anthropic;
+`;
+		installSteps = `\
+    - name: Setup pnpm
+      uses: ${pinnedUses(ACTION_PINS.pnpmSetup)}
 
-if (!cred || cred.type !== "oauth") {
-  console.log("No OAuth credentials for anthropic, skipping refresh");
-  process.exit(0);
-}
+    - name: Add pnpm global bin to PATH
+      shell: bash
+      run: |
+        pnpm setup
+        echo "$HOME/.local/share/pnpm" >> "$GITHUB_PATH"
 
-if (Date.now() < cred.expires) {
-  console.log("Token still valid until", new Date(cred.expires).toISOString());
-  process.exit(0);
-}
+    # Workspace mode (dorfl's own repository, decision 8 of ADR
+    # ci-agent-job-holds-no-write-token): build dorfl from the tree of
+    # \`source-ref\`, exported into $RUNNER_TEMP (outside the checkout), with
+    # \`--ignore-scripts\`. In merge mode this is code an earlier agent landed on
+    # main running in a write job, the trust merge mode already implies.
+    # Only dorfl and its workspace dependencies (\`--filter 'dorfl...'\`) are
+    # installed and built: the other workspace packages (the website) are not
+    # needed to run dorfl, so they do not run next to the write token.
+    - name: Build dorfl from the base commit (outside the checkout)
+      shell: bash
+      env:
+        SOURCE_REF: \${{ inputs.source-ref }}
+      run: |
+        set -euo pipefail
+        src="$RUNNER_TEMP/dorfl-src"
+        rm -rf "$src"
+        mkdir -p "$src"
+        git archive "$(git rev-parse --verify "\${SOURCE_REF:-HEAD}^{commit}")" | tar -x -C "$src"
+        cd "$src"
+        pnpm install --frozen-lockfile --ignore-scripts --filter 'dorfl...'
+        pnpm --filter 'dorfl...' build
+        cd packages/dorfl && pnpm link --global`;
+	} else {
+		installSteps = `\
+    # Pinned to the dorfl version that generated this action. Installed from
+    # $RUNNER_TEMP (outside the checkout, so a repository .npmrc cannot redirect
+    # the registry) with --ignore-scripts (no install script runs next to the
+    # write token).
+    - name: Install dorfl (outside the checkout, no install scripts)
+      shell: bash
+      run: |
+        cd "$RUNNER_TEMP"
+        npm install -g --ignore-scripts dorfl@${dorflPackageVersion()}`;
+	}
+	return `\
+name: Setup dorfl (writer role)
+description: Install Node.js and dorfl only, for the CI jobs that run no agent (lock, apply, reap, close, enumerate)
+
+${inputsBlock}# THE WRITER ROLE (ADR ci-agent-job-holds-no-write-token): the jobs that use
+# this action hold a write token (or run next to one) and run NO agent and NO
+# repository code. So it installs Node.js and dorfl ONLY: no agent harness, no
+# provider API key, no models.json, no project-setup hook, no install of the
+# project's dependencies, and no Actions cache (an agent can write
+# default-branch cache entries, so a restore here would run its bytes with
+# write access). The agent role is ./.github/actions/dorfl-setup.
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js
+      uses: ${pinnedUses(ACTION_PINS.setupNode)}
+      with:
+        node-version: '22'
+        # No cache in the writer role (see above).
+        package-manager-cache: false
 
-console.log(
-  "Token expired at",
-  new Date(cred.expires).toISOString(),
-  "- refreshing..."
-);
-
-const response = await fetch(ANTHROPIC_TOKEN_URL, {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/x-www-form-urlencoded",
-    Accept: "application/json",
-  },
-  body: new URLSearchParams({
-    grant_type: "refresh_token",
-    client_id: ANTHROPIC_CLIENT_ID,
-    refresh_token: cred.refresh,
-  }).toString(),
-  signal: AbortSignal.timeout(30_000),
-});
-
-const data = await response.json();
-
-if (!response.ok) {
-  console.error("Refresh failed:", response.status, JSON.stringify(data));
-  process.exit(1);
-}
+    - name: Configure git identity
+      shell: bash
+      run: |
+        git config user.name "dorfl[bot]"
+        git config user.email "dorfl[bot]@users.noreply.github.com"
 
-auth.anthropic = {
-  type: "oauth",
-  refresh: data.refresh_token,
-  access: data.access_token,
-  expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
-};
-
-writeFileSync(authPath, JSON.stringify(auth, null, 2));
-chmodSync(authPath, 0o600);
-console.log(
-  "Token refreshed, new expiry:",
-  new Date(auth.anthropic.expires).toISOString()
-);
-
-// Update the GitHub secret so the next run has the latest refresh token.
-const repo = process.env.GITHUB_REPOSITORY;
-const token = process.env.GH_PAT;
-if (repo && token) {
-  try {
-    execSync(\`gh secret set PI_AUTH_JSON --repo "\${repo}"\`, {
-      input: JSON.stringify(auth),
-      env: { ...process.env, GH_TOKEN: token },
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    console.log("PI_AUTH_JSON secret updated");
-  } catch (err) {
-    console.warn("Failed to update secret (non-fatal):", err.stderr?.toString() || err.message);
-  }
-} else {
-  console.log("Skipping secret update (no GH_PAT or GITHUB_REPOSITORY)");
-}
+${installSteps}
 `;
+}
 
 // ─── the --fake snapshot mechanism + artifact assembly ───────────────────────
 
 /**
- * The setup ARTIFACTS this task generates: the composite setup action + (in
- * `auth-json` mode) the OAuth-refresh script, plus any selected capabilities'
+ * The setup ARTIFACTS this task generates: the composite setup actions, plus
+ * any selected capabilities'
  * workflow files. This task emits NO capability workflow itself (those are the
  * sibling tasks); `capabilities` defaults to none.
  */
@@ -1168,13 +1311,11 @@ export function buildSetupArtifacts(
 			path: join('actions', 'dorfl-setup', 'action.yml'),
 			content: generateSetupAction(config, options?.projectSetupSteps),
 		},
+		{
+			path: join('actions', 'dorfl-setup-writer', 'action.yml'),
+			content: generateWriterSetupAction(config),
+		},
 	];
-	if (config.authMode === 'auth-json') {
-		files.push({
-			path: join('scripts', 'refresh-oauth-token.mjs'),
-			content: REFRESH_OAUTH_SCRIPT,
-		});
-	}
 	for (const cap of capabilities) {
 		files.push(...cap.emit(config));
 	}
@@ -1195,6 +1336,13 @@ export function outputBaseName(fake: boolean): string {
  * Write the artifacts under `<workDir>/<base>/` (base = `.fake` when `fake`, else
  * `.github`). Returns the repo-relative paths actually written. Pure filesystem
  * I/O — no secrets, no git. Creates parent dirs as needed.
+ *
+ * PIN PRESERVATION. Before writing a YAML artifact, any `uses:` of an action the
+ * repository's EXISTING `.github/<path>` already pins to a full commit SHA keeps
+ * that reference and its trailing comment (see {@link preserveExistingPins}),
+ * so a Dependabot bump survives regeneration and a pin is never swapped for a
+ * tag. The existing file is always read from `.github/`, also in `--fake` mode,
+ * so the `.fake/` preview shows what a real run would write.
  */
 export function writeArtifacts(options: {
 	workDir: string;
@@ -1205,8 +1353,15 @@ export function writeArtifacts(options: {
 	const written: string[] = [];
 	for (const file of options.files) {
 		const abs = join(options.workDir, base, file.path);
+		let content = file.content;
+		if (/\.ya?ml$/.test(file.path)) {
+			const current = join(options.workDir, outputBaseName(false), file.path);
+			if (existsSync(current)) {
+				content = preserveExistingPins(content, readFileSync(current, 'utf8'));
+			}
+		}
 		mkdirSync(dirname(abs), {recursive: true});
-		writeFileSync(abs, file.content, 'utf8');
+		writeFileSync(abs, content, 'utf8');
 		written.push(relative(options.workDir, abs));
 	}
 	return written;