dorfl 0.14.1 → 0.14.3

package/src/advance-lifecycle-template.ts

@@ -60,6 +60,7 @@
  * the test generates this artifact under `--fake` and asserts every invariant.
  */
 
+import {ACTION_PINS, pinnedUses} from './install-ci-action-pins.js';
 import type {ResolvedCIConfig} from './install-ci-core.js';
 import {providerSecretsWithBlock} from './install-ci-core.js';
 
@@ -296,7 +297,7 @@ jobs:
       # re-run, no baked-in YAML number.
       githubTimeout: \${{ steps.timeout.outputs.githubTimeout }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup
@@ -306,13 +307,26 @@ jobs:
         # surfaceBlockers), so an override that does not reach this job produces an
         # empty matrix and is silently inert. \`if:\` + the inner \`[ -n ... ]\` guard
         # keep schedule/push (and a blank dispatch field) exporting NOTHING — an
-        # empty DORFL_* would make env-config coercion throw.
+        # empty DORFL_* would make env-config coercion throw. The inputs reach the
+        # shell through \`env:\` as DATA, never as \`\${{ }}\` text spliced into the
+        # script (GitHub's script-injection guidance), and the \`case\` guard stops a
+        # value from appending its own lines to $GITHUB_ENV. Both only matter if an
+        # input ever stops being a fixed \`type: choice\`; for the choices below the
+        # step writes exactly what it always did.
         if: \${{ github.event_name == 'workflow_dispatch' }}
+        env:
+          DISPATCH_AUTO_BUILD: \${{ github.event.inputs.autoBuild }}
+          DISPATCH_AUTO_TASK: \${{ github.event.inputs.autoTask }}
+          DISPATCH_OBSERVATION_TRIAGE: \${{ github.event.inputs.observationTriage }}
+          DISPATCH_SURFACE_BLOCKERS: \${{ github.event.inputs.surfaceBlockers }}
         run: |
-          [ -n "\${{ github.event.inputs.autoBuild }}" ] && echo "DORFL_AUTO_BUILD=\${{ github.event.inputs.autoBuild }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.autoTask }}" ] && echo "DORFL_AUTO_TASK=\${{ github.event.inputs.autoTask }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.observationTriage }}" ] && echo "DORFL_OBSERVATION_TRIAGE=\${{ github.event.inputs.observationTriage }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.surfaceBlockers }}" ] && echo "DORFL_SURFACE_BLOCKERS=\${{ github.event.inputs.surfaceBlockers }}" >> "$GITHUB_ENV"
+          case "\${DISPATCH_AUTO_BUILD}\${DISPATCH_AUTO_TASK}\${DISPATCH_OBSERVATION_TRIAGE}\${DISPATCH_SURFACE_BLOCKERS}" in
+            *$'\\n'*|*$'\\r'*) echo "::error::a dispatch gate override contains a line break"; exit 1 ;;
+          esac
+          [ -n "\${DISPATCH_AUTO_BUILD}" ] && echo "DORFL_AUTO_BUILD=\${DISPATCH_AUTO_BUILD}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_AUTO_TASK}" ] && echo "DORFL_AUTO_TASK=\${DISPATCH_AUTO_TASK}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_OBSERVATION_TRIAGE}" ] && echo "DORFL_OBSERVATION_TRIAGE=\${DISPATCH_OBSERVATION_TRIAGE}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_SURFACE_BLOCKERS}" ] && echo "DORFL_SURFACE_BLOCKERS=\${DISPATCH_SURFACE_BLOCKERS}" >> "$GITHUB_ENV"
           true
       - id: scan
         # Enumerate eligible items as namespaced ids, one matrix leg per id. CI
@@ -393,7 +407,7 @@ jobs:
       matrix:
         item: \${{ fromJson(needs.enumerate.outputs.items) }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}
@@ -402,11 +416,19 @@ jobs:
         # DORFL_* ONLY on a workflow_dispatch with a non-blank input, so the
         # one-shot override also reaches the \`advance\` leg that builds the item.
         if: \${{ github.event_name == 'workflow_dispatch' }}
