dorfl 0.14.3 → 0.15.1

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
@@ -35,6 +34,11 @@ import {
 import {dirname, join, relative} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import type {HarnessAdapter} from './config.js';
+import {NO_FORWARD_ENV} from './bootstrap-forward.js';
+import {
+	REPO_CONFIG_FILENAME,
+	REPO_CONFIG_FILENAME_LEGACY,
+} from './repo-config.js';
 import {
 	ACTION_PINS,
 	pinnedUses,
@@ -44,16 +48,31 @@ import {
 // ─── 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:
@@ -95,7 +114,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;
@@ -208,6 +227,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
@@ -288,6 +321,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
@@ -416,9 +468,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>;
@@ -426,14 +481,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;
@@ -443,19 +500,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) {
@@ -468,13 +533,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';
 
@@ -501,14 +566,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 '';
 	}
@@ -518,6 +582,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. */
@@ -615,12 +690,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"');
 	}
@@ -649,20 +729,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,
@@ -718,7 +796,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 {
@@ -761,6 +839,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
@@ -798,29 +925,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 '';
 }
@@ -833,14 +979,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,
@@ -854,51 +997,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
@@ -909,8 +1033,8 @@ export function generateSetupAction(
 ${exportEnvLines}
       run: |
 ${exportRunLines}`
-				: '';
-		authStep = `\
+			: '';
+	const authStep = `\
     - name: Configure agent models (models.json)
       shell: bash
       run: |
@@ -918,20 +1042,16 @@ ${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 = `\
@@ -986,10 +1106,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:
@@ -1056,111 +1175,234 @@ ${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.
+ * In both modes it then exports `DORFL_NO_FORWARD=1` for the rest of the job
+ * ({@link writerNoForwardStep}): the writer role never forwards to the
+ * repository's `dorflCmd`, which usually points into dependencies this role
+ * never installs. In `registry` mode it also warns when the repository pins a
+ * different dorfl version ({@link WRITER_PIN_CHECK_SCRIPT}).
+ *
+ * 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";
+export function generateWriterSetupAction(config: ResolvedCIConfig): string {
+	let installSteps: string;
+	let inputsBlock = '';
+	// Registry mode only: warn when the repository's `dorflCmd` names an exact
+	// `dorfl@<version>` that is not the version pinned here. Workspace mode builds
+	// dorfl from the checked-out source, so there is no second version to compare.
+	let pinCheckStep = '';
+	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 ANTHROPIC_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
-const ANTHROPIC_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+`;
+		installSteps = `\
+    - name: Setup pnpm
+      uses: ${pinnedUses(ACTION_PINS.pnpmSetup)}
 
-const authPath = join(process.env.HOME, ".pi", "agent", "auth.json");
-const auth = JSON.parse(readFileSync(authPath, "utf-8"));
-const cred = auth.anthropic;
+    - name: Add pnpm global bin to PATH
+      shell: bash
+      run: |
+        pnpm setup
+        echo "$HOME/.local/share/pnpm" >> "$GITHUB_PATH"
 
-if (!cred || cred.type !== "oauth") {
-  console.log("No OAuth credentials for anthropic, skipping refresh");
-  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()}`;
+		pinCheckStep = writerPinCheckStep(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
+
+    - name: Configure git identity
+      shell: bash
+      run: |
+        git config user.name "dorfl[bot]"
+        git config user.email "dorfl[bot]@users.noreply.github.com"
 
-if (Date.now() < cred.expires) {
-  console.log("Token still valid until", new Date(cred.expires).toISOString());
-  process.exit(0);
+${installSteps}
+
+${writerNoForwardStep()}${pinCheckStep}
+`;
 }
 
-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);
+/**
+ * The writer-role step that turns OFF the bootstrap self-forward for every later
+ * step of the job, by exporting {@link NO_FORWARD_ENV}`=1` to `$GITHUB_ENV`.
+ *
+ * Why: a repository that pins dorfl through its dependencies declares
+ * `"dorflCmd": "node_modules/.bin/dorfl"`. The writer role deliberately installs
+ * no project dependency, so that path does not exist, and a forwarding dorfl
+ * would fail every writer job (0.15.0 regression). The dorfl installed above is
+ * already the exact version `install-ci` generated these workflows with (or,
+ * in workspace mode, dorfl built from the checked-out source), so forwarding
+ * gains nothing here. Set ONCE in the action so no job template can forget it.
+ * The agent-role `dorfl-setup` does install dependencies and keeps forwarding.
+ */
+function writerNoForwardStep(): string {
+	return `\
+    # The writer role runs the dorfl installed above and never forwards to the
+    # repository's dorflCmd: that command usually points into the project's
+    # dependencies (node_modules/.bin/dorfl), which this role never installs.
+    # Exported to $GITHUB_ENV so it holds for every later step of the job.
+    - name: Run the dorfl installed above, not the repository's dorflCmd
+      shell: bash
+      run: echo "${NO_FORWARD_ENV}=1" >> "$GITHUB_ENV"`;
 }
 
-auth.anthropic = {
-  type: "oauth",
-  refresh: data.refresh_token,
-  access: data.access_token,
-  expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+/**
+ * The JavaScript the registry-mode writer step runs with `node -e '<script>'
+ * <pinned>` to WARN (never fail) when the repository pins a different dorfl
+ * than the one the writer role installed. Exported so a test can run it.
+ *
+ * It reads JSON only (`dorfl.json`, and `package.json` for the devDependency
+ * case) and runs no project code, so it is safe next to a write token. It
+ * recognises two version-bearing shapes of `dorflCmd`:
+ *
+ * - an exact `dorfl@<version>` inside the command (`npx dorfl@0.16.0`,
+ *   `mise exec dorfl@0.16.0 --`);
+ * - `node_modules/.bin/dorfl`, when `package.json` declares `dorfl` in
+ *   `devDependencies` (or `dependencies`) at an EXACT version.
+ *
+ * Anything else (a caret range, `./bin/dorfl`, no `dorflCmd`) is skipped
+ * silently: resolving it would need the project's dependencies installed,
+ * which the writer role never does. No single quote may appear in it (it is
+ * wrapped in a single-quoted bash string).
+ */
+export const WRITER_PIN_CHECK_SCRIPT = `\
+const fs = require("fs");
+const pinned = process.argv[1];
+const readJson = (p) => {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (e) { return undefined; }
 };
-
-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);
+const semver = "\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:-[0-9A-Za-z.-]+)?";
+const config = readJson("${REPO_CONFIG_FILENAME}") || readJson("${REPO_CONFIG_FILENAME_LEGACY}") || {};
+const cmd = config.dorflCmd;
+if (typeof cmd !== "string") process.exit(0);
+let found;
+let where;
+const inCmd = new RegExp("(?:^|\\\\s)dorfl@(" + semver + ")(?=\\\\s|$)").exec(cmd);
+if (inCmd) {
+  found = inCmd[1];
+  where = "${REPO_CONFIG_FILENAME} dorflCmd";
+} else if (/(?:^|[\\s/])node_modules\\/\\.bin\\/dorfl(?=\\s|$)/.test(cmd)) {
+  const pkg = readJson("package.json") || {};
+  const spec = (pkg.devDependencies || {}).dorfl || (pkg.dependencies || {}).dorfl;
+  if (typeof spec === "string" && new RegExp("^" + semver + "$").test(spec)) {
+    found = spec;
+    where = "package.json (the dorflCmd " + cmd + ")";
   }
-} else {
-  console.log("Skipping secret update (no GH_PAT or GITHUB_REPOSITORY)");
 }
-`;
+if (found !== undefined && found !== pinned) {
+  const esc = (s) => s.replace(/%/g, "%25").replace(/\\r/g, "%0D").replace(/\\n/g, "%0A");
+  console.log("::warning title=dorfl-setup-writer::" + esc(where + " pins dorfl@" + found + " but the writer-role jobs run dorfl@" + pinned + ", the version install-ci generated these workflows with (writer jobs do not forward to dorflCmd). Re-run dorfl install-ci with dorfl " + found + " so every job runs the same version."));
+}`;
+
+/**
+ * The registry-mode writer step that runs {@link WRITER_PIN_CHECK_SCRIPT}. With
+ * the forward off (see {@link writerNoForwardStep}) a disagreement between the
+ * pinned global and the repository's own pin would otherwise go unnoticed: the
+ * agent job forwards to `dorflCmd` while the writer jobs run the pin.
+ */
+function writerPinCheckStep(pinned: string): string {
+	return `
+
+    # Warn (never fail) when the repository pins a dorfl version other than the
+    # one installed above: the agent job forwards to dorflCmd, these writer jobs
+    # do not, so the two roles would run different versions. Reads dorfl.json
+    # and package.json as JSON only; runs no project code.
+    - name: Warn if the repository pins another dorfl version
+      shell: bash
+      run: |
+        node -e '
+${indent(WRITER_PIN_CHECK_SCRIPT, 10)}
+        ' "${pinned}"`;
+}
 
 // ─── 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.
  */
@@ -1180,13 +1422,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));
 	}