forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/lib/npm-publish-workflow.js

@@ -2,17 +2,112 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { secureExecFileSync } = require('./shell-utils');
 
 const {
 	createProtectedStateAuditRecord,
 	recordProtectedStateAuditEvent,
+	removeProtectedFile,
 	writeProtectedFile,
 } = require('./protected-state-surfaces');
 const {
+	completeNpmPublishWorkflowAuthorization,
 	issueNpmPublishWorkflowAuthorization,
 } = require('./protected-state-authority');
 
 const NPM_PUBLISH_WORKFLOW_PATH = '.github/workflows/npm-publish.yml';
+const FULL_COMMIT_SHA = /^[0-9a-f]{40}$/;
+const BUN_VERSION = /^bun@(\d+\.\d+\.\d+)$/.exec(require('../package.json').packageManager)?.[1];
+if (!BUN_VERSION) throw new Error('package.json must pin an exact stable Bun version.');
+
+function resolveCurrentHead(projectRoot, execGit = secureExecFileSync) {
+	return execGit('git', ['rev-parse', '--verify', 'HEAD^{commit}'], {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	}).trim();
+}
+
+function readNpmPublishWorkflow(projectRoot, revision, execGit = secureExecFileSync) {
+	const options = {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	};
+	const indexed = revision === ':';
+	const entry = execGit('git', indexed
+		? ['ls-files', '--stage', '--', NPM_PUBLISH_WORKFLOW_PATH]
+		: ['ls-tree', revision, '--', NPM_PUBLISH_WORKFLOW_PATH], options).trim();
+	const expected = indexed
+		? /^100(?:644|755) [0-9a-f]+ 0\t\.github\/workflows\/npm-publish\.yml$/
+		: /^100(?:644|755) blob [0-9a-f]+\t\.github\/workflows\/npm-publish\.yml$/;
+	if (!expected.test(entry)) {
+		throw new Error(`${NPM_PUBLISH_WORKFLOW_PATH} is not one regular file ${indexed ? 'in the Git index' : `at ${revision}`}.`);
+	}
+	return Buffer.from(execGit('git', ['show', `${revision}${indexed ? '' : ':'}${NPM_PUBLISH_WORKFLOW_PATH}`], {
+		...options,
+		encoding: 'buffer',
+	}));
+}
+
+function readSourceNpmPublishWorkflow(projectRoot, sourceHead, execGit = secureExecFileSync) {
+	return readNpmPublishWorkflow(projectRoot, sourceHead, execGit);
+}
+
+function readIndexedNpmPublishWorkflow(projectRoot, execGit = secureExecFileSync) {
+	return readNpmPublishWorkflow(projectRoot, ':', execGit);
+}
+
+function verifyExpectedHead(projectRoot, expectedHead, resolveHead = resolveCurrentHead) {
+	if (!expectedHead) {
+		return { success: false, error: '--expect-head is required for protected workflow generation.' };
+	}
+	if (!FULL_COMMIT_SHA.test(expectedHead)) {
+		return { success: false, error: '--expect-head must be a full 40-character lowercase commit SHA.' };
+	}
+
+	let currentHead;
+	try {
+		currentHead = resolveHead(projectRoot);
+	} catch (error) {
+		return { success: false, error: `Could not resolve current HEAD: ${error.message}` };
+	}
+	if (!FULL_COMMIT_SHA.test(currentHead)) {
+		return { success: false, error: 'Current HEAD did not resolve to a full 40-character lowercase commit SHA.' };
+	}
+	if (currentHead !== expectedHead) {
+		return {
+			success: false,
+			error: `Expected HEAD ${expectedHead} does not match current HEAD ${currentHead}.`,
+		};
+	}
+	return { success: true, sourceHead: currentHead };
+}
+
+function renderNpmDistTagResolverScript() {
+	return `CORE_RE='(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)'
+NUMERIC_ID_RE='(0|[1-9][0-9]*)'
+BUILD_RE='(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?'
+BETA_RE="^\${CORE_RE}-beta(\\.\${NUMERIC_ID_RE})*\${BUILD_RE}$"
+RC_RE="^\${CORE_RE}-rc(\\.\${NUMERIC_ID_RE})*\${BUILD_RE}$"
+STABLE_RE="^\${CORE_RE}\${BUILD_RE}$"
+
+if [[ "$VERSION" =~ $BETA_RE ]]; then
+  echo "tag=beta" >> "$GITHUB_OUTPUT"
+elif [[ "$VERSION" =~ $RC_RE ]]; then
+  echo "tag=rc" >> "$GITHUB_OUTPUT"
+elif [[ "$VERSION" =~ $STABLE_RE ]]; then
+  echo "tag=latest" >> "$GITHUB_OUTPUT"
+elif [[ "$VERSION" == *-* ]]; then
+  echo "::error::Unsupported npm prerelease: $VERSION"
+  exit 1
+else
+  echo "::error::Invalid npm version: $VERSION"
+  exit 1
+fi`;
+}
 
 function snapshotWorkflow(projectRoot) {
 	const fullPath = path.resolve(projectRoot, NPM_PUBLISH_WORKFLOW_PATH);
@@ -29,24 +124,57 @@ function snapshotWorkflow(projectRoot) {
 	}
 }
 