+        env:
+          DISPATCH_AUTO_BUILD: \${{ github.event.inputs.autoBuild }}
+          DISPATCH_AUTO_TASK: \${{ github.event.inputs.autoTask }}
+          DISPATCH_OBSERVATION_TRIAGE: \${{ github.event.inputs.observationTriage }}
+          DISPATCH_SURFACE_BLOCKERS: \${{ github.event.inputs.surfaceBlockers }}
         run: |
-          [ -n "\${{ github.event.inputs.autoBuild }}" ] && echo "DORFL_AUTO_BUILD=\${{ github.event.inputs.autoBuild }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.autoTask }}" ] && echo "DORFL_AUTO_TASK=\${{ github.event.inputs.autoTask }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.observationTriage }}" ] && echo "DORFL_OBSERVATION_TRIAGE=\${{ github.event.inputs.observationTriage }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.surfaceBlockers }}" ] && echo "DORFL_SURFACE_BLOCKERS=\${{ github.event.inputs.surfaceBlockers }}" >> "$GITHUB_ENV"
+          case "\${DISPATCH_AUTO_BUILD}\${DISPATCH_AUTO_TASK}\${DISPATCH_OBSERVATION_TRIAGE}\${DISPATCH_SURFACE_BLOCKERS}" in
+            *$'\\n'*|*$'\\r'*) echo "::error::a dispatch gate override contains a line break"; exit 1 ;;
+          esac
+          [ -n "\${DISPATCH_AUTO_BUILD}" ] && echo "DORFL_AUTO_BUILD=\${DISPATCH_AUTO_BUILD}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_AUTO_TASK}" ] && echo "DORFL_AUTO_TASK=\${DISPATCH_AUTO_TASK}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_OBSERVATION_TRIAGE}" ] && echo "DORFL_OBSERVATION_TRIAGE=\${DISPATCH_OBSERVATION_TRIAGE}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_SURFACE_BLOCKERS}" ] && echo "DORFL_SURFACE_BLOCKERS=\${DISPATCH_SURFACE_BLOCKERS}" >> "$GITHUB_ENV"
           true
       - name: advance one item in-place (propose ⇒ opens a PR)
         # In-place in this checkout (no --isolated/--remote): the CI container IS
@@ -421,13 +443,19 @@ jobs:
         # works zero-config; the job's \`pull-requests: write\` scopes that token.
         env:
           GH_TOKEN: \${{ secrets.DORFL_GH_TOKEN || secrets.GITHUB_TOKEN }}
+          # The item id is a slug read from work/ (frontmatter \`slug:\` or the
+          # file name). dorfl sanitises the slugs it mints, but a hand-written
+          # one is only checked when \`advance\` resolves it, so it reaches the
+          # shell as DATA through env, never as \`\${{ matrix.item }}\` text
+          # spliced into the script.
+          WORK_ITEM: \${{ matrix.item }}
         # \`--watch\` streams the build agent's high-signal turns (assistant text,
         # tool calls, finish) into THIS job log live, so the run shows the agent
         # working instead of freezing after "Start work". A read-only observer (no
         # outcome/gate/git effect). It fits because each matrix leg names ONE item
         # (one pi session to tail) — the merge job is now a per-item matrix too
         # (see below) and streams the same way.
-        run: dorfl advance "\${{ matrix.item }}" --propose --watch --arbiter origin
+        run: dorfl advance "\${WORK_ITEM}" --propose --watch --arbiter origin
 
   # ── MERGE: a MATRIX of independent jobs (parallel build/gate/review, serialised land) ──
   # SPEC \`land-time-reverify-and-parallel-merge-ceiling\` (stories 4 + 6): each item
@@ -458,7 +486,7 @@ jobs:
       matrix:
         item: \${{ fromJson(needs.enumerate.outputs.items) }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}
@@ -468,11 +496,19 @@ jobs:
         # merge job re-scans the pool inside \`advance -n\`, so it needs the override
         # too for the lifecycle/task pools to reflect it.
         if: \${{ github.event_name == 'workflow_dispatch' }}
