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

package/lib/protected-state-authority.js

@@ -8,13 +8,66 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { resolveOwnedKernel, closeIfOwned } = require('./kernel/owned-kernel');
 const { hashProtectedContent, normalizeRepoPath } = require('./protected-state-surfaces');
+const {
+	BUN_WORKFLOW_SPECS,
+	deriveBunWorkflowUpdate,
+	readIndexedPackageManifest,
+	readIndexedWorkflow,
+	readPinnedBunVersion,
+	readSourcePackageManifest,
+	readSourceWorkflow,
+	renderBunWorkflowPin,
+	resolveBunVersionTarget,
+	resolveCurrentHead,
+} = require('./bun-workflow-pins');
 
 const PROTECTED_STATE_ENTITY_TYPE = 'protected_state';
 const PROTECTED_STATE_AUTHORIZATION_ISSUED = 'protected_state.authorization.issued';
+const PROTECTED_STATE_WRITE_COMPLETED = 'protected_state.write.completed';
 const PROTECTED_STATE_AUTHORIZATION_CONSUMED = 'protected_state.authorization.consumed';
 const PROTECTED_STATE_AUTHORIZATION_VERSION = 1;
 const PROTECTED_STATE_AUTHORIZATION_ORIGIN = 'cli';
 const NPM_WORKFLOW_SOURCE_COMMAND = 'forge release generate-npm-workflow';
+const BUN_WORKFLOW_SOURCE_COMMAND = 'forge release update-bun-pins';
+const BUN_WORKFLOW_PATHS = new Set(BUN_WORKFLOW_SPECS.map(spec => spec.path));
+const SKILL_MIRROR_SOURCE_COMMAND = 'scripts/sync-agent-skills.js';
+const CLAUDE_SETUP_SOURCE_COMMAND = 'forge setup';
+
+function isValidGitObjectId(value) {
+	return typeof value === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(value);
+}
+
+function owningWriter(pathname, surface) {
+	if (surface === 'workflows' && BUN_WORKFLOW_PATHS.has(pathname)) {
+		return {
+			sourceCommand: BUN_WORKFLOW_SOURCE_COMMAND,
+			issueOperation: 'update_bun_workflow_pin',
+			completionOperation: 'update_bun_workflow_pin_completed',
+		};
+	}
+	if (surface === 'workflows' && pathname === '.github/workflows/npm-publish.yml') {
+		return {
+			sourceCommand: NPM_WORKFLOW_SOURCE_COMMAND,
+			issueOperation: 'generate_npm_workflow',
+			completionOperation: 'generate_npm_workflow_completed',
+		};
+	}
+	if (surface === 'generated_harness' && /^\.agents\/skills\/[^/]+\/.+/.test(pathname)) {
+		return {
+			sourceCommand: SKILL_MIRROR_SOURCE_COMMAND,
+			issueOperation: 'sync_agent_skill',
+			completionOperation: 'sync_agent_skill_completed',
+		};
+	}
+	if (surface === 'generated_harness' && pathname === 'CLAUDE.md') {
+		return {
+			sourceCommand: CLAUDE_SETUP_SOURCE_COMMAND,
+			issueOperation: 'generate_claude_import',
+			completionOperation: 'generate_claude_import_completed',
+		};
+	}
+	return null;
+}
 
 function resolveWorktreeScope(projectRoot, deps = {}) {
 	const resolved = path.resolve(projectRoot);
@@ -56,8 +109,12 @@ function parseAuthorizationEvent(row) {
 		surface: payload.surface,
 		contentHash: payload.contentHash,
 		operation: payload.operation,
+		viaForgeApi: payload.viaForgeApi === true,
 		sourceCommand: payload.sourceCommand,
+		sourceHead: payload.sourceHead,
 		worktreeScope: payload.worktreeScope,
+		writeIntent: payload.writeIntent,
+		targetBunVersion: payload.targetBunVersion,
 	};
 }
 
@@ -71,6 +128,7 @@ function blockedDecision(request, reason) {
 		requiredSurface: request.surface,
 		declaredSurface: request.surface,
 		contentHash: hashProtectedContent(request.content),
+		sourceHead: request.sourceHead,
 		reason,
 		repairHint: 'Regenerate the protected file through its owning Forge command, then stage that exact output.',
 	};
@@ -83,6 +141,8 @@ function evaluateAuthorization(request, rows = []) {
 		surface: request.surface,
 		contentHash: hashProtectedContent(request.content),
 		worktreeScope: request.worktreeScope,
+		sourceHead: request.sourceHead,
+		writeIntent: request.operation === 'staged_delete' ? 'delete' : 'update',
 	};
 	const issued = rows
 		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
@@ -103,15 +163,23 @@ function evaluateAuthorization(request, rows = []) {
 		return blockedDecision(request, 'Protected-state authority is ambiguous because multiple unconsumed authorizations exist; failing closed.');
 	}
 	const latest = active[0];
+	const writer = owningWriter(latest.path, latest.surface);
 
+	const bunPinWriter = [BUN_WORKFLOW_SOURCE_COMMAND, NPM_WORKFLOW_SOURCE_COMMAND].includes(writer?.sourceCommand);
 	const structurallyValid =