-function rollbackWorkflow(snapshot, projectRoot, protectedWriter, writeOptions) {
+function sameSnapshot(expected, actual) {
+	if (!expected || typeof expected !== 'object' || Array.isArray(expected)) return false;
+	if (typeof expected.existed !== 'boolean') return false;
+	if (expected.existed && !Buffer.isBuffer(expected.content)) return false;
+	if (!expected.existed && expected.content !== null) return false;
+	return expected.existed === actual.existed
+		&& (!expected.existed || expected.content.equals(actual.content));
+}
+
+function recoverWorkflow(snapshot, projectRoot, generatedContent, protectedWriter, protectedRemover, writeOptions) {
+	const recoveryOptions = {
+		...writeOptions,
+		operation: 'recover_npm_workflow',
+		expectedContent: generatedContent,
+	};
 	if (!snapshot.existed) {
-		fs.rmSync(snapshot.fullPath, { force: true });
-		return;
+		return protectedRemover(projectRoot, NPM_PUBLISH_WORKFLOW_PATH, recoveryOptions);
 	}
 	if (!Buffer.isBuffer(snapshot.content)) {
-		throw new Error('Previous workflow was not a regular file');
+		return { allowed: false, reason: 'Previous workflow was not a regular file' };
 	}
-	const restored = protectedWriter(
+	return protectedWriter(
 		projectRoot,
 		NPM_PUBLISH_WORKFLOW_PATH,
 		snapshot.content,
-		writeOptions,
+		recoveryOptions,
 	);
-	if (!restored.allowed) throw new Error(restored.reason || 'Protected workflow restore was denied');
 }
 
-function renderNpmPublishWorkflow() {
+async function prepareWorkflowAuthorization(prepareAuthorization, projectRoot, params, authorizationOptions) {
+	try {
+		return await prepareAuthorization(projectRoot, params, authorizationOptions);
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+}
+
+function recordWorkflowAudit(auditWriter, auditRecord, projectRoot) {
+	try {
+		return auditWriter(auditRecord, { cwd: projectRoot });
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+}
+
+function renderNpmPublishWorkflow(bunVersion = BUN_VERSION) {
+	if (!/^\d+\.\d+\.\d+$/.test(bunVersion)) throw new Error('npm workflow requires an exact stable Bun version.');
+	const distTagResolver = renderNpmDistTagResolverScript()
+		.split('\n')
+		.map(line => line ? `          ${line}` : '')
+		.join('\n');
 	return `# Generated by \`forge release generate-npm-workflow\`. Do not edit directly.
 name: Bun Package
 
@@ -61,6 +189,7 @@ jobs:
   resolve-release:
     name: Resolve immutable release SHA
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: read
     outputs:
@@ -88,6 +217,7 @@ jobs:
   build:
     needs: resolve-release
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     permissions:
       contents: read
     outputs:
@@ -105,7 +235,7 @@ jobs:
           node-version: 22
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.12
+          bun-version: ${bunVersion}
       - run: bun install --frozen-lockfile
       - name: Setup test fixtures
         shell: bash
@@ -124,6 +254,7 @@ jobs:
   publish-npm:
     needs: [resolve-release, build]
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     permissions:
       contents: read
       id-token: write
@@ -146,7 +277,7 @@ jobs:
         run: node scripts/npm-release-receipt.js verify
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.12
+          bun-version: ${bunVersion}
       - run: bun install --frozen-lockfile
       - name: Release tag matches package.json version
         shell: bash
@@ -164,36 +295,92 @@ jobs:
         run: npm pack --dry-run
       - name: Ensure OIDC-capable npm
         run: npm install --global npm@11.5.1 && npm --version
-      - name: Publish to npm
+      - name: Resolve npm dist-tag
+        id: dist-tag
         shell: bash
         run: |
           set -euo pipefail
           VERSION="$(node -p "require('./package.json').version")"
-          if echo "$VERSION" | grep -q '-'; then
-            echo "Prerelease $VERSION -> publishing under the beta dist-tag"
-            npm publish --provenance --tag beta
-          else
-            npm publish --provenance
-          fi
+${distTagResolver}
+      - name: Publish to npm
+        shell: bash
+        run: |
+          set -euo pipefail
+          DIST_TAG="\${{ steps.dist-tag.outputs.tag }}"
+          case "$DIST_TAG" in
+            beta)
+              npm publish --provenance --tag beta
+              ;;
+            rc)
+              npm publish --provenance --tag rc
+              ;;
+            latest)
+              npm publish --provenance
+              ;;
+            *)
+              echo "::error::Unsupported npm dist-tag: $DIST_TAG"
+              exit 1
+              ;;
+          esac
 `;
 }
 
 async function generateNpmPublishWorkflow(projectRoot, options = {}) {
-	const content = renderNpmPublishWorkflow();
+	const head = verifyExpectedHead(projectRoot, options.expectedHead, options.resolveHead);
+	if (!head.success) return head;
+	const sourceHead = head.sourceHead;
+	let targetBunVersion;
+	try {
+		targetBunVersion = options.targetBunVersion
+			|| require('./bun-workflow-pins').resolveBunVersionTarget(projectRoot, options).version;
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	const bunVersion = options.bunVersion || targetBunVersion;
+	if (bunVersion !== targetBunVersion) {
+		return { success: false, error: 'npm workflow Bun version must match the staged package.json Bun pin.' };
+	}
+	const content = renderNpmPublishWorkflow(bunVersion);
 	const actor = options.actor || options.env?.FORGE_ACTOR || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'unknown';
 	const protectedWriter = options.writeProtectedFile || writeProtectedFile;
+	const protectedRemover = options.removeProtectedFile || removeProtectedFile;
 	const auditWriter = options.recordProtectedStateAuditEvent || recordProtectedStateAuditEvent;
-	const authorizationWriter = options.issueNpmPublishWorkflowAuthorization || issueNpmPublishWorkflowAuthorization;
+	const prepareAuthorization = options.prepareNpmPublishWorkflowAuthorization || issueNpmPublishWorkflowAuthorization;
+	const activateAuthorization = options.activateNpmPublishWorkflowAuthorization || completeNpmPublishWorkflowAuthorization;
 	const snapshot = snapshotWorkflow(projectRoot);
+	if (options.expectedSnapshot && !sameSnapshot(options.expectedSnapshot, snapshot)) {
+		return {
+			success: false,
+			error: `${NPM_PUBLISH_WORKFLOW_PATH} changed after Bun pin batch preflight.`,
+		};
+	}
 	const writeOptions = {
 		actor,
 		operation: 'generate_npm_workflow',
 		viaForgeApi: true,
 		surface: 'workflows',
 	};
+	const trustedAuthorization = await prepareWorkflowAuthorization(
+		prepareAuthorization,
+		projectRoot,
+		{ actor, sourceHead, bunVersion, targetBunVersion },
+		{ deps: options.kernelDeps, capabilityId: options.capabilityId },
+	);
+	if (!trustedAuthorization.success) {
+		return {
+			success: false,
+			error: `Could not record trusted protected-state authorization: ${trustedAuthorization.error}`,
+			trustedAuthorization,
+		};
+	}
+
 	let write;
 	try {
-		write = protectedWriter(projectRoot, NPM_PUBLISH_WORKFLOW_PATH, content, writeOptions);
+		write = protectedWriter(projectRoot, NPM_PUBLISH_WORKFLOW_PATH, content, {
+			...writeOptions,
+			expectedContent: snapshot.existed ? snapshot.content : null,
+			...(options.beforeAtomicCommit ? { beforeAtomicCommit: options.beforeAtomicCommit } : {}),
+		});
 	} catch (error) {
 		return { success: false, error: error.message };
 	}
@@ -207,66 +394,72 @@ async function generateNpmPublishWorkflow(projectRoot, options = {}) {
 		path: NPM_PUBLISH_WORKFLOW_PATH,
 		content,
 		operation: 'generate_npm_workflow',
+		viaForgeApi: true,
+		sourceHead,
 	});
-	let audit;
-	try {
-		audit = auditWriter(auditRecord, { cwd: projectRoot });
-	} catch (error) {
-		audit = { success: false, error: error.message };
-	}
+	const audit = recordWorkflowAudit(auditWriter, auditRecord, projectRoot);
 	if (!audit.success) {
-		let rollbackError;
+		let recovery;
 		try {
-			rollbackWorkflow(snapshot, projectRoot, protectedWriter, writeOptions);
+			recovery = recoverWorkflow(snapshot, projectRoot, content, protectedWriter, protectedRemover, writeOptions);
 		} catch (error) {
-			rollbackError = error.message;
+			recovery = { allowed: false, reason: error.message };
 		}
 		return {
 			success: false,
 			error: `Could not record protected-state authorization: ${audit.error}`,
 			audit,
-			rollbackError,
+			recovery,
 		};
 	}
 
-	let trustedAuthorization;
+	let writeCompletion;
 	try {
-		trustedAuthorization = await authorizationWriter(
+		writeCompletion = await activateAuthorization(
 			projectRoot,
-			{ actor },
+			{ actor, sourceHead, capabilityId: trustedAuthorization.capabilityId, bunVersion, targetBunVersion },
 			{ deps: options.kernelDeps },
 		);
 	} catch (error) {
-		trustedAuthorization = { success: false, error: error.message };
+		writeCompletion = { success: false, error: error.message };
 	}
-	if (!trustedAuthorization.success) {
-		let rollbackError;
+	if (!writeCompletion.success) {
+		let recovery;
 		try {
-			rollbackWorkflow(snapshot, projectRoot, protectedWriter, writeOptions);
+			recovery = recoverWorkflow(snapshot, projectRoot, content, protectedWriter, protectedRemover, writeOptions);
 		} catch (error) {
-			rollbackError = error.message;
+			recovery = { allowed: false, reason: error.message };
 		}
 		return {
 			success: false,
-			error: `Could not record trusted protected-state authorization: ${trustedAuthorization.error}`,
+			error: `Could not complete trusted protected-state authorization: ${writeCompletion.error}`,
 			audit,
 			trustedAuthorization,
-			rollbackError,
+			writeCompletion,
+			recovery,
 		};
 	}
 
 	return {
 		success: true,
 		path: NPM_PUBLISH_WORKFLOW_PATH,
+		sourceHead,
+		bunVersion,
 		contentHash: write.contentHash,
 		write,
 		audit,
 		trustedAuthorization,
+		writeCompletion,
 	};
 }
 
 module.exports = {
 	NPM_PUBLISH_WORKFLOW_PATH,
+	readIndexedNpmPublishWorkflow,
+	readSourceNpmPublishWorkflow,
+	renderNpmDistTagResolverScript,
 	renderNpmPublishWorkflow,
+	resolveCurrentHead,
+	verifyExpectedHead,
 	generateNpmPublishWorkflow,
 };

package/lib/package-root.js

@@ -67,8 +67,10 @@ const ASSET_ROOTS = Object.freeze([
   'skills',
   'rules',
   'AGENTS.md',
+  'CODING_STANDARDS.md',
   '.claude/scripts',
   '.forge/hooks',
+  'lib/kernel/windows-private-acl.js',
   'scripts',
 ]);
 

package/lib/pr-monitor/auto-actions.js

@@ -35,6 +35,17 @@ const INFRA_CONCLUSIONS = new Set(['CANCELLED', 'TIMED_OUT', 'STALE', 'STARTUP_F
 /** Conclusions that mean the code is genuinely broken — NEVER auto-rerun these. */
 const REAL_FAILURE_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'ACTION_REQUIRED']);
 
+const AUTO_ACTION_STATUS = Object.freeze({
+  PASS: 'PASS',
+  UNCHANGED: 'UNCHANGED',
+  STALE: 'STALE',
+  INCOMPLETE: 'INCOMPLETE',
+  CONFLICT: 'CONFLICT',
+});
+
+const MAX_AUTO_ACTIONS = 8;
+const MAX_AUTO_ATTEMPTS = 5;
+
 /**
  * Pull the numeric Actions run id from a job/run "details" URL
  * (`.../actions/runs/<run>/job/<job>` or `.../actions/runs/<run>`). Returns null
@@ -99,16 +110,40 @@ function decideUpdateBranch(payload, opts = {}) {
   return { should: true, reason: 'otherwise-clean-behind — only blocker is behind-base; merge base in' };
 }
 
+function indexFailures(failures) {
+  const byName = new Map();
+  for (const failure of failures) {
+    if (!failure?.name || byName.has(failure.name)) continue;
+    byName.set(failure.name, {
+      conclusion: String(failure.conclusion || '').toUpperCase(),
+      url: failure.jobUrl || failure.detailsUrl || null,
+    });
+  }
+  return byName;
+}
+
+function selectRerunChecks(failingNames, failuresByName) {
+  const checks = [];
+  for (const name of failingNames) {
+    const failure = failuresByName.get(name);
+    if (!failure?.conclusion) {
+      return { reason: `required check "${name}" has no known conclusion — cannot confirm flaky, fail closed` };
+    }
+    if (REAL_FAILURE_CONCLUSIONS.has(failure.conclusion)) {
+      return { reason: `required check "${name}" is a real failure (${failure.conclusion}) — never rerun` };
+    }
+    if (!INFRA_CONCLUSIONS.has(failure.conclusion)) {
+      return { reason: `required check "${name}" conclusion ${failure.conclusion} is not classified infrastructural — fail closed` };
+    }
+    checks.push({ name, conclusion: failure.conclusion, runId: runIdFromUrl(failure.url) });
+  }
+  return { checks };
+}
+
 /**
  * Decide whether to re-run flaky REQUIRED checks. Fires ONLY when EVERY failing
- * required check is infrastructural (cancelled/timed-out/stale/startup-failure)
- * with a derivable run id, and NONE is a real FAILURE/ERROR/ACTION_REQUIRED. A
- * single real failure, an unclassifiable conclusion, a required-failing check
- * with no matching `failures[]` entry, or a missing run id fails the WHOLE
- * decision closed (never rerun a genuinely-broken PR, never loop on a real bug).
- *
- * @param {object} payload - the `--pull --json` payload.
- * @returns {{ should: boolean, checks: Array<{name:string,conclusion:string,runId:string|null}>, runIds: string[], reason: string }}
+ * required check is infrastructural with a derivable run id, and NONE is a real
+ * failure or an unclassifiable signal.
  */
 function decideRerun(payload) {
   const empty = (reason) => ({ should: false, checks: [], runIds: [], reason });
@@ -119,28 +154,15 @@ function decideRerun(payload) {
   const failingNames = Array.isArray(rc.failing) ? rc.failing : [];
   if (failingNames.length === 0) return empty('no failing required checks');
 
-  const failures = Array.isArray(payload.failures) ? payload.failures : [];
-  const conclByName = new Map();
-  const urlByName = new Map();
-  for (const f of failures) {
-    if (!f || !f.name) continue;
-    if (!conclByName.has(f.name)) {
-      conclByName.set(f.name, String(f.conclusion || '').toUpperCase());
-      urlByName.set(f.name, f.jobUrl || f.detailsUrl || null);
-    }
-  }
-
-  const picked = [];
-  for (const name of failingNames) {
-    const concl = conclByName.get(name);
-    if (!concl) return empty(`required check "${name}" has no known conclusion — cannot confirm flaky, fail closed`);
-    if (REAL_FAILURE_CONCLUSIONS.has(concl)) return empty(`required check "${name}" is a real failure (${concl}) — never rerun`);
-    if (!INFRA_CONCLUSIONS.has(concl)) return empty(`required check "${name}" conclusion ${concl} is not classified infrastructural — fail closed`);
-    picked.push({ name, conclusion: concl, runId: runIdFromUrl(urlByName.get(name)) });
-  }
+  const selection = selectRerunChecks(
+    failingNames,
+    indexFailures(Array.isArray(payload.failures) ? payload.failures : []),
+  );
+  if (selection.reason) return empty(selection.reason);
 
+  const picked = selection.checks;
   const runIds = [...new Set(picked.map((p) => p.runId).filter(Boolean))];
-  if (runIds.length === 0) return empty('no run id derivable from failure jobUrl — fail closed');
+  if (picked.some((item) => !item.runId)) return empty('no run id derivable from failure jobUrl — fail closed');
   return {
     should: true,
     checks: picked,
@@ -164,6 +186,123 @@ function decideAutoActions(payload, opts = {}) {
   };
 }
 
+function boundedPolicyValue(value, fallback, maximum) {
+  const selected = value ?? fallback;
+  return Number.isSafeInteger(selected) && selected > 0 && selected <= maximum ? selected : null;
+}
+
+function normalizeActionHistory(history) {
+  if (!Array.isArray(history)) return { ok: false, reason: 'action history is incomplete' };
+  const byKey = new Map();
+  for (const item of history) {
+    if (!item || typeof item.key !== 'string' || !item.key
+      || !['pending', 'applied', 'failed'].includes(item.state)
+      || !Number.isSafeInteger(item.attempts) || item.attempts < 0) {
+      return { ok: false, reason: 'action history is incomplete' };
+    }
+    const prior = byKey.get(item.key);
+    if (prior && (prior.state !== item.state || prior.attempts !== item.attempts)) {
+      return { ok: false, conflict: true, reason: `action history conflicts for ${item.key}` };
+    }
+    if (!prior) byKey.set(item.key, item);
+  }
+  return { ok: true, byKey };
+}
+
+function validateAutoActionAuthority(payload) {
+  if (!payload?.evidence || !Array.isArray(payload.evidence.unreadable)
+    || typeof payload.evidence.tornRead !== 'boolean') {
+    return { ok: false, reason: 'verdict evidence is incomplete' };
+  }
+  if (payload.draft !== false) {
+    return { ok: false, reason: 'non-draft authority is incomplete' };
+  }
+
+  const failuresByName = new Map();
+  for (const failure of Array.isArray(payload.failures) ? payload.failures : []) {
+    if (!failure || typeof failure.name !== 'string' || !failure.name) continue;
+    const evidence = {
+      conclusion: String(failure.conclusion || '').toUpperCase(),
+      url: failure.jobUrl || failure.detailsUrl || null,
+    };
+    const prior = failuresByName.get(failure.name);
+    if (prior && (prior.conclusion !== evidence.conclusion || prior.url !== evidence.url)) {
+      return { ok: false, conflict: true, reason: `required check evidence conflicts for ${failure.name}` };
+    }
+    if (!prior) failuresByName.set(failure.name, evidence);
+  }
+  return { ok: true };
+}
+
+function buildAutoActionCandidates(decision, subjectRevision) {
+  const candidates = [];
+  if (decision.updateBranch.should) {
+    candidates.push({ type: 'updateBranch', key: `updateBranch:${subjectRevision}`, subjectRevision });
+  }
+  if (decision.rerunFlaky.should) {
+    const runIds = [...decision.rerunFlaky.runIds].sort((left, right) => left.localeCompare(right));
+    for (const runId of runIds) {
+      candidates.push({
+        type: 'rerunFlaky',
+        key: `rerunFlaky:${subjectRevision}:${runId}`,
+        subjectRevision,
+        runId,
+      });
+    }
+  }
+  return candidates;
+}
+
+function selectBoundedActions(candidates, history, maxActions, maxAttempts) {
+  const actions = [];
+  for (const candidate of candidates) {
+    const prior = history.get(candidate.key);
+    if (prior && (prior.state === 'pending' || prior.state === 'applied' || prior.attempts >= maxAttempts)) continue;
+    actions.push({ ...candidate, attempt: prior ? prior.attempts + 1 : 1 });
+    if (actions.length === maxActions) break;
+  }
+  return actions;
+}
+
+/** Select a deterministic, per-head, bounded action/retry batch. */
+function decideBoundedAutoActions(payload, opts = {}) {
+  const closed = (status, reason) => ({ status, reason, actions: [] });
+  const subjectRevision = payload?.headSha;
+  if (typeof subjectRevision !== 'string' || !/^[0-9a-f]{40}$/i.test(subjectRevision)) {
+    return closed(AUTO_ACTION_STATUS.INCOMPLETE, 'exact head authority is incomplete');
+  }
+  if (opts.expectedRevision != null && opts.expectedRevision !== subjectRevision) {
+    return closed(AUTO_ACTION_STATUS.STALE, 'payload head does not match expected revision');
+  }
+  const authority = validateAutoActionAuthority(payload);
+  if (!authority.ok) {
+    return closed(authority.conflict ? AUTO_ACTION_STATUS.CONFLICT : AUTO_ACTION_STATUS.INCOMPLETE, authority.reason);
+  }
+  const maxActions = boundedPolicyValue(opts.maxActions, 1, MAX_AUTO_ACTIONS);
+  const maxAttempts = boundedPolicyValue(opts.maxAttempts, 2, MAX_AUTO_ATTEMPTS);
+  if (maxActions == null || maxAttempts == null) {
+    return closed(AUTO_ACTION_STATUS.INCOMPLETE, 'auto-action policy exceeds bounded limits');
+  }
+  const history = normalizeActionHistory(opts.history || []);
+  if (!history.ok) {
+    return closed(history.conflict ? AUTO_ACTION_STATUS.CONFLICT : AUTO_ACTION_STATUS.INCOMPLETE, history.reason);
+  }
+
+  const decision = decideAutoActions(payload, opts);
+  if (decision.updateBranch.should && decision.rerunFlaky.should) {
+    return closed(AUTO_ACTION_STATUS.CONFLICT, 'payload authorizes conflicting update and rerun actions');
+  }
+
+  const candidates = buildAutoActionCandidates(decision, subjectRevision);
+  const actions = selectBoundedActions(candidates, history.byKey, maxActions, maxAttempts);
+  if (actions.length === 0) {
+    return closed(AUTO_ACTION_STATUS.UNCHANGED, candidates.length === 0
+      ? 'no safe auto-action transition'
+      : 'identical actions are pending, applied, or retry-exhausted');
+  }
+  return { status: AUTO_ACTION_STATUS.PASS, reason: 'bounded auto-actions selected', actions };
+}
+
 module.exports = {
   decideAutoActions,
   decideUpdateBranch,
@@ -172,4 +311,6 @@ module.exports = {
   isDegraded,
   INFRA_CONCLUSIONS,
   REAL_FAILURE_CONCLUSIONS,
+  AUTO_ACTION_STATUS,
+  decideBoundedAutoActions,
 };