+        env:
+          DISPATCH_AUTO_BUILD: \${{ github.event.inputs.autoBuild }}
+          DISPATCH_AUTO_TASK: \${{ github.event.inputs.autoTask }}
+          DISPATCH_OBSERVATION_TRIAGE: \${{ github.event.inputs.observationTriage }}
+          DISPATCH_SURFACE_BLOCKERS: \${{ github.event.inputs.surfaceBlockers }}
         run: |
-          [ -n "\${{ github.event.inputs.autoBuild }}" ] && echo "DORFL_AUTO_BUILD=\${{ github.event.inputs.autoBuild }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.autoTask }}" ] && echo "DORFL_AUTO_TASK=\${{ github.event.inputs.autoTask }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.observationTriage }}" ] && echo "DORFL_OBSERVATION_TRIAGE=\${{ github.event.inputs.observationTriage }}" >> "$GITHUB_ENV"
-          [ -n "\${{ github.event.inputs.surfaceBlockers }}" ] && echo "DORFL_SURFACE_BLOCKERS=\${{ github.event.inputs.surfaceBlockers }}" >> "$GITHUB_ENV"
+          case "\${DISPATCH_AUTO_BUILD}\${DISPATCH_AUTO_TASK}\${DISPATCH_OBSERVATION_TRIAGE}\${DISPATCH_SURFACE_BLOCKERS}" in
+            *$'\\n'*|*$'\\r'*) echo "::error::a dispatch gate override contains a line break"; exit 1 ;;
+          esac
+          [ -n "\${DISPATCH_AUTO_BUILD}" ] && echo "DORFL_AUTO_BUILD=\${DISPATCH_AUTO_BUILD}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_AUTO_TASK}" ] && echo "DORFL_AUTO_TASK=\${DISPATCH_AUTO_TASK}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_OBSERVATION_TRIAGE}" ] && echo "DORFL_OBSERVATION_TRIAGE=\${DISPATCH_OBSERVATION_TRIAGE}" >> "$GITHUB_ENV"
+          [ -n "\${DISPATCH_SURFACE_BLOCKERS}" ] && echo "DORFL_SURFACE_BLOCKERS=\${DISPATCH_SURFACE_BLOCKERS}" >> "$GITHUB_ENV"
           true
       - name: advance one item in-place (merge ⇒ rebase + CAS land on main)
         # In-place (no --isolated/--remote). \`--merge\` ties the integration mode
@@ -483,10 +519,16 @@ jobs:
         # \`GH_TOKEN\` from the env.
         env:
           GH_TOKEN: \${{ secrets.DORFL_GH_TOKEN || secrets.GITHUB_TOKEN }}
+          # The item id is a slug read from work/ (frontmatter \`slug:\` or the
+          # file name). dorfl sanitises the slugs it mints, but a hand-written
+          # one is only checked when \`advance\` resolves it, so it reaches the
+          # shell as DATA through env, never as \`\${{ matrix.item }}\` text
+          # spliced into the script.
+          WORK_ITEM: \${{ matrix.item }}
         # \`--watch\` streams the build agent's high-signal turns into THIS job
         # log live; each leg names ONE item, so it fits the same way it does on
         # the propose legs.
-        run: dorfl advance "\${{ matrix.item }}" --merge --watch --arbiter origin
+        run: dorfl advance "\${WORK_ITEM}" --merge --watch --arbiter origin
 
   # ── REAP merged remote work/* branches (capability F, the hygiene sweep) ─────
   # PRESERVED from the seed (NOT a separate gc-sweep workflow): the provider-
