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

package/lib/kernel/broker.js

@@ -1,12 +1,14 @@
 'use strict';
 
 const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
-const { randomUUID } = require('node:crypto');
-const { buildConflict, evaluateKernelEvent, normalizePayload } = require('./evaluators');
+const { createHash, randomUUID } = require('node:crypto');
+const { types: { isProxy } } = require('node:util');
+const { buildConflict, evaluateKernelEvent, normalizePayload, stableStringify } = require('./evaluators');
 const { CONFLICT_SIGNAL, classifyConflictSignal } = require('./conflict-signal');
 const { buildKernelMigrationPlan } = require('./migrations');
-const { buildClaimConflict, isValidExpiresAt, planClaimAcquisition } = require('./lease-enforcer');
+const { buildClaimConflict, isLeaseExpired, isValidExpiresAt, planClaimAcquisition } = require('./lease-enforcer');
 const {
 	ISSUE_COMMAND_EXIT_CODES,
 	ISSUE_COMMAND_SCHEMA_VERSION,
@@ -15,7 +17,12 @@ const {
 	isValidIssuePriority,
 	normalizePriority,
 } = require('./issue-command-contract');
-const { isValidIssueStatus, isValidStatusTransition, rankForPriorityLabel } = require('./taxonomy-validator');
+const {
+	isTerminalStatus,
+	isValidIssueStatus,
+	isValidStatusTransition,
+	rankForPriorityLabel,
+} = require('./taxonomy-validator');
 const { assertFilesystemSafeForKernel } = require('./fs-class');
 const { resolveIssueIdArgs } = require('./issue-id-resolver');
 
@@ -25,6 +32,22 @@ const LOCAL_BROKER_PRAGMAS = Object.freeze([
 	'PRAGMA foreign_keys=ON;',
 	'PRAGMA busy_timeout=5000;',
 ]);
+const PR_LINKAGE_TURNS = new WeakMap();
+
+async function withPrLinkageTurn(driver, operation) {
+	const queueKey = driver.transactionQueueKey || driver;
+	const prior = PR_LINKAGE_TURNS.get(queueKey) || Promise.resolve();
+	let release;
+	const current = new Promise(resolve => { release = resolve; });
+	PR_LINKAGE_TURNS.set(queueKey, current);
+	await prior;
+	try {
+		return await operation();
+	} finally {
+		release();
+		if (PR_LINKAGE_TURNS.get(queueKey) === current) PR_LINKAGE_TURNS.delete(queueKey);
+	}
+}
 
 // Bounded wall-clock ceiling for the single `git rev-parse --git-common-dir`
 // probe below. This synchronous spawn has intermittently hung on Windows/Node
@@ -56,6 +79,16 @@ function resolveGitCommonDir(projectRoot, deps = {}) {
 		throw new Error('projectRoot is required to resolve the Kernel broker common-dir');
 	}
 
+	const conventionalDir = defaultGitCommonDir(projectRoot);
+	try {
+		if (fs.lstatSync(conventionalDir).isDirectory()) {
+			return conventionalDir;
+		}
+	} catch {
+		// Missing/unreadable .git or a linked-worktree .git file needs Git's
+		// authoritative common-dir resolution below.
+	}
+
 	const exec = deps.execFileSync || execFileSync;
 	let rawCommonDir;
 	try {
@@ -117,6 +150,500 @@ function requireDriverMethod(driver, methodName) {
 	}
 }
 
+const TRACE_FULL_HEAD = /^[0-9a-f]{40}$/;
+const TRACE_SHA256 = /^[0-9a-f]{64}$/;
+const TRACE_MAX_RECEIPT_BYTES = 1_048_576;
+const TRACE_MAX_RECEIPT_DEPTH = 64;
+const TRACE_MAX_RECEIPT_NODES = 100_000;
+const TRACE_MAX_ARTIFACT_BYTES = 65_536;
+const TRACE_MAX_GATES = 32;
+
+function traceError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	error.status = 'INCOMPLETE';
+	return error;
+}
+
+function readReceiptShape(value) {
+	try {
+		return {
+			descriptors: Object.getOwnPropertyDescriptors(value),
+			prototype: Object.getPrototypeOf(value),
+		};
+	} catch {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt must be bounded plain JSON');
+	}
+}
+
+function assertBoundedReceiptArray(value, descriptors, prototype, state, depth) {
+	const keys = Reflect.ownKeys(descriptors);
+	if (prototype !== Array.prototype || keys.length !== value.length + 1) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt arrays must be dense');
+	}
+	for (let index = 0; index < value.length; index += 1) {
+		const descriptor = descriptors[String(index)];
+		if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) {
+			throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt must not contain accessors');
+		}
+		assertBoundedReceiptValue(descriptor.value, state, depth + 1);
+	}
+}
+
+function assertBoundedReceiptObject(descriptors, prototype, state, depth) {
+	if (prototype !== Object.prototype) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt objects must be plain');
+	}
+	for (const descriptor of Object.values(descriptors)) {
+		if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
+			throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt must not contain accessors');
+		}
+		assertBoundedReceiptValue(descriptor.value, state, depth + 1);
+	}
+}
+
+function assertBoundedReceiptValue(value, state, depth = 0) {
+	const traversal = state || { ancestors: new WeakSet(), nodes: 0 };
+	traversal.nodes += 1;
+	if (traversal.nodes > TRACE_MAX_RECEIPT_NODES || depth > TRACE_MAX_RECEIPT_DEPTH) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt exceeds canonical bounds');
+	}
+	if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+	if (typeof value === 'number' && Number.isFinite(value)) return;
+	if (!value || typeof value !== 'object' || isProxy(value) || traversal.ancestors.has(value)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt must be bounded plain JSON');
+	}
+	const { descriptors, prototype } = readReceiptShape(value);
+	const keys = Reflect.ownKeys(descriptors);
+	if (keys.some(key => typeof key !== 'string')) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt must not contain symbol keys');
+	}
+	traversal.ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			assertBoundedReceiptArray(value, descriptors, prototype, traversal, depth);
+			return;
+		}
+		assertBoundedReceiptObject(descriptors, prototype, traversal, depth);
+	} finally {
+		traversal.ancestors.delete(value);
+	}
+}
+
+// Contract hashes use ECMAScript's default UTF-16 code-unit key order, not locale collation.
+function compareCanonicalReceiptKeys(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+
+function canonicalReceiptStringify(value) {
+	if (value === null || typeof value !== 'object') return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalReceiptStringify).join(',')}]`;
+	return `{${Object.keys(value).sort(compareCanonicalReceiptKeys)
+		.map(key => `${JSON.stringify(key)}:${canonicalReceiptStringify(value[key])}`)
+		.join(',')}}`;
+}
+
+function snapshotReceipt(receipt) {
+	assertBoundedReceiptValue(receipt);
+	return JSON.parse(canonicalReceiptStringify(receipt));
+}
+
+function normalizeTraceRepository(value) {
+	return typeof value === 'string' ? value.trim().toLowerCase() : value;
+}
+
+function snapshotPrLinkageInput(input) {
+	if (!input || typeof input !== 'object') return input;
+	return {
+		phase: input.phase,
+		git_common_dir: input.git_common_dir,
+		repo: normalizeTraceRepository(input.repo),
+		number: input.number,
+		url: input.url,
+		branch: input.branch,
+		work_packet: snapshotReceipt(input.work_packet),
+		run_receipt: snapshotReceipt(input.run_receipt),
+		occurred_at: input.occurred_at || new Date().toISOString(),
+		worktree_id: input.worktree_id,
+		issue_id: input.issue_id,
+		journal_ptr: input.journal_ptr,
+		id: input.id,
+	};
+}
+
+function receiptContentHash(receipt) {
+	const withoutHash = {};
+	for (const [key, value] of Object.entries(receipt)) {
+		if (key !== 'content_hash') withoutHash[key] = value;
+	}
+	const canonical = canonicalReceiptStringify(withoutHash);
+	if (Buffer.byteLength(canonical, 'utf8') > TRACE_MAX_RECEIPT_BYTES) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage receipt exceeds byte bound');
+	}
+	return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+
+function assertReceiptEnvelope(receipt, schemaId) {
+	assertBoundedReceiptValue(receipt);
+	if (!receipt || receipt.schema_id !== schemaId || receipt.schema_version !== 1
+		|| !TRACE_SHA256.test(receipt.content_hash)
+		|| receiptContentHash(receipt) !== receipt.content_hash
+		|| !receipt.payload || typeof receipt.payload !== 'object' || Array.isArray(receipt.payload)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', `recordPrLinkage requires a valid ${schemaId} receipt`);
+	}
+	return receipt;
+}
+
+function derivePrEvidence(input) {
+	const packet = assertReceiptEnvelope(input?.work_packet, 'forge.memory.work-packet.v1');
+	const receipt = assertReceiptEnvelope(input?.run_receipt, 'forge.memory.run-receipt.v1');
+	const packetPayload = packet.payload;
+	const receiptPayload = receipt.payload;
+	if (typeof packetPayload.issue_id !== 'string' || !packetPayload.issue_id
+		|| !Number.isInteger(packetPayload.expected_issue_revision) || packetPayload.expected_issue_revision < 0
+		|| packetPayload.authority?.issue_revision !== packetPayload.expected_issue_revision
+		|| typeof packetPayload.packet_id !== 'string' || !packetPayload.packet_id || packetPayload.packet_id.length > 512
+		|| typeof packetPayload.repository_id !== 'string' || !packetPayload.repository_id
+		|| !Number.isSafeInteger(packetPayload.packet_revision) || packetPayload.packet_revision < 1
+		|| !TRACE_SHA256.test(packetPayload.capability_manifest_digest)
+		|| typeof packetPayload.workflow_config_revision !== 'string' || !packetPayload.workflow_config_revision
+		|| !TRACE_FULL_HEAD.test(packetPayload.target_head)
+		|| !TRACE_SHA256.test(packetPayload.risk_manifest_digest)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage WorkPacket authority binding is incomplete');
+	}
+	const gateIds = packetPayload.receipt_requirements?.gate_ids;
+	if (!Array.isArray(gateIds) || gateIds.length === 0 || gateIds.length > TRACE_MAX_GATES
+		|| new Set(gateIds).size !== gateIds.length
+		|| gateIds.some(gateId => typeof gateId !== 'string' || gateId.length === 0 || gateId.length > 128)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage WorkPacket gate requirements are incomplete');
+	}
+	if (!Array.isArray(packetPayload.allowed_mutations)
+		|| !packetPayload.allowed_mutations.includes(`pr.${input.phase}`)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', `recordPrLinkage WorkPacket does not authorize pr.${input.phase}`);
+	}
+	if (receiptPayload.status !== 'PASS' || receiptPayload.validation?.status !== 'PASS') {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage requires a PASS RunReceipt');
+	}
+	for (const field of ['run_id', 'attempt_id']) {
+		const value = receiptPayload[field];
+		const hasControl = typeof value === 'string' && [...value].some(character => {
+			const code = character.charCodeAt(0);
+			return code <= 31 || code === 127;
+		});
+		if (typeof value !== 'string' || value.length === 0 || value.length > 512 || hasControl) {
+			throw traceError('FORGE_TRACE_INVALID_RECEIPT', `recordPrLinkage RunReceipt ${field} is invalid`);
+		}
+	}
+	const requiredMutation = `pr.${input.phase}`;
+	if (!Array.isArray(receiptPayload.mutations_attempted)
+		|| !receiptPayload.mutations_attempted.includes(requiredMutation)
+		|| !Array.isArray(receiptPayload.mutations_authorized)
+		|| !receiptPayload.mutations_authorized.includes(requiredMutation)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', `recordPrLinkage RunReceipt must attempt and authorize ${requiredMutation}`);
+	}
+	const bindingsMatch = receiptPayload.packet_hash === packet.content_hash
+		&& receiptPayload.exact_head === packetPayload.target_head
+		&& receiptPayload.packet_revision === packetPayload.packet_revision
+		&& receiptPayload.manifest_digest === packetPayload.capability_manifest_digest
+		&& receiptPayload.workflow_config_revision === packetPayload.workflow_config_revision;
+	if (!bindingsMatch) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage WorkPacket and RunReceipt bindings conflict');
+	}
+	if (input.issue_id && input.issue_id !== packetPayload.issue_id) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage explicit issue_id conflicts with WorkPacket authority');
+	}
+	if (packetPayload.repository_id !== input.repo) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage repository conflicts with WorkPacket authority');
+	}
+	return {
+		issue_id: packetPayload.issue_id,
+		issue_revision: packetPayload.expected_issue_revision,
+		head_sha: packetPayload.target_head,
+		packet_id: packetPayload.packet_id,
+		packet_revision: packetPayload.packet_revision,
+		work_packet_hash: packet.content_hash,
+		work_packet_identity: stableStringify([
+			packetPayload.issue_id,
+			packetPayload.expected_issue_revision,
+			packetPayload.packet_id,
+			packetPayload.packet_revision,
+			packetPayload.repository_id,
+			packetPayload.target_head,
+		]),
+		run_receipt_hash: receipt.content_hash,
+		run_id: receiptPayload.run_id,
+		attempt_id: receiptPayload.attempt_id,
+		risk_manifest_digest: packetPayload.risk_manifest_digest,
+		gate_ids: gateIds,
+	};
+}
+
+function parseTracePayload(row) {
+	try {
+		return JSON.parse(row?.payload_json || '{}');
+	} catch {
+		return {};
+	}
+}
+
+function isNewerGateCandidate(candidate, current) {
+	return !current || candidate.eventAtMs > current.eventAtMs
+		|| (candidate.eventAtMs === current.eventAtMs && candidate.order > current.order);
+}
+
+function resolveGateReceipts(events, gateIds, occurredAt) {
+	const occurredAtMs = Date.parse(occurredAt);
+	if (!Number.isFinite(occurredAtMs)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage occurred_at must be a valid timestamp');
+	}
+	const gateEvents = new Map();
+	for (const [order, event] of events.entries()) {
+		if (!['gate.approved', 'gate.rejected'].includes(event.event_type)) continue;
+		const eventAtMs = Date.parse(event.created_at);
+		if (!Number.isFinite(eventAtMs) || eventAtMs > occurredAtMs) continue;
+		const payload = parseTracePayload(event);
+		const candidate = { event, payload, eventAtMs, order };
+		if (gateIds.includes(payload.gate) && isNewerGateCandidate(candidate, gateEvents.get(payload.gate))) {
+			// listKernelEvents supplies rowid order for equal timestamps; later rows win explicitly.
+			gateEvents.set(payload.gate, candidate);
+		}
+	}
+	return gateIds.map(gateId => {
+		const latest = gateEvents.get(gateId);
+		const expiry = latest?.payload?.expires_at;
+		const active = latest?.event?.event_type === 'gate.approved'
+			&& (!expiry || (Number.isFinite(Date.parse(expiry)) && Date.parse(occurredAt) < Date.parse(expiry)));
+		if (!active || typeof latest.event.idempotency_key !== 'string' || !latest.event.idempotency_key) {
+			throw traceError('FORGE_TRACE_GATE_UNAVAILABLE', `recordPrLinkage gate ${gateId} lacks an active approval receipt`);
+		}
+		return latest.event.idempotency_key;
+	});
+}
+
+function readTraceArtifact(projectRoot, workFolder, filename) {
+	if (!workFolder) return { artifact: null, gap: filename.replace('.md', '') };
+	const root = fs.realpathSync(path.resolve(projectRoot));
+	const candidateFolder = path.resolve(root, workFolder);
+	if (!fs.existsSync(candidateFolder)) return { artifact: null, gap: filename.replace('.md', '') };
+	const folder = fs.realpathSync(candidateFolder);
+	const relativeFolder = path.relative(root, folder);
+	if (relativeFolder.startsWith('..') || path.isAbsolute(relativeFolder)) {
+		return { artifact: null, gap: `${filename.replace('.md', '')}:outside_project` };
+	}
+	const file = path.join(folder, filename);
+	if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return { artifact: null, gap: filename.replace('.md', '') };
+	const resolvedFile = fs.realpathSync(file);
+	const relativeFile = path.relative(root, resolvedFile);
+	if (relativeFile.startsWith('..') || path.isAbsolute(relativeFile)) {
+		return { artifact: null, gap: `${filename.replace('.md', '')}:outside_project` };
+	}
+	if (fs.statSync(resolvedFile).size > TRACE_MAX_ARTIFACT_BYTES) {
+		return { artifact: null, gap: `${filename.replace('.md', '')}:oversized` };
+	}
+	return {
+		artifact: {
+			path: path.posix.join(String(workFolder).replaceAll('\\', '/'), filename),
+			content: fs.readFileSync(resolvedFile, 'utf8'),
+		},
+		gap: null,
+	};
+}
+
+function buildTraceEnvelope(projectRoot, target, rows) {
+	const artifactReads = Object.fromEntries(['plan', 'tasks', 'decisions'].map(name => (
+		[name, readTraceArtifact(projectRoot, rows.work_folder, `${name}.md`)]
+	)));
+	const artifacts = Object.fromEntries(Object.entries(artifactReads).map(([name, value]) => [name, value.artifact]));
+	const gaps = [];
+	if (!rows.issue) gaps.push('issue');
+	if (!rows.worktree) gaps.push('worktree');
+	if (!rows.work_folder) gaps.push('work_folder');
+	for (const name of ['plan', 'tasks', 'decisions']) if (artifactReads[name].gap) gaps.push(artifactReads[name].gap);
+	if (rows.pull_requests.length === 0) gaps.push('pull_requests');
+	for (const gap of rows.gaps || []) if (!gaps.includes(gap)) gaps.push(gap);
+	return {
+		schema_version: 'forge.trace.v1',
+		target: target.issue_id
+			? { kind: 'issue', id: target.issue_id }
+			: { kind: 'pr', number: Number(target.pr_number), repo: target.repo ?? null },
+		issue: rows.issue,
+		worktree: rows.worktree,
+		work_folder: rows.work_folder,
+		artifacts,
+		pull_requests: rows.pull_requests,
+		gaps,
+	};
+}
+
+function assertCompatiblePrEvidence(existingEvent, payload) {
+	if (!existingEvent || stableStringify(normalizePayload(existingEvent)) === stableStringify(payload)) return;
+	throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'INCOMPLETE: conflicting evidence for idempotency key');
+}
+
+const PR_LINKAGE_DRIVER_METHODS = [
+	'exec', 'resolvePrLinkage', 'upsertPr', 'retirePr', 'readTrace',
+	'listKernelEvents', 'loadKernelEventByIdempotencyKey', 'loadPrEventsByRunId', 'insertKernelEvent', 'enqueueKernelProjection',
+];
+
+function preparePrLinkageInput(input, driver) {
+	const linkageInput = snapshotPrLinkageInput(input);
+	if (!linkageInput || !['opened', 'merged'].includes(linkageInput.phase)) {
+		throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordPrLinkage phase must be opened or merged');
+	}
+	for (const field of ['git_common_dir', 'repo', 'number', 'branch']) {
+		if (linkageInput[field] === undefined || linkageInput[field] === null || linkageInput[field] === '') {
+			throw traceError('FORGE_TRACE_INVALID_RECEIPT', `recordPrLinkage requires ${field}`);
+		}
+	}
+	for (const method of PR_LINKAGE_DRIVER_METHODS) requireDriverMethod(driver, method);
+	return linkageInput;
+}
+
+function assertResolvedPrLinkage(inferred, evidence) {
+	if (!inferred.issue_id || inferred.issue_revision === null) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage requires resolved issue linkage');
+	}
+	if (!inferred.worktree_id || !inferred.worktree_matches) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage requires a matching active worktree binding');
+	}
+	if (inferred.inferred_issue_id && evidence.issue_id !== inferred.inferred_issue_id) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage WorkPacket issue conflicts with inferred worktree issue');
+	}
+	if (evidence.issue_revision !== inferred.issue_revision) {
+		throw traceError(
+			'FORGE_TRACE_STALE_AUTHORITY',
+			`recordPrLinkage stale issue revision: expected ${evidence.issue_revision}, actual ${inferred.issue_revision}`,
+		);
+	}
+}
+
+function findPriorPr(pullRequests, input) {
+	return pullRequests.find(candidate => (
+		candidate.git_common_dir === input.git_common_dir
+			&& candidate.repo === input.repo
+			&& Number(candidate.number) === Number(input.number)
+	)) || null;
+}
+
+function buildPrLinkagePayload(input, evidence, worktreeId, gateReceipts) {
+	return {
+		phase: input.phase,
+		issue_id: evidence.issue_id,
+		issue_revision: evidence.issue_revision,
+		worktree_id: worktreeId,
+		repo: input.repo,
+		number: input.number,
+		git_common_dir: input.git_common_dir,
+		branch: input.branch,
+		url: input.url ?? null,
+		head_sha: evidence.head_sha,
+		work_packet_hash: evidence.work_packet_hash,
+		work_packet_identity: evidence.work_packet_identity,
+		packet_id: evidence.packet_id,
+		packet_revision: evidence.packet_revision,
+		run_receipt_hash: evidence.run_receipt_hash,
+		run_id: evidence.run_id,
+		attempt_id: evidence.attempt_id,
+		risk_manifest_digest: evidence.risk_manifest_digest,
+		gate_receipts: gateReceipts,
+	};
+}
+
+function assertTerminalPrCompatibility(terminalPr, input, evidence, worktreeId) {
+	if (!terminalPr) return;
+	const conflicts = evidence.head_sha !== terminalPr.head_sha
+		|| (input.branch != null && input.branch !== terminalPr.branch)
+		|| evidence.issue_id !== terminalPr.issue_id
+		|| (worktreeId != null && worktreeId !== terminalPr.worktree_id)
+		|| (input.journal_ptr != null && input.journal_ptr !== terminalPr.journal_ptr);
+	if (conflicts) throw traceError('FORGE_TRACE_TERMINAL_CONFLICT', 'recordPrLinkage terminal PR linkage conflict');
+}
+
+function assertTerminalPrEvent(terminalPr, existingEvent) {
+	if (terminalPr && !existingEvent) {
+		throw traceError('FORGE_TRACE_TERMINAL_CONFLICT', 'recordPrLinkage terminal PR linkage conflict');
+	}
+}
+
+function assertAtomicPrEvidence(trace, input, evidence) {
+	if (input.phase !== 'opened') return;
+	if (trace.gaps?.some(gap => gap === 'pull_requests:overflow'
+		|| /^pull_requests:.*:unlinked_issue$/.test(gap)
+		|| /^iterations:.*:(?:missing|incomplete|overflow)$/.test(gap))) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage cannot prove complete semantic identity evidence');
+	}
+	for (const request of trace.pull_requests || []) {
+		const conflicting = (request.iterations || []).some(iteration => {
+			if (iteration.type !== 'pr.opened') return false;
+			if (iteration.work_packet_identity !== evidence.work_packet_identity) return false;
+			const sameTarget = request.git_common_dir === input.git_common_dir
+				&& request.repo === input.repo && Number(request.number) === Number(input.number);
+			const sameContent = iteration.work_packet_hash === evidence.work_packet_hash
+				&& iteration.run_receipt_hash === evidence.run_receipt_hash;
+			return !sameTarget || !sameContent;
+		});
+		if (conflicting) {
+			throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage semantic identity conflicts with durable PR evidence');
+		}
+	}
+}
+
+function assertAtomicRunIdentity(events, payload) {
+	const identityFields = ['issue_id', 'repo', 'number', 'git_common_dir', 'branch', 'head_sha',
+		'work_packet_identity', 'packet_id', 'packet_revision', 'run_id', 'attempt_id'];
+	for (const event of events) {
+		const existing = normalizePayload(event);
+		if (identityFields.some(field => stableStringify(existing[field]) !== stableStringify(payload[field]))) {
+			throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordPrLinkage run identity conflicts with durable PR evidence');
+		}
+	}
+}
+
+async function assertExactLifecycleOwnership(driver, evidence, context, config, now) {
+	for (const method of ['loadActiveKernelClaim', 'loadKernelEntity']) requireDriverMethod(driver, method);
+	if (typeof context.actor !== 'string' || !context.actor || typeof context.sessionId !== 'string' || !context.sessionId) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordOpenedPrLinkage requires exact actor and session authority');
+	}
+	const [issue, claim] = await Promise.all([
+		driver.loadKernelEntity('issue', evidence.issue_id, context, config),
+		driver.loadActiveKernelClaim(evidence.issue_id, context, config),
+	]);
+	if (!issue || isTerminalStatus(issue.status) || !claim || claim.state !== 'active'
+		|| claim.actor !== context.actor || claim.session_id !== context.sessionId || isLeaseExpired(claim, now)) {
+		throw traceError('FORGE_TRACE_EVIDENCE_CONFLICT', 'recordOpenedPrLinkage claimant no longer owns the live issue');
+	}
+}
+
+function isDatabaseLocked(error) {
+	return /database is locked|SQLITE_BUSY/i.test(String(error?.message || error));
+}
+
+async function beginImmediate(driver, config) {
+	await driver.exec('PRAGMA busy_timeout=0;', config);
+	for (let attempt = 0; attempt < 500; attempt += 1) {
+		try {
+			await driver.exec('BEGIN IMMEDIATE;', config);
+			return;
+		} catch (error) {
+			if (!isDatabaseLocked(error) || attempt === 499) {
+				await restoreBusyTimeout(driver, config);
+				throw error;
+			}
+			await new Promise(resolve => setTimeout(resolve, 10));
+		}
+	}
+}
+
+async function restoreBusyTimeout(driver, config) {
+	try {
+		await driver.exec(`PRAGMA busy_timeout=${config.busyTimeoutMs ?? 5000};`, config);
+	} catch {
+		// Recovery must never hide the authoritative linkage result.
+	}
+}
+
 // The migration ledger records which migration ids have been applied so initialize()
 // applies each migration AT MOST ONCE — no full re-run, no blanket duplicate-error
 // swallow. The ledger table is broker-managed bookkeeping (created before the plan is
@@ -266,6 +793,13 @@ function buildClaimScope(event) {
 	};
 }
 
+function terminalClaimValidationError(issueId, status) {
+	const error = new Error(`Cannot claim a terminal (${status}) issue ${issueId}`);
+	error.isIssueValidation = true;
+	error.validationField = 'status';
+	return error;
+}
+
 const GUARDED_DRIVER_METHODS = Object.freeze([
 	'exec',
 	'loadKernelEntity',
@@ -365,6 +899,12 @@ async function commitGuardedAccept({ driver, event, evaluation, claimScope, acti
 
 	await driver.exec('BEGIN IMMEDIATE;', config);
 	try {
+		if (claimScope) {
+			const issue = await driver.loadKernelEntity('issue', claimScope.issue_id, context, config);
+			if (isTerminalStatus(issue?.status)) {
+				throw terminalClaimValidationError(claimScope.issue_id, issue.status);
+			}
+		}
 		if (claimPlan) {
 			if (claimPlan.action === 'reclaim') {
 				await driver.updateKernelClaimState(
@@ -448,9 +988,39 @@ function nextCommandsFor(commandId) {
 	return contract ? [...contract.nextCommands] : [];
 }
 
-// First non-flag token (the issue id for update/close/comment).
+const VALUE_TAKING_ISSUE_FLAGS = new Set([
+	'acceptance', 'assignee', 'blocks', 'body', 'description', 'design', 'expires',
+	'id', 'issue', 'label', 'metadata', 'notes', 'parent', 'priority', 'reason',
+	'status', 'title', 'type', 'close-reason', 'closed-at', 'created-by', 'dep-type',
+	'priority-rank',
+]);
+
+// Return bare operands while skipping the value consumed by each known
+// space-separated issue flag. Boolean/unknown flags (for example --json) do not
+// consume the following operand; --key=value has no separate value.
+function positionalArgs(args = []) {
+	const positionals = [];
+	for (let index = 0; index < (args || []).length; index += 1) {
+		const token = args[index];
+		if (typeof token !== 'string') continue;
+		if (token.startsWith('--')) {
+			const flagName = token.slice(2).split('=', 1)[0];
+			if (VALUE_TAKING_ISSUE_FLAGS.has(flagName)
+				&& !token.includes('=')
+				&& typeof args[index + 1] === 'string'
+				&& !args[index + 1].startsWith('--')) {
+				index += 1;
+			}
+			continue;
+		}
+		if (!token.startsWith('-')) positionals.push(token);
+	}
+	return positionals;
+}
+
+// First bare operand (the issue id for update/close/comment).
 function firstPositionalArg(args = []) {
-	return (args || []).find(value => typeof value === 'string' && !value.startsWith('-'));
+	return positionalArgs(args)[0];
 }
 
 // Parse the long-flag pairs CLI mutations carry. Supports BOTH forms:
@@ -588,9 +1158,11 @@ function buildCommentPayload(issueId, args) {
 // edge insert is malformed — previously a positional invocation left issue_id
 // undefined and the INSERT failed with a SQLite bind error).
 function resolveDependencyEndpoints(flags, args = []) {
-	const positionals = args.filter(arg => typeof arg === 'string' && !arg.startsWith('-'));
+	const positionals = positionalArgs(args);
 	const issueId = typeof flags.issue === 'string' ? flags.issue : positionals[0];
-	const blocksIssueId = typeof flags.blocks === 'string' ? flags.blocks : positionals[1];
+	const blocksIssueId = typeof flags.blocks === 'string'
+		? flags.blocks
+		: (typeof flags.issue === 'string' ? positionals[0] : positionals[1]);
 	return {
 		issue_id: typeof issueId === 'string' ? issueId : undefined,
 		blocks_issue_id: typeof blocksIssueId === 'string' ? blocksIssueId : undefined,
@@ -714,6 +1286,37 @@ function assertValidIssueMutationPayload(payload, isCreate) {
 	}
 }
 
+function issueNotFoundError(issueId) {
+	const notFound = new Error(`Issue ${issueId ?? '<missing id>'} not found`);
+	notFound.isIssueNotFound = true;
+	return notFound;
+}
+
+async function loadRequiredIssue(driver, issueId, context, config) {
+	if (typeof issueId !== 'string' || issueId.trim() === '') {
+		throw issueNotFoundError(issueId);
+	}
+	const entity = await driver.loadKernelEntity('issue', issueId, context, config);
+	if (!entity) throw issueNotFoundError(issueId);
+	return entity;
+}
+
+function assertClaimEligible(operation, claimEntity, claimIssueId) {
+	if (operation !== 'claim') return;
+	if (isTerminalStatus(claimEntity.status)) {
+		throw terminalClaimValidationError(claimIssueId, claimEntity.status);
+	}
+	if (claimEntity.status === 'backlog') {
+		const error = new Error(
+			`Cannot claim a parked (backlog) issue ${claimIssueId}: promote it first `
+			+ `(forge issue update ${claimIssueId} --status open)`,
+		);
+		error.isIssueValidation = true;
+		error.validationField = 'status';
+		throw error;
+	}
+}
+
 // Construct the kernel event for a mutation op. For update/close/comment, the
 // expected_revision is the FRESHLY READ stored revision (so runIssueOperation can
 // never manufacture a stale CAS — a behind revision only arrives via a raw
@@ -741,41 +1344,28 @@ async function buildIssueMutationEvent(driver, operation, args, context, config)
 	// Dependency / claim ops target their own entity stream (no issue-row CAS): the
 	// event entity_type is 'dependency'/'claim' and entity_id is a fresh dep/claim id.
 	if (DEPENDENCY_OPERATIONS.has(operation)) {
+		const endpoints = resolveDependencyEndpoints(flags, args);
+		await loadRequiredIssue(driver, endpoints.issue_id, context, config);
+		await loadRequiredIssue(driver, endpoints.blocks_issue_id, context, config);
 		return buildDependencyMutationEvent(operation, flags, actor, origin, context, args);
 	}
 	if (CLAIM_OPERATIONS.has(operation)) {
+		const claimIssueId = typeof flags.issue === 'string' ? flags.issue : firstPositionalArg(args);
+		const claimEntity = await loadRequiredIssue(driver, claimIssueId, context, config);
 		// Claim eligibility: a `backlog` (parked) issue is NOT workable — beginning it
 		// would jump backlog->in_progress and skip the required promote (backlog->open).
 		// Reject the claim here rather than minting a lease that silently activates parked
 		// work. `release` is never gated (an over-eager park must always be releasable).
-		if (operation === 'claim') {
-			const claimIssueId = typeof flags.issue === 'string' ? flags.issue : firstPositionalArg(args);
-			const claimEntity = await driver.loadKernelEntity('issue', claimIssueId, context, config);
-			if (claimEntity && claimEntity.status === 'backlog') {
-				const err = new Error(
-					`Cannot claim a parked (backlog) issue ${claimIssueId}: promote it first `
-					+ `(forge issue update ${claimIssueId} --status open)`,
-				);
-				err.isIssueValidation = true;
-				err.validationField = 'status';
-				throw err;
-			}
-		}
+		assertClaimEligible(operation, claimEntity, claimIssueId);
 		return buildClaimMutationEvent(operation, flags, actor, origin, context, args);
 	}
 
 	const issueId = firstPositionalArg(args);
-	const entity = await driver.loadKernelEntity('issue', issueId, context, config);
-	// Existence guard: update/close/comment target an EXISTING issue. Without this a
-	// missing issue yields entity=null -> expected_revision 0, which the row-level CAS
+	const entity = await loadRequiredIssue(driver, issueId, context, config);
+	// loadRequiredIssue above enforces that update/close/comment target an EXISTING issue.
 	// accepts as a fresh insert — silently minting a phantom issue on a typo'd id (data
 	// corruption; Beads errors not-found). Signal not-found so runIssueMutation returns
 	// the contract FORGE_ISSUE_NOT_FOUND / exit 3 instead of writing a row.
-	if (!entity) {
-		const notFound = new Error(`Issue ${issueId ?? '<missing id>'} not found`);
-		notFound.isIssueNotFound = true;
-		throw notFound;
-	}
 	const expectedRevision = Number(entity?.entity_revision || 0);
 	// For close, the driver maps event_type='issue.close' to a terminal status; an
 	// explicit --status flag (rework move) still wins via the update payload.
@@ -938,6 +1528,7 @@ async function mapMutationResult(driver, operation, event, result, context, conf
 
 function createLocalBroker(options = {}) {
 	const driver = options.driver;
+	const now = typeof options.now === 'function' ? options.now : () => new Date().toISOString();
 	let cachedConfig;
 
 	// Memoized config build AND the structural home of the D19 default-on
@@ -1045,6 +1636,8 @@ function createLocalBroker(options = {}) {
 		let event;
 		try {
 			event = await buildIssueMutationEvent(driver, operation, args, context, config);
+			const result = await runGuardedEventImpl(event, context);
+			return mapMutationResult(driver, operation, event, result, context, config);
 		} catch (err) {
 			if (err && err.isIssueNotFound) {
 				// Missing target for update/close/comment: return the contract not-found
@@ -1069,8 +1662,6 @@ function createLocalBroker(options = {}) {
 			}
 			throw err;
 		}
-		const result = await runGuardedEventImpl(event, context);
-		return mapMutationResult(driver, operation, event, result, context, config);
 	}
 
 	return {
@@ -1211,6 +1802,107 @@ function createLocalBroker(options = {}) {
 			return driver.upsertPr(row, context, getConfig());
 		},
 
+		async recordPrLinkage(input, context = {}) {
+			if (typeof driver.forkConnection !== 'function') {
+				throw traceError('FORGE_TRACE_UNAVAILABLE', 'recordPrLinkage requires an isolated transaction connection');
+			}
+			let transactionDriver;
+			const config = getConfig();
+			try {
+				transactionDriver = driver.forkConnection(config);
+			} catch {
+				throw traceError('FORGE_TRACE_UNAVAILABLE', 'recordPrLinkage could not create an isolated transaction connection');
+			}
+			if (!transactionDriver || transactionDriver === driver || typeof transactionDriver.close !== 'function') {
+				throw traceError('FORGE_TRACE_UNAVAILABLE', 'recordPrLinkage received an invalid isolated transaction connection');
+			}
+			try {
+				return await withPrLinkageTurn(transactionDriver, async () => {
+				const linkageInput = preparePrLinkageInput(input, transactionDriver);
+				const evidence = derivePrEvidence(linkageInput);
+				let transactionOpen = false;
+				try {
+				await beginImmediate(transactionDriver, config);
+				transactionOpen = true;
+				if (linkageInput.phase === 'opened' || context.requireExactLifecycleOwnership === true) {
+					await assertExactLifecycleOwnership(transactionDriver, evidence, context, config, now());
+				}
+				const inferred = await transactionDriver.resolvePrLinkage({ ...linkageInput, issue_id: evidence.issue_id }, context, config);
+				assertResolvedPrLinkage(inferred, evidence);
+				const issueEvents = await transactionDriver.listKernelEvents('issue', evidence.issue_id, context, config);
+				const gateReceipts = resolveGateReceipts(issueEvents, evidence.gate_ids, linkageInput.occurred_at);
+				const issueRows = await transactionDriver.readTrace({ issue_id: evidence.issue_id, pr_number: linkageInput.number,
+					repo: linkageInput.repo, git_common_dir: linkageInput.git_common_dir }, context, config);
+				assertAtomicPrEvidence(issueRows, linkageInput, evidence);
+				const priorPr = findPriorPr(issueRows.pull_requests, linkageInput);
+				const worktreeId = inferred.worktree_id;
+				const eventType = `pr.${linkageInput.phase}`;
+				const payload = buildPrLinkagePayload(linkageInput, evidence, worktreeId, gateReceipts);
+				assertAtomicRunIdentity(await transactionDriver.loadPrEventsByRunId(evidence.run_id, context, config), payload);
+				if (priorPr && priorPr.head_sha !== evidence.head_sha) {
+					throw traceError('FORGE_TRACE_STALE_AUTHORITY', 'recordPrLinkage receipt head conflicts with current PR authority');
+				}
+				const terminalPr = priorPr && ['merged', 'closed'].includes(priorPr.state) ? priorPr : null;
+				assertTerminalPrCompatibility(terminalPr, linkageInput, evidence, worktreeId);
+				const linked = terminalPr ? { ok: true, ...terminalPr } : await transactionDriver.upsertPr({
+					...linkageInput, head_sha: evidence.head_sha, issue_id: evidence.issue_id,
+					worktree_id: worktreeId, registered_at: linkageInput.occurred_at,
+				}, context, config);
+				const idempotencyKey = `${eventType}:${linked.id}:${evidence.head_sha}`;
+				const existingEvent = await transactionDriver.loadKernelEventByIdempotencyKey(idempotencyKey, context, config);
+				assertCompatiblePrEvidence(existingEvent, payload);
+				assertTerminalPrEvent(terminalPr, existingEvent);
+				let iteration;
+				if (existingEvent) {
+					iteration = { decision: 'duplicate', originalEvent: existingEvent, projection: false };
+				} else {
+					const event = await transactionDriver.insertKernelEvent({
+						entity_type: 'pr', entity_id: linked.id, event_type: eventType,
+						idempotency_key: idempotencyKey, expected_revision: 0,
+						actor: context.actor || 'forge', origin: context.origin || 'cli',
+						created_at: linkageInput.occurred_at, payload,
+					}, context, config);
+					const outboxEntry = await transactionDriver.enqueueKernelProjection(
+						buildProjectionOutboxEntry(event, context.projectionTarget || 'jsonl', linkageInput.occurred_at),
+						context, config,
+					);
+					iteration = { decision: 'accept', event, outboxEntry, projection: true };
+				}
+				if (linkageInput.phase === 'merged' && !terminalPr) {
+					await transactionDriver.retirePr({ git_common_dir: linked.git_common_dir, repo: linked.repo, number: linked.number },
+						{ state: 'merged', retired_at: linkageInput.occurred_at }, context, config);
+				}
+				await transactionDriver.exec('COMMIT;', config);
+				transactionOpen = false;
+				await restoreBusyTimeout(transactionDriver, config);
+				return { link: linked, iteration };
+				} catch (error) {
+				if (transactionOpen) {
+					try { await transactionDriver.exec('ROLLBACK;', config); } catch { /* preserve original error */ }
+				}
+				await restoreBusyTimeout(transactionDriver, config);
+				throw error;
+				}
+				});
+			} finally {
+				transactionDriver.close();
+			}
+		},
+
+		async recordOpenedPrLinkage(input, context = {}) {
+			if (input?.phase !== 'opened') throw traceError('FORGE_TRACE_INVALID_RECEIPT', 'recordOpenedPrLinkage requires opened phase');
+			return this.recordPrLinkage(input, { ...context, requireExactLifecycleOwnership: true });
+		},
+
+		async readTrace(target, context = {}) {
+			if (!target || (!target.issue_id && target.pr_number === undefined)) {
+				throw new Error('readTrace requires issue_id or pr_number');
+			}
+			requireDriverMethod(driver, 'readTrace');
+			const config = getConfig();
+			return buildTraceEnvelope(config.projectRoot, target, await driver.readTrace(target, context, config));
+		},
+
 		async updatePrVerdict(key, patch = {}, context = {}) {
 			requireDriverMethod(driver, 'updatePrVerdict');
 			return driver.updatePrVerdict(key, patch, context, getConfig());