+		writer !== null &&
 		latest.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
 		typeof latest.capabilityId === 'string' && latest.capabilityId.length > 0 &&
 		latest.origin === PROTECTED_STATE_AUTHORIZATION_ORIGIN &&
 		latest.actor === latest.payloadActor &&
 		latest.worktreeScope === expected.worktreeScope &&
 		latest.entityId === authorizationEntityId(expected.worktreeScope, latest.path) &&
-		latest.sourceCommand === NPM_WORKFLOW_SOURCE_COMMAND;
+		latest.viaForgeApi === true &&
+		latest.sourceCommand === writer?.sourceCommand &&
+		latest.operation === writer?.issueOperation &&
+		latest.writeIntent === expected.writeIntent &&
+		isValidGitObjectId(latest.sourceHead) &&
+		(!bunPinWriter || /^\d+\.\d+\.\d+$/.test(latest.targetBunVersion));
 	if (!structurallyValid) {
 		return blockedDecision(request, 'The latest Forge-owned authorization is malformed or was not issued by the owning command.');
 	}
@@ -120,9 +188,36 @@ function evaluateAuthorization(request, rows = []) {
 		latest.actor !== expected.actor ||
 		latest.path !== expected.path ||
 		latest.surface !== expected.surface ||
-		latest.contentHash !== expected.contentHash
+		latest.contentHash !== expected.contentHash ||
+		latest.sourceHead !== expected.sourceHead ||
+		latest.writeIntent !== expected.writeIntent
 	) {
-		return blockedDecision(request, 'The latest Forge-owned content-bound authorization does not match this actor, surface, path, and content hash.');
+		return blockedDecision(request, 'The latest Forge-owned authorization does not match this actor, surface, path, content hash, and source HEAD.');
+	}
+
+	const matchingCompletions = rows
+		.filter(row => row?.event_type === PROTECTED_STATE_WRITE_COMPLETED)
+		.map(parseAuthorizationEvent)
+		.filter(event =>
+			event.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
+			event.capabilityId === latest.capabilityId &&
+			event.origin === PROTECTED_STATE_AUTHORIZATION_ORIGIN &&
+			event.actor === latest.actor &&
+			event.payloadActor === latest.payloadActor &&
+			event.entityId === latest.entityId &&
+			event.path === latest.path &&
+			event.surface === latest.surface &&
+			event.contentHash === latest.contentHash &&
+			event.sourceHead === latest.sourceHead &&
+			event.worktreeScope === latest.worktreeScope &&
+			event.writeIntent === latest.writeIntent &&
+			event.operation === writer.completionOperation &&
+			event.viaForgeApi === true &&
+			event.sourceCommand === writer.sourceCommand
+			&& event.targetBunVersion === latest.targetBunVersion
+		);
+	if (matchingCompletions.length !== 1) {
+		return blockedDecision(request, 'The latest Forge-owned authorization is not completed by its owning writer; failing closed.');
 	}
 
 	return {
@@ -134,8 +229,11 @@ function evaluateAuthorization(request, rows = []) {
 		requiredSurface: expected.surface,
 		declaredSurface: expected.surface,
 		contentHash: expected.contentHash,
+		sourceHead: expected.sourceHead,
+		viaForgeApi: true,
 		capabilityId: latest.capabilityId,
 		worktreeScope: latest.worktreeScope,
+		targetBunVersion: latest.targetBunVersion,
 		reason: 'Staged content matches the latest unconsumed Forge-owned authorization.',
 		repairHint: null,
 	};
@@ -169,7 +267,11 @@ async function issueProtectedStateAuthorization(projectRoot, request = {}, optio
 			contentHash: hashProtectedContent(request.content),
 			worktreeScope,
 			operation: request.operation || 'generate',
+			viaForgeApi: request.viaForgeApi === true,
 			sourceCommand: request.sourceCommand || NPM_WORKFLOW_SOURCE_COMMAND,
+			...(request.sourceHead ? { sourceHead: request.sourceHead } : {}),
+			...(request.targetBunVersion ? { targetBunVersion: request.targetBunVersion } : {}),
+			writeIntent: request.writeIntent || 'update',
 		},
 		created_at: createdAt,
 	};
@@ -182,6 +284,10 @@ async function issueProtectedStateAuthorization(projectRoot, request = {}, optio
 			{},
 			kernel.config,
 		);
+		if (request.verifyBeforeInsert) {
+			const verification = await request.verifyBeforeInsert();
+			if (!verification?.success) return verification || { success: false, error: 'Protected-state source changed during authorization.' };
+		}
 		const consumedCapabilities = new Set((existingRows || [])
 			.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_CONSUMED)
 			.map(row => parseAuthorizationEvent(row).capabilityId)
@@ -206,13 +312,19 @@ async function issueProtectedStateAuthorization(projectRoot, request = {}, optio
 					path: normalizedPath,
 					surface: existing.surface,
 					contentHash: existing.contentHash,
+					sourceHead: existing.sourceHead,
 					worktreeScope,
 					operation: 'superseded',
+					viaForgeApi: existing.viaForgeApi === true,
 					sourceCommand: request.sourceCommand || NPM_WORKFLOW_SOURCE_COMMAND,
 				},
 				created_at: createdAt,
 			}, {}, kernel.config);
 		}