@@ -508,7 +550,7 @@ jobs:
     if: \${{ (github.event.inputs.sweepMergedBranches || 'true') == 'true' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup
@@ -607,11 +649,19 @@ export function validateAdvanceLifecycleWorkflow(
 		text,
 	), 'the matrix items must be ENUMERATED via the eligible-pool scan ' +
 		'(`dorfl scan --json`).');
-	require('propose-one-advance-per-item', /dorfl advance "?\$\{\{\s*matrix\./.test(
+	require('propose-one-advance-per-item', /WORK_ITEM:\s*\$\{\{\s*matrix\.item\s*\}\}[\s\S]*?dorfl advance "\$\{WORK_ITEM\}"/.test(
 		text,
 	), 'each matrix leg must run one `dorfl advance <matrix item>` ' +
-		'(one PR per item).');
-	require('propose-leg-carries-propose-flag', /advance-propose:[\s\S]*?dorfl advance "?\$\{\{\s*matrix\.[\s\S]*?--propose\b/.test(
+		'(one PR per item), reading the item from the step env (`WORK_ITEM`).');
+	// The item id is a slug that may be hand-written (only minted slugs are
+	// sanitised), so it must reach the shell as DATA through `env:`, never as `${{ }}` text
+	// spliced into the `run:` script (GitHub Actions script injection).
+	require('matrix-item-not-spliced-into-run', !/dorfl advance "?\$\{\{/.test(
+		operative,
+	), 'the matrix item must NOT be interpolated into the `run:` script as ' +
+		'`${{ matrix.item }}` (script injection): pass it through the step `env:` ' +
+		'as `WORK_ITEM` and quote it as `"${WORK_ITEM}"`.');
+	require('propose-leg-carries-propose-flag', /advance-propose:[\s\S]*?dorfl advance "\$\{WORK_ITEM\}"[^\n]*--propose\b/.test(
 		text,
 	), 'each `propose` matrix leg must pass `--propose` so the integration mode is ' +
 		'TIED to the matrix shape (a leg can never merge to main / desync from the ' +
@@ -626,7 +676,7 @@ export function validateAdvanceLifecycleWorkflow(
 	), 'the `merge` job must use a MATRIX (parallel build/gate/review per item; ' +
 		"the land tail is serialised by the engine's `mergeRetries` CAS-retry " +
 		"loop, not by the workflow's job shape).");
-	require('merge-leg-carries-merge-flag', /advance-merge:[\s\S]*?dorfl advance "?\$\{\{\s*matrix\.[\s\S]*?--merge\b/.test(
+	require('merge-leg-carries-merge-flag', /advance-merge:[\s\S]*?dorfl advance "\$\{WORK_ITEM\}"[^\n]*--merge\b/.test(
 		text,
 	), 'each `merge` matrix leg must pass `--merge` so the integration mode is ' +
 		'TIED to the matrix shape (a leg can never propose-only / desync from the ' +
@@ -692,9 +742,14 @@ export function validateAdvanceLifecycleWorkflow(
 		['observationTriage', 'DORFL_OBSERVATION_TRIAGE'],
 		['surfaceBlockers', 'DORFL_SURFACE_BLOCKERS'],
 	] as const) {
-		// The override is a guarded shell write: `[ -n <input> ] && echo <ENV>=<input> >> $GITHUB_ENV`.
+		// The override is a guarded shell write of a step-env copy of the input:
+		// `env: DISPATCH_<X>: ${{ inputs.<x> }}` then
+		// `[ -n "${DISPATCH_<X>}" ] && echo "<ENV>=${DISPATCH_<X>}" >> $GITHUB_ENV`.
+		// The input never appears as `${{ }}` text inside the `run:` script.
+		const dispatchVar = envVar.replace(/^DORFL_/, 'DISPATCH_');
 		const guardedWrite = new RegExp(
-			`\\[ -n "\\$\\{\\{ github\\.event\\.inputs\\.${input} \\}\\}" \\][\\s\\S]*?${envVar}=`,
+			`${dispatchVar}:\\s*\\$\\{\\{ github\\.event\\.inputs\\.${input} \\}\\}` +
+				`[\\s\\S]*?\\[ -n "\\$\\{${dispatchVar}\\}" \\] && echo "${envVar}=\\$\\{${dispatchVar}\\}"`,
 		);
 		require(`dispatch-${input}-guarded-write`, guardedWrite.test(
 			text,

package/src/cli.ts

@@ -1108,8 +1108,8 @@ interface CloseMergedIssuesFlags {
  * it prints the error to stderr and exits 1 (the task-only commands never act on
  * a spec). An OMITTED slug (`start`/`complete`/`prompt` infer it from the branch)
  * passes through untouched. (The legacy ''prd:'' prefix is a DEAD namespace token
- * after the hard cutover — it is neither special-cased nor rejected here; a
- * ''prd:<slug>'' arg resolves as a bare literal task slug.)
+ * after the hard cutover: it is not special-cased here; a ''prd:<slug>'' arg
+ * is refused by the shared safe-slug check, since `:` is not a slug character.)
  *
  * `do` is the ONE command that spans both namespaces; it consumes the full
  * `resolveSlug` (with the cross-namespace collision check) in the `do-in-place`

package/src/close-job-template.ts

@@ -33,7 +33,9 @@
  * the test generates this artifact under `--fake` and asserts every invariant.
  */
 
+import {ACTION_PINS, pinnedUses} from './install-ci-action-pins.js';
 import type {ResolvedCIConfig} from './install-ci-core.js';
+import {shouldDropCheckoutCredentials} from './install-ci-core.js';
 
 /** The capability id (the registry key + the emitted workflow file stem). */
 export const CLOSE_JOB_CAPABILITY_ID = 'close-job';
@@ -52,7 +54,19 @@ export const CLOSE_JOB_WORKFLOW_PATH = 'workflows/close-job.yml';
  * and future per-config wiring, but the close-job shape itself is
  * config-independent.
  */
-export function generateCloseJobWorkflow(_config: ResolvedCIConfig): string {
+export function generateCloseJobWorkflow(config: ResolvedCIConfig): string {
+	// `persist-credentials: false` ONLY on a repo KNOWN to be public (see
+	// {@link shouldDropCheckoutCredentials}): this job has `contents: read`, so
+	// the persisted token can only ever read, and on a public repo reads need
+	// no token. Unknown / private / internal ⇒ today's checkout, unchanged.
+	const checkoutCredentials = shouldDropCheckoutCredentials(config)
+		? `
+          # Public repository: every git read works without a token, and this
+          # job cannot push, so do not leave the token in .git/config for later
+          # steps (the setup action, including any project-setup hook, and
+          # close-merged-issues) to read.
+          persist-credentials: false`
+		: '';
 	return `\
 # dorfl — the ISSUE CLOSE-JOB in CI (capability E, spec runner-in-ci).
 # EMITTED by \`dorfl install-ci\`; the human commits it. DO NOT hand-edit a
@@ -110,9 +124,9 @@ jobs:
   close-merged-issues:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
-          fetch-depth: 0
+          fetch-depth: 0${checkoutCredentials}
       - uses: ./.github/actions/dorfl-setup
       - name: close issues whose work has landed on main
         # In-place in this checkout (no --isolated/--remote): the CI container IS

package/src/install-ci-action-pins.ts

@@ -0,0 +1,184 @@
+/**
+ * The ONE table of third-party GitHub Actions that `dorfl install-ci` emits,
+ * each pinned to a full 40-character commit SHA, plus the regeneration rule that
+ * keeps a consumer repository's own pins.
+ *
+ * WHY SHAS. A tag such as `@v5` can be moved by whoever controls the action's
+ * repository, so a compromised or careless release reaches every job that uses
+ * it, including dorfl's jobs that hold `contents: write` and a provider API key.
+ * A commit SHA cannot move. This is GitHub's own hardening guidance ("Using
+ * third-party actions", Security hardening for GitHub Actions).
+ *
+ * THE FORMAT. Every reference is emitted as `owner/repo@<40-hex-sha> # vX.Y.Z`,
+ * the exact shape Dependabot writes and rewrites, so a consumer that enables
+ * Dependabot's `github-actions` ecosystem (with `/.github/actions/*` in
+ * `directories` for the composite action) gets reviewable bump PRs.
+ *
+ * HOW EACH SHA WAS RESOLVED (2026-09-26). For each tag:
+ *   1. `git ls-remote --tags https://github.com/<owner>/<repo>.git`, reading the
+ *      peeled `refs/tags/<tag>^{}` line when the tag is annotated (that line is
+ *      the COMMIT; the unpeeled line is the tag OBJECT and must never be used),
+ *      else the tag line itself for a lightweight tag;
+ *   2. cross-checked with `gh api repos/<owner>/<repo>/git/ref/tags/<tag>`
+ *      (object type) and `gh api repos/<owner>/<repo>/commits/<sha>` (the SHA is
+ *      a commit that exists in the repository).
+ *
+ *   actions/checkout v7.0.1: lightweight tag, `git/ref` type `commit`,
+ *     3d3c42e5aac5ba805825da76410c181273ba90b1 ("prep v7.0.1 release (#2531)").
+ *     The floating `v7` tag points at the same commit. v7 is the current major
+ *     and adds the fork-PR checkout block for `pull_request_target` /
+ *     `workflow_run` that v5 lacks; the inputs dorfl passes (`fetch-depth`,
+ *     `persist-credentials`) are unchanged.
+ *   actions/setup-node v7.0.0: lightweight tag, `git/ref` type `commit`,
+ *     820762786026740c76f36085b0efc47a31fe5020 ("Migrate to ESM and upgrade
+ *     dependencies (#1574)"). The floating `v7` tag points at the same commit.
+ *     `node-version` and `package-manager-cache` are still inputs (see the
+ *     comment on the setup-node step in `generateSetupAction`).
+ *   pnpm/action-setup v6.1.0: ANNOTATED tag. `git/ref` type `tag` with object
+ *     d9184bf108216479bc5a137cc391f4d7b14c870b (the tag object, NOT usable);
+ *     peeled `^{}` and `gh api .../git/tags/d9184bf...` both give the commit
+ *     ea17c68df8912ef543352723c149a84f56e3d413 ("feat: support pnpm v12
+ *     (#288)"). With no `version` input it still reads `packageManager` from
+ *     package.json, which is how dorfl's workspace mode uses it.
+ *
+ * To bump a pin: resolve the new tag the same way, update the entry, and record
+ * the resolution above. `install-ci-actions-pinned.test.ts` fails on any
+ * emitted `uses:` that is not a full SHA.
+ */
+
+/** One pinned third-party action. */
+export interface ActionPin {
+	/** `owner/repo`, or `owner/repo/path` for an action in a subdirectory. */
+	readonly action: string;
+	/** The full 40-character lowercase commit SHA (never a tag object). */
+	readonly sha: string;
+	/** The release tag the SHA was resolved from, for the trailing comment. */
+	readonly version: string;
+}
+
+/** Every third-party action dorfl's generators emit. */
+export const ACTION_PINS = {
+	checkout: {
+		action: 'actions/checkout',
+		sha: '3d3c42e5aac5ba805825da76410c181273ba90b1',
+		version: 'v7.0.1',
+	},
+	setupNode: {
+		action: 'actions/setup-node',
+		sha: '820762786026740c76f36085b0efc47a31fe5020',
+		version: 'v7.0.0',
+	},
+	pnpmSetup: {
+		action: 'pnpm/action-setup',
+		sha: 'ea17c68df8912ef543352723c149a84f56e3d413',
+		version: 'v6.1.0',
+	},
+} as const satisfies Record<string, ActionPin>;
+
+/**
+ * The value to put after `uses: ` for a pinned action:
+ * `owner/repo@<sha> # vX.Y.Z` (the Dependabot format).
+ */
+export function pinnedUses(pin: ActionPin): string {
+	return `${pin.action}@${pin.sha} # ${pin.version}`;
+}
+
+// ─── preserving the consumer's pins on regeneration ─────────────────────────
+
+/**
+ * A `uses:` step line: the prefix (indentation, an optional `- ` list marker,
+ * `uses:` and its spacing), then the VALUE (an optionally quoted
+ * `action@ref`), then an optional trailing comment. Matched per line, which is
+ * how both dorfl's templates and Dependabot write these lines. A flow-style or
+ * multi-line `uses:` value is not recognised (and so not preserved).
+ */
+const USES_LINE =
+	/^(\s*(?:-\s+)?uses:[ \t]+)((['"]?)([^\s'"@#]+)@([^\s'"#]+)\3(?:[ \t]+#.*)?)[ \t]*$/;
+
+/**
+ * A full commit SHA (what counts as "pinned"). Case-insensitive here, so a
+ * consumer's uppercase pin is still kept; dorfl itself emits lowercase.
+ */
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+
+/** The lookup key for an action: GitHub treats `owner/repo` case-insensitively. */
+function actionKey(action: string): string {
+	return action.toLowerCase();
+}
+
+/** A remote action key (`owner/repo[/path]`), i.e. not `./local` nor `docker://`. */
+function isRemoteAction(action: string): boolean {
+	return !action.startsWith('.') && /^[^/\s]+\/[^/\s]+/.test(action);
+}
+
+/** Parse the version out of a trailing `# v1.2.3` comment, for ranking. */
+function versionOf(tail: string): number[] | undefined {
+	const m = /#\s*v?(\d+(?:\.\d+)*)/.exec(tail);
+	return m ? m[1].split('.').map(Number) : undefined;
+}
+
+/** Compare two parsed versions; a missing version ranks lowest. */
+function compareVersions(a?: number[], b?: number[]): number {
+	if (!a || !b) return (a ? 1 : 0) - (b ? 1 : 0);
+	for (let i = 0; i < Math.max(a.length, b.length); i++) {
+		const d = (a[i] ?? 0) - (b[i] ?? 0);
+		if (d !== 0) return d;
+	}
+	return 0;
+}
+
+/**
+ * Collect the SHA pins an existing file already carries, keyed by action
+ * (`owner/repo[/path]`). The value is the whole `uses:` value with its trailing
+ * comment, exactly as written. When the file pins the same action to several
+ * different SHAs, the one whose `# vX.Y.Z` comment is highest wins (ties: the
+ * first in the file), so a partial manual bump is never undone.
+ */
+export function existingPins(existing: string): Map<string, string> {
+	const pins = new Map<string, string>();
+	// `\r?\n`: a CRLF checkout (Windows, `core.autocrlf`) must not hide its pins,
+	// or dorfl's default would silently replace them.
+	for (const line of existing.split(/\r?\n/)) {
+		const m = USES_LINE.exec(line);
+		if (!m) continue;
+		const [, , value, , action, ref] = m;
+		if (!isRemoteAction(action) || !FULL_SHA.test(ref)) continue;
+		const key = actionKey(action);
+		const current = pins.get(key);
+		if (
+			current === undefined ||
+			compareVersions(versionOf(value), versionOf(current)) > 0
+		) {
+			pins.set(key, value);
+		}
+	}
+	return pins;
+}
+
+/**
+ * Rewrite a freshly generated workflow / composite action so every `uses:` of an
+ * action that `existing` already pins to a full SHA keeps the consumer's
+ * reference and trailing comment. Matching is by action (`owner/repo`, plus the
+ * path for an action in a subdirectory), never by position. An existing TAG is
+ * not a pin: the generated reference (dorfl's SHA) stays. So the result never
+ * swaps a SHA for a tag. Only the value after `uses: ` changes; indentation and
+ * every other line are the generated ones.
+ */
+export function preserveExistingPins(
+	generated: string,
+	existing: string | undefined,
+): string {
+	if (existing === undefined) return generated;
+	const pins = existingPins(existing);
+	if (pins.size === 0) return generated;
+	return generated
+		.split('\n')
+		.map((line) => {
+			const m = USES_LINE.exec(line);
+			if (!m) return line;
+			const [, prefix, , , action] = m;
+			const kept = pins.get(actionKey(action));
+			return kept === undefined ? line : `${prefix}${kept}`;
+		})
+		.join('\n');
+}