dorfl 0.14.3 → 0.15.1

package/dist/install-ci-core.js

@@ -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
@@ -27,7 +26,17 @@
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { NO_FORWARD_ENV } from './bootstrap-forward.js';
+import { REPO_CONFIG_FILENAME, REPO_CONFIG_FILENAME_LEGACY, } from './repo-config.js';
 import { ACTION_PINS, pinnedUses, preserveExistingPins, } from './install-ci-action-pins.js';
+/**
+ * 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 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.';
 /** Parse a provider's visibility answer (`PUBLIC`, `private`, ...); unknown ⇒ `undefined`. */
 export function parseRepoVisibility(raw) {
     const v = raw.trim().toLowerCase();
@@ -126,15 +135,20 @@ function pathToFileUrl(absPath) {
 // ─── models.json generation ──────────────────────────────────────────────────
 /**
  * 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) {
     const providersObj = {};
     for (const p of providers) {
         if (p.builtin) {
-            const entry = { apiKey: p.apiKeyEnvVar };
+            const entry = {
+                apiKey: modelsJsonEnvRef(p.apiKeyEnvVar),
+            };
             if (p.baseUrl)
                 entry.baseUrl = p.baseUrl;
             providersObj[p.name] = entry;
@@ -143,7 +157,7 @@ export function buildModelsJson(providers) {
             const entry = {
                 baseUrl: p.baseUrl,
                 api: p.api,
-                apiKey: p.apiKeyEnvVar,
+                apiKey: modelsJsonEnvRef(p.apiKeyEnvVar),
                 models: p.models,
             };
             if (p.compat)
@@ -153,18 +167,25 @@ export function buildModelsJson(providers) {
     }
     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) {
+    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) {
-    if (config.authMode === 'auth-json') {
-        return ['PI_AUTH_JSON', 'GH_PAT'];
-    }
     const seen = new Set();
     const names = [];
     for (const p of config.providers) {
@@ -177,13 +198,13 @@ export function requiredSecretNames(config) {
 }
 /**
  * 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';
 /**
@@ -208,13 +229,13 @@ export function optionalSecretNames(config) {
  * 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) {
-    const names = config.authMode === 'models-json' ? requiredSecretNames(config) : [];
+    const names = providerSecretNames(config);
     if (names.length === 0) {
         return '';
     }
@@ -223,6 +244,16 @@ export function providerSecretsWithBlock(config) {
         .join('\n');
     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) {
+    return requiredSecretNames(config);
+}
 /**
  * Orchestrate the required secrets through the provider seam: for each
  * DEDUPLICATED required name, take its value from `knownSecrets` (the
@@ -290,10 +321,17 @@ export function loadCIConfigFile(filePath) {
         throw new CIConfigError(`could not read/parse config file ${filePath}: ` +
             (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 = data.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 = 'models-json';
     if (!data.defaultProvider) {
         throw new CIConfigError('config file must contain "defaultProvider"');
     }
@@ -314,16 +352,14 @@ export function loadCIConfigFile(filePath) {
                 'the per-provider payload is OPAQUE to the core');
         }
     }
-    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,
@@ -373,7 +409,7 @@ export function exportCIConfig(config, secrets) {
     }
     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, spaces) {
     const pad = ' '.repeat(spaces);
@@ -412,6 +448,48 @@ export const PI_HARNESS_PACKAGE = '@earendil-works/pi-coding-agent';
  * `node-version: '22'` satisfies (setup-node resolves the latest 22.x).
  */
 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 = {
+    '@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() {
+    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
@@ -443,25 +521,47 @@ export function dorflPackageVersion() {
     }
     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, installSource) {
+function harnessInstallStep(harness) {
     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 '';
 }
@@ -473,14 +573,11 @@ function harnessInstallStep(harness, installSource) {
  * `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, 
 /**
@@ -492,43 +589,24 @@ export function generateSetupAction(config,
  * baseline (the load-bearing absent-⇒-identical contract).
  */
 projectSetupSteps) {
-    let authStep;
-    // 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
@@ -539,8 +617,8 @@ projectSetupSteps) {
 ${exportEnvLines}
       run: |
 ${exportRunLines}`
-            : '';
-        authStep = `\
+        : '';
+    const authStep = `\
     - name: Configure agent models (models.json)
       shell: bash
       run: |
@@ -548,15 +626,14 @@ ${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;
     if (config.installSource === 'workspace') {
         installSteps = `\
@@ -610,10 +687,9 @@ ${indent(modelsJsonStr, 8)}
     // would exec the local bin which then forwards AGAIN — a confusing
     // 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:
 ${providerKeyNames
@@ -672,109 +748,228 @@ ${installSteps}
 ${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";
-
-const ANTHROPIC_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
-const ANTHROPIC_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+export function generateWriterSetupAction(config) {
+    let installSteps;
+    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 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()}`;
+        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)
 
-console.log(
-  "Token expired at",
-  new Date(cred.expires).toISOString(),
-  "- refreshing..."
-);
+${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
 
-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),
-});
+    - name: Configure git identity
+      shell: bash
+      run: |
+        git config user.name "dorfl[bot]"
+        git config user.email "dorfl[bot]@users.noreply.github.com"
 
-const data = await response.json();
+${installSteps}
 
-if (!response.ok) {
-  console.error("Refresh failed:", response.status, JSON.stringify(data));
-  process.exit(1);
+${writerNoForwardStep()}${pinCheckStep}
+`;
 }
-
-auth.anthropic = {
-  type: "oauth",
-  refresh: data.refresh_token,
-  access: data.access_token,
-  expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+/**
+ * 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() {
+    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"`;
+}
+/**
+ * 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) {
+    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.
  */
@@ -791,13 +986,11 @@ options) {
             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));
     }