+		if (request.verifyBeforeInsert) {
+			const verification = await request.verifyBeforeInsert();
+			if (!verification?.success) return verification || { success: false, error: 'Protected-state source changed during authorization.' };
+		}
 		const inserted = await kernel.driver.insertKernelEvent(event, {}, kernel.config);
 		return { success: true, capabilityId, event: parseAuthorizationEvent(inserted) };
 	} finally {
@@ -220,22 +332,687 @@ async function issueProtectedStateAuthorization(projectRoot, request = {}, optio
 	}
 }
 
+function resolveCurrentBunWorkflowTarget(projectRoot, params, requireWritten = false) {
+	let currentHead;
+	try {
+		currentHead = resolveCurrentHead(projectRoot);
+	} catch (error) {
+		return { success: false, error: `Could not resolve current HEAD: ${error.message}` };
+	}
+	if (currentHead !== params.sourceHead) {
+		return { success: false, error: `Protected Bun workflow source HEAD changed from ${params.sourceHead} to ${currentHead}.` };
+	}
+
+	let update;
+	try {
+		const target = resolveBunVersionTarget(projectRoot);
+		if (params.targetBunVersion !== target.version) {
+			return { success: false, error: 'Protected Bun workflow target does not match the staged package.json Bun pin.' };
+		}
+		update = deriveBunWorkflowUpdate(projectRoot, params.sourceHead, params.path, { version: target.version });
+		if (requireWritten) {
+			const fullPath = path.join(projectRoot, update.path);
+			const stat = fs.lstatSync(fullPath);
+			if (!stat.isFile() || stat.isSymbolicLink() || !fs.readFileSync(fullPath).equals(update.content)) {
+				return { success: false, error: 'Protected Bun workflow completion requires the exact generated workflow bytes.' };
+			}
+		}
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	return { success: true, update };
+}
+
+function resolveBoundNpmBunTarget(projectRoot, params) {
+	if (!/^\d+\.\d+\.\d+$/.test(params.targetBunVersion || '')
+		|| params.bunVersion !== params.targetBunVersion
+		|| resolveBunVersionTarget(projectRoot).version !== params.targetBunVersion) {
+		return { success: false, error: 'Protected npm workflow target does not match the staged package.json Bun pin.' };
+	}
+	return { success: true, version: params.targetBunVersion };
+}
+
 async function issueNpmPublishWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead)) {
+		return {
+			success: false,
+			error: 'Protected npm workflow authorization requires a full 40- or 64-character lowercase source HEAD.',
+		};
+	}
 	const {
 		NPM_PUBLISH_WORKFLOW_PATH,
 		renderNpmPublishWorkflow,
 	} = require('./npm-publish-workflow');
+	let content;
+	try {
+		const target = resolveBoundNpmBunTarget(projectRoot, params);
+		if (!target.success) return target;
+		content = renderNpmPublishWorkflow(params.bunVersion);
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
 	return issueProtectedStateAuthorization(projectRoot, {
 		actor: params.actor,
 		surface: 'workflows',
 		path: NPM_PUBLISH_WORKFLOW_PATH,
-		content: renderNpmPublishWorkflow(),
+		content,
 		operation: 'generate_npm_workflow',
+		viaForgeApi: true,
 		sourceCommand: NPM_WORKFLOW_SOURCE_COMMAND,
+		sourceHead: params.sourceHead,
+		targetBunVersion: params.targetBunVersion,
+		verifyBeforeInsert: () => {
+			try {
+				return resolveBoundNpmBunTarget(projectRoot, params).success
+					? { success: true }
+					: { success: false, error: 'Protected npm workflow target changed during authorization.' };
+			} catch (error) {
+				return { success: false, error: error.message };
+			}
+		},
 	}, options);
 }
 
+async function issueBunWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead) || !BUN_WORKFLOW_PATHS.has(params.path)) {
+		return {
+			success: false,
+			error: 'Protected Bun workflow authorization requires an allowlisted path and a full 40- or 64-character lowercase source HEAD.',
+		};
+	}
+	const target = resolveCurrentBunWorkflowTarget(projectRoot, params);
+	if (!target.success) return target;
+	const { update } = target;
+	const expectedHash = hashProtectedContent(update.content);
+	return issueProtectedStateAuthorization(projectRoot, {
+		actor: params.actor,
+		surface: 'workflows',
+		path: update.path,
+		content: update.content,
+		operation: 'update_bun_workflow_pin',
+		viaForgeApi: true,
+		sourceCommand: BUN_WORKFLOW_SOURCE_COMMAND,
+		sourceHead: params.sourceHead,
+		verifyBeforeInsert: () => {
+			const fresh = resolveCurrentBunWorkflowTarget(projectRoot, params);
+			if (!fresh.success) return fresh;
+			return hashProtectedContent(fresh.update.content) === expectedHash
+				? { success: true }
+				: { success: false, error: 'Protected Bun workflow target changed during authorization.' };
+		},
+		targetBunVersion: params.targetBunVersion,
+	}, options);
+}
+
+function findExactAuthorization(rows, params, expected) {
+	const issued = (rows || [])
+		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
+		.map(parseAuthorizationEvent)
+		.find(event => event.capabilityId === params.capabilityId);
+	const consumed = (rows || [])
+		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_CONSUMED)
+		.map(parseAuthorizationEvent)
+		.some(event => event.capabilityId === params.capabilityId);
+	const exactIssued = issued?.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
+		issued.origin === PROTECTED_STATE_AUTHORIZATION_ORIGIN &&
+		issued.actor === expected.actor && issued.payloadActor === expected.actor &&
+		issued.entityId === expected.entityId && issued.path === expected.path &&
+		issued.surface === expected.surface && issued.contentHash === expected.contentHash &&
+		issued.sourceHead === params.sourceHead && issued.worktreeScope === expected.worktreeScope &&
+		issued.operation === expected.operation && issued.viaForgeApi === true &&
+		issued.writeIntent === expected.writeIntent && issued.sourceCommand === expected.sourceCommand;
+	const targetMatches = expected.targetBunVersion === undefined
+		|| issued.targetBunVersion === expected.targetBunVersion;
+	return { exactIssued: exactIssued && targetMatches, consumed };
+}
+
+async function completeNpmPublishWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead)) {
+		return {
+			success: false,
+			error: 'Protected npm workflow completion requires a full 40- or 64-character lowercase source HEAD.',
+		};
+	}
+	if (typeof params.capabilityId !== 'string' || params.capabilityId.length === 0) {
+		return { success: false, error: 'Protected npm workflow completion requires a capability id.' };
+	}
+
+	const {
+		NPM_PUBLISH_WORKFLOW_PATH,
+		renderNpmPublishWorkflow,
+	} = require('./npm-publish-workflow');
+	const actor = params.actor;
+	const normalizedPath = normalizeRepoPath(NPM_PUBLISH_WORKFLOW_PATH);
+	let contentHash;
+	try {
+		const target = resolveBoundNpmBunTarget(projectRoot, params);
+		if (!target.success) return target;
+		contentHash = hashProtectedContent(renderNpmPublishWorkflow(params.bunVersion));
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+	const createdAt = options.now || new Date().toISOString();
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const rows = await kernel.driver.listKernelEvents(
+			PROTECTED_STATE_ENTITY_TYPE,
+			entityId,
+			{},
+			kernel.config,
+		);
+		const { exactIssued, consumed } = findExactAuthorization(rows, params, {
+			actor,
+			entityId,
+			path: normalizedPath,
+			surface: 'workflows',
+			contentHash,
+			worktreeScope,
+			operation: 'generate_npm_workflow',
+			writeIntent: 'update',
+			sourceCommand: NPM_WORKFLOW_SOURCE_COMMAND,
+			targetBunVersion: params.targetBunVersion,
+		});
+		if (!exactIssued || consumed) {
+			return {
+				success: false,
+				error: 'Protected npm workflow completion does not match one active exact authorization.',
+			};
+		}
+		try {
+			if (!resolveBoundNpmBunTarget(projectRoot, params).success) {
+				return { success: false, error: 'Protected npm workflow target changed during completion.' };
+			}
+		} catch (error) {
+			return { success: false, error: error.message };
+		}
+
+		const event = {
+			entity_type: PROTECTED_STATE_ENTITY_TYPE,
+			entity_id: entityId,
+			event_type: PROTECTED_STATE_WRITE_COMPLETED,
+			idempotency_key: `${PROTECTED_STATE_WRITE_COMPLETED}:${params.capabilityId}`,
+			expected_revision: 0,
+			actor,
+			origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+			payload: {
+				version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+				capabilityId: params.capabilityId,
+				actor,
+				path: normalizedPath,
+				surface: 'workflows',
+				contentHash,
+				sourceHead: params.sourceHead,
+				worktreeScope,
+				writeIntent: 'update',
+				operation: 'generate_npm_workflow_completed',
+				viaForgeApi: true,
+				sourceCommand: NPM_WORKFLOW_SOURCE_COMMAND,
+				targetBunVersion: params.targetBunVersion,
+			},
+			created_at: createdAt,
+		};
+		const inserted = await kernel.driver.insertKernelEvent(event, {}, kernel.config);
+		return { success: true, capabilityId: params.capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+async function completeBunWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead) || !BUN_WORKFLOW_PATHS.has(params.path)) {
+		return {
+			success: false,
+			error: 'Protected Bun workflow completion requires an allowlisted path and a full 40- or 64-character lowercase source HEAD.',
+		};
+	}
+	if (typeof params.capabilityId !== 'string' || params.capabilityId.length === 0) {
+		return { success: false, error: 'Protected Bun workflow completion requires a capability id.' };
+	}
+
+	const target = resolveCurrentBunWorkflowTarget(projectRoot, params, true);
+	if (!target.success) return target;
+	const { update } = target;
+
+	const actor = params.actor;
+	const normalizedPath = normalizeRepoPath(update.path);
+	const contentHash = hashProtectedContent(update.content);
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+	const createdAt = options.now || new Date().toISOString();
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const rows = await kernel.driver.listKernelEvents(
+			PROTECTED_STATE_ENTITY_TYPE,
+			entityId,
+			{},
+			kernel.config,
+		);
+		const { exactIssued, consumed } = findExactAuthorization(rows, params, {
+			actor,
+			entityId,
+			path: normalizedPath,
+			surface: 'workflows',
+			contentHash,
+			worktreeScope,
+			operation: 'update_bun_workflow_pin',
+			writeIntent: 'update',
+			sourceCommand: BUN_WORKFLOW_SOURCE_COMMAND,
+			targetBunVersion: params.targetBunVersion,
+		});
+		if (!exactIssued || consumed) {
+			return {
+				success: false,
+				error: 'Protected Bun workflow completion does not match one active exact authorization.',
+			};
+		}
+		const fresh = resolveCurrentBunWorkflowTarget(projectRoot, params, true);
+		if (!fresh.success) return fresh;
+		if (hashProtectedContent(fresh.update.content) !== contentHash) {
+			return { success: false, error: 'Protected Bun workflow target changed during completion.' };
+		}
+
+		const event = {
+			entity_type: PROTECTED_STATE_ENTITY_TYPE,
+			entity_id: entityId,
+			event_type: PROTECTED_STATE_WRITE_COMPLETED,
+			idempotency_key: `${PROTECTED_STATE_WRITE_COMPLETED}:${params.capabilityId}`,
+			expected_revision: 0,
+			actor,
+			origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+			payload: {
+				version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+				capabilityId: params.capabilityId,
+				actor,
+				path: normalizedPath,
+				surface: 'workflows',
+				contentHash,
+				sourceHead: params.sourceHead,
+				worktreeScope,
+				writeIntent: 'update',
+				operation: 'update_bun_workflow_pin_completed',
+				viaForgeApi: true,
+				sourceCommand: BUN_WORKFLOW_SOURCE_COMMAND,
+				targetBunVersion: params.targetBunVersion,
+			},
+			created_at: createdAt,
+		};
+		const inserted = await kernel.driver.insertKernelEvent(event, {}, kernel.config);
+		return { success: true, capabilityId: params.capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+async function cancelBunWorkflowBatchAuthorizations(projectRoot, requests = [], options = {}) {
+	if (requests.length === 0) return { success: true, results: [] };
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	const results = [];
+	try {
+		for (const request of requests) {
+			const normalizedPath = normalizeRepoPath(request.path);
+			const writer = owningWriter(normalizedPath, 'workflows');
+			if (!request.actor || !isValidGitObjectId(request.sourceHead) || !request.capabilityId ||
+				!writer || ![BUN_WORKFLOW_SOURCE_COMMAND, NPM_WORKFLOW_SOURCE_COMMAND].includes(writer.sourceCommand)) {
+				results.push({ success: false, path: normalizedPath, capabilityId: request.capabilityId, error: 'Invalid Bun workflow batch cancellation request.' });
+				continue;
+			}
+			try {
+				const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+				const rows = await kernel.driver.listKernelEvents(PROTECTED_STATE_ENTITY_TYPE, entityId, {}, kernel.config);
+				const events = (rows || []).map(parseAuthorizationEvent);
+				const issued = events.find(event =>
+					event.eventType === PROTECTED_STATE_AUTHORIZATION_ISSUED &&
+					event.capabilityId === request.capabilityId
+				);
+				if (!issued) {
+					results.push({ success: true, path: normalizedPath, capabilityId: request.capabilityId, status: 'not-issued' });
+					continue;
+				}
+				const exact = issued.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
+					issued.origin === PROTECTED_STATE_AUTHORIZATION_ORIGIN &&
+					issued.actor === request.actor && issued.payloadActor === request.actor &&
+					issued.entityId === entityId && issued.path === normalizedPath &&
+					issued.surface === 'workflows' && issued.sourceHead === request.sourceHead &&
+					issued.worktreeScope === worktreeScope && issued.operation === writer.issueOperation &&
+					issued.viaForgeApi === true && issued.writeIntent === 'update' &&
+					issued.sourceCommand === writer.sourceCommand;
+				if (!exact) {
+					results.push({ success: false, path: normalizedPath, capabilityId: request.capabilityId, error: 'Capability does not match this Bun workflow batch.' });
+					continue;
+				}
+				if (events.some(event => event.eventType === PROTECTED_STATE_AUTHORIZATION_CONSUMED && event.capabilityId === request.capabilityId)) {
+					results.push({ success: true, path: normalizedPath, capabilityId: request.capabilityId, status: 'already-consumed' });
+					continue;
+				}
+				await kernel.driver.insertKernelEvent({
+					entity_type: PROTECTED_STATE_ENTITY_TYPE,
+					entity_id: entityId,
+					event_type: PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+					idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_CONSUMED}:${request.capabilityId}`,
+					expected_revision: 0,
+					actor: request.actor,
+					origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+					payload: {
+						version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+						capabilityId: request.capabilityId,
+						actor: request.actor,
+						path: normalizedPath,
+						surface: 'workflows',
+						contentHash: issued.contentHash,
+						sourceHead: request.sourceHead,
+						worktreeScope,
+						writeIntent: 'update',
+						operation: 'batch_rollback',
+						viaForgeApi: true,
+						sourceCommand: BUN_WORKFLOW_SOURCE_COMMAND,
+					},
+					created_at: options.now || new Date().toISOString(),
+				}, {}, kernel.config);
+				results.push({ success: true, path: normalizedPath, capabilityId: request.capabilityId, status: 'consumed' });
+			} catch (error) {
+				results.push({ success: false, path: normalizedPath, capabilityId: request.capabilityId, error: error.message });
+			}
+		}
+		return { success: results.every(result => result.success), results };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+const CLAUDE_POINTER_CONTENT = Buffer.from('@AGENTS.md\n');
+const CLAUDE_POINTER_CRLF_CONTENT = Buffer.from('@AGENTS.md\r\n');
+
+function isExactClaudePointer(content) {
+	const bytes = Buffer.from(content || '');
+	return bytes.equals(Buffer.from('@AGENTS.md')) || bytes.equals(CLAUDE_POINTER_CONTENT) || bytes.equals(CLAUDE_POINTER_CRLF_CONTENT);
+}
+
+async function issueGeneratedHarnessClaudeAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead) || !isExactClaudePointer(params.content)) {
+		return {
+			success: false,
+			error: 'Root CLAUDE.md authorization requires exact @AGENTS.md pointer bytes and a full 40- or 64-character source HEAD.',
+		};
+	}
+	const content = Buffer.from(params.content || CLAUDE_POINTER_CONTENT);
+	return issueProtectedStateAuthorization(projectRoot, {
+		actor: params.actor,
+		surface: 'generated_harness',
+		path: 'CLAUDE.md',
+		content,
+		operation: 'generate_claude_import',
+		viaForgeApi: true,
+		sourceCommand: CLAUDE_SETUP_SOURCE_COMMAND,
+		sourceHead: params.sourceHead,
+	}, options);
+}
+
+async function completeGeneratedHarnessClaudeAuthorization(projectRoot, params = {}, options = {}) {
+	const content = Buffer.from(params.content || CLAUDE_POINTER_CONTENT);
+	if (!isValidGitObjectId(params.sourceHead) || !params.capabilityId || !isExactClaudePointer(content)) {
+		return { success: false, error: 'Root CLAUDE.md completion requires a capability id and full 40- or 64-character source HEAD.' };
+	}
+	const actor = params.actor;
+	const normalizedPath = 'CLAUDE.md';
+	const contentHash = hashProtectedContent(content);
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const rows = await kernel.driver.listKernelEvents(PROTECTED_STATE_ENTITY_TYPE, entityId, {}, kernel.config);
+		const { exactIssued, consumed } = findExactAuthorization(rows, params, {
+			actor,
+			entityId,
+			path: normalizedPath,
+			surface: 'generated_harness',
+			contentHash,
+			worktreeScope,
+			operation: 'generate_claude_import',
+			writeIntent: 'update',
+			sourceCommand: CLAUDE_SETUP_SOURCE_COMMAND,
+		});
+		if (!exactIssued || consumed) {
+			return { success: false, error: 'Root CLAUDE.md completion does not match one active exact authorization.' };
+		}
+		const inserted = await kernel.driver.insertKernelEvent({
+			entity_type: PROTECTED_STATE_ENTITY_TYPE,
+			entity_id: entityId,
+			event_type: PROTECTED_STATE_WRITE_COMPLETED,
+			idempotency_key: `${PROTECTED_STATE_WRITE_COMPLETED}:${params.capabilityId}`,
+			expected_revision: 0,
+			actor,
+			origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+			payload: {
+				version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+				capabilityId: params.capabilityId,
+				actor,
+				path: normalizedPath,
+				surface: 'generated_harness',
+				contentHash,
+				sourceHead: params.sourceHead,
+				worktreeScope,
+				writeIntent: 'update',
+				operation: 'generate_claude_import_completed',
+				viaForgeApi: true,
+				sourceCommand: CLAUDE_SETUP_SOURCE_COMMAND,
+			},
+			created_at: options.now || new Date().toISOString(),
+		}, {}, kernel.config);
+		return { success: true, capabilityId: params.capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+function resolveCanonicalSkillMirror(projectRoot, mirrorPath, options = {}) {
+	const normalizedPath = normalizeRepoPath(mirrorPath);
+	const match = /^\.agents\/skills\/([^/]+)\/(.+)$/.exec(normalizedPath);
+	if (!match || match[1] === '.' || match[1] === '..') return null;
+	const segments = match[2].split('/');
+	if (segments.some(segment => !segment || segment === '.' || segment === '..')) return null;
+	const skillRoot = path.resolve(projectRoot, 'skills', match[1]);
+	const canonicalPath = path.resolve(skillRoot, match[2]);
+	if (canonicalPath !== skillRoot && !canonicalPath.startsWith(`${skillRoot}${path.sep}`)) return null;
+	try {
+		const skillsRoot = path.resolve(projectRoot, 'skills');
+		const skillsStat = fs.lstatSync(skillsRoot);
+		if (!skillsStat.isDirectory() || skillsStat.isSymbolicLink()) return null;
+		const rootStat = fs.lstatSync(skillRoot);
+		if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return null;
+		let ancestor = skillRoot;
+		for (const segment of segments.slice(0, -1)) {
+			ancestor = path.join(ancestor, segment);
+			const ancestorStat = fs.lstatSync(ancestor);
+			if (!ancestorStat.isDirectory() || ancestorStat.isSymbolicLink()) return null;
+		}
+		const stat = fs.lstatSync(canonicalPath);
+		if (!stat.isFile() || stat.isSymbolicLink()) return null;
+		return { normalizedPath, content: fs.readFileSync(canonicalPath) };
+	} catch (error) {
+		if (options.allowMissing === true && error.code === 'ENOENT' && Buffer.isBuffer(options.priorContent)) {
+			return { normalizedPath, content: options.priorContent, missing: true };
+		}
+		return null;
+	}
+}
+
+async function issueGeneratedHarnessSkillAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead)) {
+		return { success: false, error: 'Protected skill mirror authorization requires a full 40- or 64-character lowercase source HEAD.' };
+	}
+	const writeIntent = params.writeIntent === 'delete' ? 'delete' : 'update';
+	const canonical = resolveCanonicalSkillMirror(projectRoot, params.path, {
+		allowMissing: writeIntent === 'delete',
+		priorContent: params.priorContent,
+	});
+	if (!canonical) {
+		return { success: false, error: 'Protected skill mirror authorization requires a canonical .agents/skills/<name>/<file> path.' };
+	}
+	if (writeIntent === 'delete' && canonical.missing !== true) {
+		return { success: false, error: 'Protected skill mirror deletion authorization requires the canonical source to be absent.' };
+	}
+	return issueProtectedStateAuthorization(projectRoot, {
+		actor: params.actor,
+		surface: 'generated_harness',
+		path: canonical.normalizedPath,
+		content: canonical.content,
+		operation: 'sync_agent_skill',
+		viaForgeApi: true,
+		sourceCommand: SKILL_MIRROR_SOURCE_COMMAND,
+		sourceHead: params.sourceHead,
+		writeIntent,
+	}, options);
+}
+
+async function completeGeneratedHarnessSkillAuthorization(projectRoot, params = {}, options = {}) {
+	if (!isValidGitObjectId(params.sourceHead) || !params.capabilityId) {
+		return { success: false, error: 'Protected skill mirror completion requires a capability id and full 40- or 64-character source HEAD.' };
+	}
+	const writeIntent = params.writeIntent === 'delete' ? 'delete' : 'update';
+	const canonical = resolveCanonicalSkillMirror(projectRoot, params.path, {
+		allowMissing: writeIntent === 'delete',
+		priorContent: params.priorContent,
+	});
+	if (!canonical) {
+		return { success: false, error: 'Protected skill mirror completion requires a canonical .agents/skills/<name>/<file> path.' };
+	}
+	if (writeIntent === 'delete' && canonical.missing !== true) {
+		return { success: false, error: 'Protected skill mirror deletion completion requires the canonical source to be absent.' };
+	}
+	const actor = params.actor;
+	const contentHash = hashProtectedContent(canonical.content);
+	const mirrorTarget = path.resolve(projectRoot, canonical.normalizedPath);
+	if (writeIntent === 'delete' && fs.existsSync(mirrorTarget)) {
+		return { success: false, error: 'Protected skill mirror deletion completion requires the exact mirror path to be absent.' };
+	}
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, canonical.normalizedPath);
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const rows = await kernel.driver.listKernelEvents(PROTECTED_STATE_ENTITY_TYPE, entityId, {}, kernel.config);
+		const { exactIssued, consumed } = findExactAuthorization(rows, params, {
+			actor,
+			entityId,
+			path: canonical.normalizedPath,
+			surface: 'generated_harness',
+			contentHash,
+			worktreeScope,
+			operation: 'sync_agent_skill',
+			writeIntent,
+			sourceCommand: SKILL_MIRROR_SOURCE_COMMAND,
+		});
+		if (!exactIssued || consumed) {
+			return { success: false, error: 'Protected skill mirror completion does not match one active exact authorization.' };
+		}
+		const inserted = await kernel.driver.insertKernelEvent({
+			entity_type: PROTECTED_STATE_ENTITY_TYPE,
+			entity_id: entityId,
+			event_type: PROTECTED_STATE_WRITE_COMPLETED,
+			idempotency_key: `${PROTECTED_STATE_WRITE_COMPLETED}:${params.capabilityId}`,
+			expected_revision: 0,
+			actor,
+			origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+			payload: {
+				version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+				capabilityId: params.capabilityId,
+				actor,
+				path: canonical.normalizedPath,
+				surface: 'generated_harness',
+				contentHash,
+				sourceHead: params.sourceHead,
+				worktreeScope,
+				writeIntent,
+				operation: 'sync_agent_skill_completed',
+				viaForgeApi: true,
+				sourceCommand: SKILL_MIRROR_SOURCE_COMMAND,
+			},
+			created_at: options.now || new Date().toISOString(),
+		}, {}, kernel.config);
+		return { success: true, capabilityId: params.capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+function validateBunDecisionTargets(projectRoot, decisions) {
+	const bunDecisions = decisions.filter(decision => decision.allowed && decision.targetBunVersion);
+	if (bunDecisions.length === 0) return;
+	let stagedVersion;
+	try {
+		stagedVersion = resolveBunVersionTarget(projectRoot).version;
+	} catch (error) {
+		for (const decision of bunDecisions) Object.assign(decision, { allowed: false, decision: 'blocked', reason: error.message });
+		return;
+	}
+	for (const decision of bunDecisions) {
+		if (decision.targetBunVersion !== stagedVersion) {
+			Object.assign(decision, { allowed: false, decision: 'blocked', reason: 'The staged package.json Bun pin changed after workflow generation.' });
+		}
+	}
+}
+
+function validateCompleteBunPinBatch(projectRoot, options = {}) {
+	if (options.sourceHead === null) return { success: true };
+	let sourceHead;
+	let sourcePackage;
+	try {
+		sourceHead = options.sourceHead || resolveCurrentHead(projectRoot);
+		sourcePackage = Buffer.from((options.readSourcePackageManifest || readSourcePackageManifest)(projectRoot, sourceHead));
+	} catch (error) {
+		if (error.message.includes('package.json is not a regular file at')) return { success: true };
+		return { success: false, error: `Could not verify the complete staged Bun pin update: ${error.message}` };
+	}
+	try {
+		if (JSON.parse(sourcePackage.toString('utf8')).name !== 'forge-workflow') return { success: true };
+		const sourceVersion = readPinnedBunVersion(sourcePackage);
+		const indexedPackage = Buffer.from((options.readIndexedPackageManifest || readIndexedPackageManifest)(projectRoot));
+		const targetVersion = readPinnedBunVersion(indexedPackage);
+		if (targetVersion === sourceVersion) return { success: true };
+		if (resolveBunVersionTarget(projectRoot, options).version !== targetVersion) {
+			return { success: false, error: 'The working package.json Bun pin differs from the staged pin.' };
+		}
+
+		for (const spec of BUN_WORKFLOW_SPECS) {
+			const baseline = (options.readSourceWorkflow || readSourceWorkflow)(projectRoot, sourceHead, spec.path);
+			const expected = Buffer.from(renderBunWorkflowPin(spec.path, baseline, targetVersion));
+			const indexed = Buffer.from((options.readIndexedWorkflow || readIndexedWorkflow)(projectRoot, spec.path));
+			if (!indexed.equals(expected)) {
+				return { success: false, error: `A staged Bun pin change requires the complete generated workflow set; ${spec.path} does not match Bun ${targetVersion}.` };
+			}
+		}
+
+		const npmWorkflow = require('./npm-publish-workflow');
+		const indexedNpm = Buffer.from((options.readIndexedNpmPublishWorkflow || npmWorkflow.readIndexedNpmPublishWorkflow)(projectRoot));
+		if (!indexedNpm.equals(Buffer.from(npmWorkflow.renderNpmPublishWorkflow(targetVersion)))) {
+			return { success: false, error: `A staged Bun pin change requires the complete generated workflow set; ${npmWorkflow.NPM_PUBLISH_WORKFLOW_PATH} does not match Bun ${targetVersion}.` };
+		}
+		return { success: true, sourceVersion, targetVersion };
+	} catch (error) {
+		return { success: false, error: `Could not verify the complete staged Bun pin update: ${error.message}` };
+	}
+}
+
+function blockedBunBatchDecision(reason) {
+	return {
+		allowed: false,
+		decision: 'blocked',
+		path: 'package.json',
+		operation: 'staged_edit',
+		requiredSurface: 'workflows',
+		declaredSurface: 'workflows',
+		reason,
+		repairHint: 'Run forge release update-bun-pins from the staged package.json target, then stage the complete generated workflow set.',
+	};
+}
+
 async function authorizeAndConsumeProtectedStateWrites(projectRoot, requests = [], options = {}) {
+	const bunBatch = (options.validateCompleteBunPinBatch || validateCompleteBunPinBatch)(projectRoot, options);
+	if (!bunBatch.success) {
+		return { success: false, decisions: [], batchDecision: blockedBunBatchDecision(bunBatch.error) };
+	}
 	if (requests.length === 0) return { success: true, decisions: [] };
 	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
 	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
@@ -256,10 +1033,15 @@ async function authorizeAndConsumeProtectedStateWrites(projectRoot, requests = [
 				worktreeScope,
 			}, rows || []));
 		}
+		validateBunDecisionTargets(projectRoot, decisions);
 
 		if (decisions.some(decision => !decision.allowed)) {
 			return { success: false, decisions };
 		}
+		const currentBunBatch = (options.validateCompleteBunPinBatch || validateCompleteBunPinBatch)(projectRoot, options);
+		if (!currentBunBatch.success) {
+			return { success: false, decisions, batchDecision: blockedBunBatchDecision(currentBunBatch.error) };
+		}
 
 		for (const decision of decisions) {
 			const createdAt = options.now || new Date().toISOString();
@@ -278,8 +1060,11 @@ async function authorizeAndConsumeProtectedStateWrites(projectRoot, requests = [
 					path: decision.path,
 					surface: decision.requiredSurface,
 					contentHash: decision.contentHash,
+					sourceHead: decision.sourceHead,
 					worktreeScope: decision.worktreeScope,
+					writeIntent: decision.operation === 'staged_delete' ? 'delete' : 'update',
 					operation: 'staged_edit',
+					viaForgeApi: decision.viaForgeApi === true,
 					sourceCommand: 'scripts/protected-state-check.js',
 				},
 				created_at: createdAt,
@@ -295,11 +1080,21 @@ async function authorizeAndConsumeProtectedStateWrites(projectRoot, requests = [
 module.exports = {
 	PROTECTED_STATE_ENTITY_TYPE,
 	PROTECTED_STATE_AUTHORIZATION_ISSUED,
+	PROTECTED_STATE_WRITE_COMPLETED,
 	PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+	isValidGitObjectId,
 	resolveWorktreeScope,
 	authorizationEntityId,
 	parseAuthorizationEvent,
 	evaluateAuthorization,
 	issueNpmPublishWorkflowAuthorization,
+	completeNpmPublishWorkflowAuthorization,
+	issueBunWorkflowAuthorization,
+	completeBunWorkflowAuthorization,
+	cancelBunWorkflowBatchAuthorizations,
+	issueGeneratedHarnessClaudeAuthorization,
+	completeGeneratedHarnessClaudeAuthorization,
+	issueGeneratedHarnessSkillAuthorization,
+	completeGeneratedHarnessSkillAuthorization,
 	authorizeAndConsumeProtectedStateWrites,
 };