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

package/lib/commands/merge.js

@@ -46,6 +46,8 @@ const { evaluateMergeRules } = require('../merge-rules');
 const { runIssueOperation } = require('../forge-issues');
 const { PrStateAdapter } = require('../adapters/pr-state-adapter');
 const { stripGlobalFlags } = require('../global-flags');
+const gateCommand = require('./gate');
+const { computeContentHash, validateContractStructure } = require('@forge/contracts');
 
 const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
 const FORGE_ISSUE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -64,6 +66,37 @@ const REVIEW_ACTOR_TYPENAMES = new Set([
 const REVIEW_STATES = new Set([
   'APPROVED', 'CHANGES_REQUESTED', 'COMMENTED', 'DISMISSED', 'PENDING',
 ]);
+const MERGE_GATE = 'gate.merge';
+
+function uuidFromSeed(seed) {
+  const hash = computeContentHash({ seed });
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
+
+function contractEnvelope(schemaId, objectId, createdAt, actor, payload) {
+  const value = {
+    schema_id: schemaId,
+    schema_version: 1,
+    object_id: objectId,
+    created_at: createdAt,
+    producer: { product_id: 'forge', product_version: '0.1.0', instance_id: actor },
+    capabilities_used: [],
+    provenance: { source_kind: 'guarded-merge', actor_class: 'system', actor_id: actor },
+    payload,
+    extensions: {},
+  };
+  value.content_hash = computeContentHash(value);
+  const validation = validateContractStructure(value);
+  if (!validation.ok) throw new Error(`${schemaId} validation failed`);
+  return value;
+}
+
+function currentTimestamp(now = Date.now) {
+  const value = typeof now === 'function' ? now() : now;
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new Error('Merge decision clock is invalid.');
+  return date.toISOString();
+}
 
 function normalizeFullHeadSha(value) {
   return typeof value === 'string' && FULL_HEAD_SHA.test(value) ? value.toLowerCase() : null;
@@ -84,6 +117,53 @@ function normalizeRepository(value) {
   return typeof value === 'string' && REPOSITORY_NAME.test(value) ? value.toLowerCase() : null;
 }
 
+function defaultResolveLocalRepository({ projectRoot, git = execFileSync }) {
+  try {
+    const remote = git('git', ['remote', 'get-url', 'origin'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    }).trim();
+    const scp = /^[A-Za-z]:/.test(remote) || /^(?:git|https?|ssh|file):/i.test(remote) ? null
+      : /^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9][A-Za-z0-9._-]*:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(remote);
+    if (scp) return normalizeRepository(scp[1]);
+    const parsed = new URL(remote);
+    if (!['git:', 'http:', 'https:', 'ssh:'].includes(parsed.protocol)
+      || !parsed.hostname || parsed.password || parsed.search || parsed.hash
+      || (['http:', 'https:'].includes(parsed.protocol) && parsed.username)) return null;
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    if (parts.length !== 2) return null;
+    return normalizeRepository(`${parts[0]}/${parts[1].replace(/\.git$/, '')}`);
+  } catch {
+    return null;
+  }
+}
+
+function terminalEvidenceFromTrace(row, { issueId, repository, number, expectedHead }) {
+  const normalizedExpectedHead = normalizeFullHeadSha(expectedHead);
+  if (!normalizedExpectedHead || !Array.isArray(row?.iterations)) return { invalid: true };
+  const merged = row.iterations.filter(iteration => iteration?.type === 'pr.merged');
+  if (merged.length === 0) return null;
+  if (merged.length !== 1) return { invalid: true };
+  const exact = merged.filter(iteration => iteration.issue_id === issueId
+    && Number.isInteger(iteration.issue_revision) && iteration.issue_revision >= 0
+    && normalizeFullHeadSha(iteration.head_sha) === normalizedExpectedHead
+    && typeof iteration.at === 'string' && Number.isFinite(Date.parse(iteration.at))
+    && /^[0-9a-f]{64}$/.test(iteration.work_packet_hash)
+    && /^[0-9a-f]{64}$/.test(iteration.run_receipt_hash));
+  if (exact.length !== 1) return { invalid: true };
+  const iteration = exact[0];
+  const decisionSeed = `${issueId}:${iteration.issue_revision}:${repository}:${number}:${normalizedExpectedHead}`;
+  return {
+    decisionId: uuidFromSeed(`merge-packet:${decisionSeed}`),
+    receiptId: uuidFromSeed(`merge-receipt:${iteration.work_packet_hash}`),
+    receiptHash: iteration.run_receipt_hash,
+    occurredAt: iteration.at,
+  };
+}
+
 function parseMergeArgs(argv) {
   const values = { auto: false, pr: null, expectedHead: null, issueId: null, error: null };
   const seen = new Set();
@@ -168,76 +248,343 @@ async function defaultVerifyIssueOwnership({
   if (!actor) return { owned: false, actor: null, error: 'FORGE_ACTOR or FORGE_SESSION_ID is required.' };
   const frozenEnv = { ...env, FORGE_ACTOR: actor };
   const result = await runIssue('owns', [issueId], projectRoot, { env: frozenEnv });
-  const data = result && result.data;
-  const owned = result && result.ok === true && data && data.owned === true
+  const data = result?.data;
+  const ownershipMatches = result?.ok === true && data?.owned === true
     && data.expired === false && data.actor === actor && data.claimed_by === actor;
+  const expectedSessionId = typeof env.FORGE_SESSION_ID === 'string' && env.FORGE_SESSION_ID.trim()
+    ? env.FORGE_SESSION_ID.trim()
+    : null;
+  let sessionId = null;
+  if (ownershipMatches && expectedSessionId) {
+    const claimsResult = await runIssue('claims', [], projectRoot, { env: frozenEnv });
+    const claims = claimsResult?.ok === true && Array.isArray(claimsResult.data?.claims)
+      ? claimsResult.data.claims
+      : [];
+    const exactClaims = claims.filter(claim => claim?.issue_id === issueId
+      && claim?.actor === actor && claim?.session_id === expectedSessionId);
+    sessionId = exactClaims.length === 1 ? exactClaims[0].session_id : null;
+  }
+  const owned = ownershipMatches && (!expectedSessionId || sessionId === expectedSessionId);
   return {
     owned: Boolean(owned),
     actor,
-    claimedBy: data && data.claimed_by,
-    expired: data && typeof data.expired === 'boolean' ? data.expired : null,
-    error: result && result.error,
+    claimedBy: data?.claimed_by,
+    sessionId,
+    expired: typeof data?.expired === 'boolean' ? data.expired : null,
+    error: result?.error,
+  };
+}
+
+function selectPrBindingRow(rows, repository, number, gitCommonDir = null) {
+  if (!Array.isArray(rows)) return { error: 'Kernel PR linkage is unreadable.' };
+  const repositoryRows = repository
+    ? rows.filter(row => normalizeRepository(row?.repo) === repository)
+    : rows;
+  const candidateRows = gitCommonDir
+    ? repositoryRows.filter(row => row?.git_common_dir === gitCommonDir)
+    : repositoryRows;
+  if (candidateRows.some(row => !normalizeKernelPrNumber(row.number))) {
+    return { error: 'Kernel PR linkage contains a malformed PR number.' };
+  }
+  const matches = candidateRows.filter(row => normalizeKernelPrNumber(row.number) === number);
+  if (matches.length === 0) return { missing: true, error: 'Kernel PR linkage is missing.' };
+  if (matches.length > 1) return { error: 'Kernel PR linkage is ambiguous.' };
+  if (!normalizeRepository(matches[0]?.repo)) return { error: 'Kernel PR repository identity is unreadable.' };
+  return { row: matches[0] };
+}
+
+async function openPrBindingBroker(projectRoot, buildBroker) {
+  if (buildBroker) {
+    const built = await buildBroker({ projectRoot });
+    return { built, ownsDriver: false };
+  }
+  const { resolveGitCommonDir } = require('../kernel/broker');
+  const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+  const gitCommonDir = resolveGitCommonDir(projectRoot);
+  const deps = await buildMigratedKernelIssueDeps({ projectRoot, gitCommonDir });
+  return {
+    built: { gitCommonDir, broker: deps.kernelBroker, driver: deps.kernelDriver },
+    ownsDriver: true,
   };
 }
 
+async function readPrBindingRows(built, allowRetired, { issueId, number, repository }) {
+  if (allowRetired) {
+    const target = {
+      issue_id: issueId,
+      pr_number: Number(number),
+      git_common_dir: built.gitCommonDir,
+    };
+    if (repository) target.repo = repository;
+    const read = await built.broker.readTrace(target);
+    return { rows: read?.pull_requests, gaps: read?.gaps };
+  }
+  return { rows: await built.broker.listOpenPrs(built.gitCommonDir), gaps: [] };
+}
+
+function terminalTraceGapKind(gap) {
+  if (typeof gap !== 'string') return null;
+  if (/^(?:issue|worktree|work_folder|pull_requests|(?:plan|tasks|decisions)(?::(?:outside_project|oversized))?)$/.test(gap)) {
+    return 'benign';
+  }
+  if (gap === 'pull_requests:overflow'
+    || /^pull_requests:[^:]+:unlinked_issue$/.test(gap)
+    || /^iterations:[^:]+:(?:missing|incomplete|overflow)$/.test(gap)) {
+    return 'authority';
+  }
+  return null;
+}
+
+function terminalTraceIsIncomplete(gaps, row) {
+  if (!Array.isArray(gaps) || gaps.some(gap => terminalTraceGapKind(gap) === null)) return true;
+  const rowId = typeof row?.id === 'string' && row.id ? row.id : null;
+  return gaps.some((gap) => {
+    if (gap === 'pull_requests:overflow') return true;
+    if (rowId && gap === `pull_requests:${rowId}:unlinked_issue`) return true;
+    if (!/^iterations:[^:]+:(?:missing|incomplete|overflow)$/.test(gap)) return false;
+    return !rowId || ['missing', 'incomplete', 'overflow']
+      .some(suffix => gap === `iterations:${rowId}:${suffix}`);
+  });
+}
+
+function terminalTraceAbsenceIsClean(gaps) {
+  return Array.isArray(gaps) && gaps.every(gap => terminalTraceGapKind(gap) === 'benign');
+}
+
 async function defaultVerifyPrIssueBinding({
   issueId,
   pr,
   projectRoot,
   prContext,
   buildBroker,
+  allowRetired = false,
 }) {
   const number = normalizePrNumber(String(pr));
-  const repository = normalizeRepository(prContext && prContext.repository);
-  if (!number || !repository || !prContext || prContext.number !== Number(number)) {
+  let repository = normalizeRepository(prContext?.repository);
+  if (!number || !prContext || prContext.number !== Number(number) || (!allowRetired && !repository)) {
     return { bound: false, error: 'PR identity is unreadable or does not match the requested PR number.' };
   }
 
   let built;
-  const ownsDriver = !buildBroker;
+  let ownsDriver = false;
   try {
-    if (buildBroker) {
-      built = await buildBroker({ projectRoot });
-    } else {
-      const { resolveGitCommonDir } = require('../kernel/broker');
-      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
-      const gitCommonDir = resolveGitCommonDir(projectRoot);
-      const deps = await buildMigratedKernelIssueDeps({ projectRoot, gitCommonDir });
-      built = { gitCommonDir, broker: deps.kernelBroker, driver: deps.kernelDriver };
-    }
-    if (!built || !built.broker || typeof built.broker.listOpenPrs !== 'function'
+    ({ built, ownsDriver } = await openPrBindingBroker(projectRoot, buildBroker));
+    const linkageReader = allowRetired ? built?.broker?.readTrace : built?.broker?.listOpenPrs;
+    if (!built?.broker || typeof linkageReader !== 'function'
       || typeof built.gitCommonDir !== 'string' || !built.gitCommonDir) {
       return { bound: false, error: 'Kernel PR linkage reader is unavailable.' };
     }
-    const rows = await built.broker.listOpenPrs(built.gitCommonDir);
-    if (!Array.isArray(rows)) return { bound: false, error: 'Kernel PR linkage is unreadable.' };
-    const sameRepositoryRows = rows.filter((row) => row && normalizeRepository(row.repo) === repository);
-    if (sameRepositoryRows.some((row) => !normalizeKernelPrNumber(row.number))) {
-      return { bound: false, error: 'Kernel PR linkage contains a malformed PR number.' };
+    const linkage = await readPrBindingRows(built, allowRetired, { issueId, number, repository });
+    const { rows } = linkage;
+    const selection = selectPrBindingRow(
+      rows,
+      repository,
+      number,
+      allowRetired ? built.gitCommonDir : null,
+    );
+    if (!selection.row) {
+      const cleanRetiredAbsence = allowRetired && selection.missing === true
+        && terminalTraceAbsenceIsClean(linkage.gaps);
+      return {
+        bound: false,
+        error: cleanRetiredAbsence
+          ? selection.error
+          : (selection.missing === true && allowRetired
+            ? 'Kernel merged PR evidence is incomplete or ambiguous.'
+            : selection.error),
+        ...(cleanRetiredAbsence ? { missing: true } : {}),
+      };
+    }
+    const { row } = selection;
+    repository = repository || normalizeRepository(row.repo);
+    const bound = (allowRetired || row.state === 'open') && row.issue_id === issueId;
+    if (allowRetired && bound && terminalTraceIsIncomplete(linkage.gaps, row)) {
+      return { bound: false, error: 'Kernel merged PR evidence is incomplete or ambiguous.' };
     }
-    const matches = sameRepositoryRows.filter((row) => row
-      && normalizeKernelPrNumber(row.number) === number);
-    if (matches.length !== 1) {
-      return { bound: false, error: 'Kernel PR linkage is missing or ambiguous.' };
+    const terminalEvidence = allowRetired && bound
+      ? terminalEvidenceFromTrace(row, {
+        issueId,
+        repository,
+        number: Number(number),
+        expectedHead: normalizeFullHeadSha(prContext?.headSha),
+      })
+      : null;
+    if (terminalEvidence?.invalid) {
+      return { bound: false, error: 'Kernel merged PR evidence is incomplete or ambiguous.' };
     }
-    const row = matches[0];
-    const bound = row.state === 'open' && row.issue_id === issueId;
     return {
       bound,
       repository,
       number: Number(number),
       issueId: row.issue_id || null,
-      error: bound ? null : 'Kernel PR row is not open or is linked to a different issue.',
+      branch: row.branch || null,
+      url: row.url || null,
+      gitCommonDir: row.git_common_dir || built.gitCommonDir,
+      error: bound ? null : (allowRetired
+        ? 'Kernel PR row is linked to a different issue.'
+        : 'Kernel PR row is not open or is linked to a different issue.'),
+      ...(terminalEvidence ? { terminalEvidence } : {}),
     };
   } catch (err) {
     return { bound: false, error: `Kernel PR linkage verification failed: ${err.message}` };
   } finally {
-    if (ownsDriver && built && built.driver && typeof built.driver.close === 'function') {
+    if (ownsDriver && typeof built?.driver?.close === 'function') {
       try { await built.driver.close(); } catch { /* cleanup must not mask the linkage verdict */ }
     }
   }
 }
 
+async function defaultVerifyMergeGate({ issueId, projectRoot, now }) {
+  const result = await gateCommand.handler(
+    ['check', issueId, MERGE_GATE],
+    {},
+    projectRoot,
+    { now },
+  );
+  return result;
+}
+
+async function defaultPrepareMergeDecision({
+  issueId,
+  pr,
+  expectedHead,
+  repository,
+  binding,
+  actor,
+  sessionId,
+  requireMergeGate = true,
+  config,
+  projectRoot,
+  env = process.env,
+  now = Date.now,
+  runIssue = runIssueOperation,
+}) {
+  if (requireMergeGate !== true) {
+    throw new Error('A disabled merge gate cannot produce broker-verifiable terminal authority.');
+  }
+  const timestamp = currentTimestamp(now);
+  const frozenEnv = { ...env, FORGE_ACTOR: actor };
+  if (sessionId) frozenEnv.FORGE_SESSION_ID = sessionId;
+  else delete frozenEnv.FORGE_SESSION_ID;
+  const issue = await runIssue('show', [issueId], projectRoot, {
+    env: frozenEnv,
+  });
+  const revision = issue?.data?.revision;
+  if (issue?.ok !== true || !Number.isInteger(revision) || revision < 0) {
+    throw new Error('Live issue revision is unavailable for the merge decision.');
+  }
+  if (!binding || typeof binding.branch !== 'string' || !binding.branch
+    || typeof binding.gitCommonDir !== 'string' || !binding.gitCommonDir) {
+    throw new Error('Authoritative PR branch/worktree linkage is unavailable for the merge decision.');
+  }
+  const capabilityDigest = computeContentHash({ capability: 'forge.merge.exact-head.v1' });
+  const workflowConfigRevision = computeContentHash({ merge: config.merge?.auto ?? null });
+  const riskManifestDigest = computeContentHash({ rules: config.merge?.auto?.rules ?? [] });
+  const decisionSeed = `${issueId}:${revision}:${repository}:${pr}:${expectedHead}`;
+  const packet = contractEnvelope(
+    'forge.memory.work-packet.v1',
+    uuidFromSeed(`merge-packet:${decisionSeed}`),
+    timestamp,
+    actor,
+    {
+      issue_id: issueId,
+      expected_issue_revision: revision,
+      packet_id: `merge:${decisionSeed}`,
+      packet_revision: 1,
+      repository_id: repository,
+      target_head: expectedHead,
+      objective: `Guarded exact-head merge of ${repository}#${pr}`,
+      authority: { kind: 'kernel-live-lease', issue_revision: revision },
+      allowed_mutations: ['pr.merged'],
+      prohibited_actions: ['pr.opened', 'review-thread.resolve'],
+      workflow_config_revision: workflowConfigRevision,
+      capability_manifest_digest: capabilityDigest,
+      risk_manifest_digest: riskManifestDigest,
+      receipt_requirements: { gate_ids: requireMergeGate ? [MERGE_GATE] : [] },
+      target: {
+        pr_number: Number(pr),
+        branch: binding.branch,
+        git_common_dir: binding.gitCommonDir,
+        ...(binding.url ? { url: binding.url } : {}),
+      },
+    },
+  );
+  return {
+    decisionId: packet.object_id,
+    packet,
+    occurredAt: timestamp,
+    actor,
+    sessionId: sessionId || null,
+    binding: { ...binding },
+  };
+}
+
+async function defaultRecordMergeDecision({ decision, mergeResult, pr, expectedHead, repository, projectRoot, buildBroker }) {
+  if (!decision?.packet || !decision?.binding) throw new Error('Merge decision evidence is unavailable.');
+  const recovered = mergeResult?.recovered === true;
+  const receipt = contractEnvelope(
+    'forge.memory.run-receipt.v1',
+    uuidFromSeed(`merge-receipt:${decision.packet.content_hash}`),
+    decision.occurredAt,
+    decision.actor,
+    {
+      packet_hash: decision.packet.content_hash,
+      run_id: `merge:${repository}:${pr}:${expectedHead}`,
+      attempt_id: `merge:${expectedHead}`,
+      exact_head: expectedHead,
+      packet_revision: decision.packet.payload.packet_revision,
+      manifest_digest: decision.packet.payload.capability_manifest_digest,
+      workflow_config_revision: decision.packet.payload.workflow_config_revision,
+      status: 'PASS',
+      executor: { product_id: 'forge', mode: recovered ? 'guarded-exact-head-recovery' : 'guarded-exact-head' },
+      started_at: decision.occurredAt,
+      ended_at: decision.occurredAt,
+      evidence_refs: [{ kind: 'pr', repository, pr_number: Number(pr), head_sha: expectedHead }],
+      validation: { status: 'PASS', decision_id: decision.decisionId },
+      cleanup: { status: 'NOT_REQUIRED' },
+      mutations_attempted: ['pr.merged'],
+      mutations_authorized: ['pr.merged'],
+    },
+  );
+
+  let built;
+  const ownsDriver = !buildBroker;
+  try {
+    if (buildBroker) built = await buildBroker({ projectRoot });
+    else {
+      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+      const deps = await buildMigratedKernelIssueDeps({
+        projectRoot,
+        gitCommonDir: decision.binding.gitCommonDir,
+      });
+      built = { broker: deps.kernelBroker, driver: deps.kernelDriver };
+    }
+    if (!built?.broker) throw new Error('Kernel lifecycle provider is unavailable.');
+    const { createMemoryAuthorityProvider } = require('@forge/memory');
+    const provider = createMemoryAuthorityProvider({ broker: built.broker });
+    await provider.recordPrLinkage({
+      phase: 'merged',
+      git_common_dir: decision.binding.gitCommonDir,
+      repo: repository,
+      number: Number(pr),
+      branch: decision.binding.branch,
+      ...(decision.binding.url ? { url: decision.binding.url } : {}),
+      occurred_at: decision.occurredAt,
+      work_packet: decision.packet,
+      run_receipt: receipt,
+    }, {
+      actor: decision.actor,
+      sessionId: decision.sessionId,
+      requireExactLifecycleOwnership: true,
+    });
+    return { receiptId: receipt.object_id, receiptHash: receipt.content_hash };
+  } finally {
+    if (ownsDriver && built?.driver && typeof built.driver.close === 'function') {
+      try { await built.driver.close(); } catch { /* terminal evidence outcome remains authoritative */ }
+    }
+  }
+}
+
 function strictCheckSuccess(check) {
   if (!check || typeof check !== 'object') return false;
   const hasStatus = Object.prototype.hasOwnProperty.call(check, 'status');
@@ -419,15 +766,121 @@ function mandatoryContextError(context, expectedHead) {
   return protectedGate.allowed ? null : protectedGate.reason;
 }
 
+async function recoverMergedTerminal({
+  pr, parsed, root, config, prContext, ownershipActor, ownershipSessionId, deps, replayOnly = false,
+}) {
+  if (normalizeFullHeadSha(prContext?.headSha) !== parsed.expectedHead) {
+    return { success: false, merged: true, error: 'Merged PR identity does not match the expected head and repository.' };
+  }
+  const verifyPrIssueBinding = deps.verifyPrIssueBinding || defaultVerifyPrIssueBinding;
+  const binding = await verifyPrIssueBinding({
+    issueId: parsed.issueId,
+    pr,
+    projectRoot: root,
+    prContext,
+    buildBroker: deps.buildPrBindingBroker,
+    allowRetired: true,
+  });
+  const repository = normalizeRepository(prContext?.repository) || normalizeRepository(binding?.repository);
+  if (binding?.bound !== true) {
+    if (replayOnly && binding?.missing === true) {
+      return {
+        success: false,
+        merged: true,
+        replayMissing: true,
+        error: 'Merged PR terminal evidence is not yet available for replay.',
+      };
+    }
+    return { success: false, merged: true, error: 'Merged PR is not authoritatively linked to the supplied Forge issue.' };
+  }
+  if (binding.terminalEvidence) {
+    if (!repository) {
+      return { success: false, merged: true, error: 'Merged PR repository identity is unavailable.' };
+    }
+    return {
+      success: true, merged: true, enabled: true, recovered: true,
+      ...binding.terminalEvidence,
+    };
+  }
+  if (replayOnly) {
+    return {
+      success: false,
+      merged: true,
+      replayMissing: true,
+      error: 'Merged PR terminal evidence is not yet available for replay.',
+    };
+  }
+  if (!repository) {
+    return { success: false, merged: true, error: 'Merged PR repository identity is unavailable.' };
+  }
+  const decisionAt = currentTimestamp(deps.now || Date.now);
+  const verifyMergeGate = deps.verifyMergeGate || defaultVerifyMergeGate;
+  const gateApproval = await verifyMergeGate({
+    issueId: parsed.issueId, projectRoot: root, actor: ownershipActor, now: decisionAt,
+  });
+  if (gateApproval !== true && gateApproval?.approved !== true && gateApproval?.disabled !== true) {
+    return { success: false, merged: true, error: `${MERGE_GATE} is not approved for this issue.` };
+  }
+  if (gateApproval?.disabled === true) {
+    return {
+      success: false,
+      merged: true,
+      error: 'The disabled merge gate cannot produce broker-verifiable terminal authority.',
+    };
+  }
+  const prepareMergeDecision = deps.prepareMergeDecision || defaultPrepareMergeDecision;
+  const decision = await prepareMergeDecision({
+    issueId: parsed.issueId,
+    pr,
+    expectedHead: parsed.expectedHead,
+    repository,
+    binding,
+    actor: ownershipActor,
+    sessionId: ownershipSessionId,
+    env: deps.env || process.env,
+    requireMergeGate: gateApproval?.disabled !== true,
+    config,
+    projectRoot: root,
+    now: decisionAt,
+  });
+  if (!decision || typeof decision.decisionId !== 'string' || !decision.decisionId) {
+    return { success: false, merged: true, error: 'Merge recovery decision evidence is unavailable.' };
+  }
+  const recordMergeDecision = deps.recordMergeDecision || defaultRecordMergeDecision;
+  try {
+    const terminal = await recordMergeDecision({
+      decision,
+      mergeResult: { merged: true, recovered: true },
+      pr,
+      expectedHead: parsed.expectedHead,
+      repository,
+      projectRoot: root,
+      buildBroker: deps.buildMergeBroker,
+    });
+    if (!terminal || typeof terminal.receiptId !== 'string' || !terminal.receiptId) {
+      throw new Error('terminal receipt evidence is unavailable');
+    }
+    return {
+      success: true, merged: true, enabled: true, recovered: true,
+      decisionId: decision.decisionId, ...terminal,
+    };
+  } catch (error) {
+    return {
+      success: false, merged: true, enabled: true, decisionId: decision.decisionId,
+      error: `Merged PR terminal linkage recovery failed: ${error.message}`,
+    };
+  }
+}
+
 /** Default `gh` runner. Only reached by the default fetch/merge seams (never in unit tests). */
 function defaultGh(args, options = {}) {
   return execFileSync('gh', args, { encoding: 'utf8', ...options }); // NOSONAR S4036 - hardcoded CLI (gh), args array (no shell), developer-tool context
 }
 
 /** Parse `gh ... --json` output, returning `null` on any failure (callers fail closed). */
-function ghJson(gh, args) {
+function ghJson(gh, args, options) {
   try {
-    return JSON.parse(gh(args) || '{}');
+    return JSON.parse(gh(args, options) || '{}');
   } catch (_err) {
     return null;
   }
@@ -523,9 +976,20 @@ function fetchCheckRunObservations(gh, { owner, repo, head }) {
  *
  * @returns {object} prContext
  */
-async function defaultFetchPrContext({ pr, gh = defaultGh, now = Date.now() }) {
-  const view = ghJson(gh, ['pr', 'view', String(pr), '--json',
-    'number,headRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,statusCheckRollup,comments,updatedAt']) || {};
+async function defaultFetchPrContext({ pr, projectRoot, gh = defaultGh, now = Date.now() }) {
+  const repoOptions = typeof projectRoot === 'string' && projectRoot ? { cwd: projectRoot } : undefined;
+  const repoIdentity = ghJson(gh, ['repo', 'view', '--json', 'owner,name,isFork,parent'], repoOptions);
+  const currentRepository = normalizeRepository(repoIdentity?.owner?.login && repoIdentity?.name
+    ? `${repoIdentity.owner.login}/${repoIdentity.name}`
+    : null);
+  const repository = repoIdentity?.isFork === true
+    ? normalizeRepository(repoIdentity?.parent?.nameWithOwner)
+    : (repoIdentity?.isFork === false ? currentRepository : null);
+  const [owner, repo] = repository ? repository.split('/') : [null, null];
+  const view = repository
+    ? (ghJson(gh, ['pr', 'view', String(pr), '--repo', repository, '--json',
+      'number,headRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,statusCheckRollup,comments,updatedAt']) || {})
+    : {};
 
   const rollup = Array.isArray(view.statusCheckRollup) ? view.statusCheckRollup : null;
 
@@ -538,9 +1002,6 @@ async function defaultFetchPrContext({ pr, gh = defaultGh, now = Date.now() }) {
     }))
     : [];
 
-  const repoIdentity = ghJson(gh, ['repo', 'view', '--json', 'owner,name']);
-  const owner = repoIdentity && repoIdentity.owner && repoIdentity.owner.login;
-  const repo = repoIdentity && repoIdentity.name;
   const adapter = owner && repo
     ? new PrStateAdapter({ gh: (_cmd, adapterArgs) => gh(adapterArgs) })
     : null;
@@ -599,7 +1060,7 @@ async function defaultFetchPrContext({ pr, gh = defaultGh, now = Date.now() }) {
 
   return {
     number: Number.isInteger(view.number) ? view.number : null,
-    repository: owner && repo ? `${owner}/${repo}` : null,
+    repository,
     headSha: view.headRefOid || null,
     checks,
     providerObservations,
@@ -627,6 +1088,10 @@ function defaultMergePr({ pr, expectedHead, repository, gh = defaultGh }) {
   if (!head) throw new Error('A full 40-character expected PR head SHA is required.');
   if (!normalizePrNumber(String(pr)) || !repo) throw new Error('A canonical PR number and repository are required.');
   gh(['pr', 'merge', String(pr), '--repo', repo, '--squash', '--match-head-commit', head]);
+  const confirmed = ghJson(gh, ['pr', 'view', String(pr), '--repo', repo, '--json', 'state,headRefOid']);
+  if (confirmed?.state !== 'MERGED' || normalizeFullHeadSha(confirmed.headRefOid) !== head) {
+    return { merged: false, reason: 'provider merge is not confirmed for the exact reviewed head' };
+  }
   return { merged: true, method: 'squash' };
 }
 
@@ -653,6 +1118,69 @@ async function handler(args, _flags, projectRoot, deps = {}) {
     };
   }
 
+  const verifyIssueOwnership = deps.verifyIssueOwnership || defaultVerifyIssueOwnership;
+  const ownershipEnv = deps.env || process.env;
+  const ownershipActor = resolveOwnershipActor(ownershipEnv);
+  const ownershipSessionId = typeof ownershipEnv.FORGE_SESSION_ID === 'string'
+    && ownershipEnv.FORGE_SESSION_ID.trim()
+    ? ownershipEnv.FORGE_SESSION_ID.trim()
+    : null;
+  const ownershipInput = {
+    issueId: parsed.issueId,
+    projectRoot: root,
+    actor: ownershipActor,
+    env: { ...ownershipEnv },
+  };
+  const fetchPrContext = deps.fetchPrContext || defaultFetchPrContext;
+  const mergePr = deps.mergePr || defaultMergePr;
+  const verifyPrIssueBinding = deps.verifyPrIssueBinding || defaultVerifyPrIssueBinding;
+  const gh = deps.githubContext?.bound ? deps.githubContext.runGh : (deps.gh || defaultGh);
+  const exactMergeIdentity = !parsed.error && parsed.expectedHead && parsed.issueId;
+  let prContext; let prState;
+  const replayBeforeProvider = async () => {
+    const resolveLocalRepository = deps.resolveLocalRepository || defaultResolveLocalRepository;
+    let localRepository;
+    try {
+      localRepository = normalizeRepository(await resolveLocalRepository({ projectRoot: root }));
+    } catch {
+      localRepository = null;
+    }
+    if (!localRepository) {
+      return { failure: {
+        success: false,
+        merged: false,
+        error: 'Local repository identity is unavailable for terminal evidence replay.',
+      } };
+    }
+    try {
+      const replay = await recoverMergedTerminal({
+        pr,
+        parsed,
+        root,
+        config: {},
+        prContext: {
+          number: Number(pr),
+          headSha: parsed.expectedHead,
+          repository: localRepository,
+        },
+        ownershipActor,
+        ownershipSessionId,
+        deps,
+        replayOnly: true,
+      });
+      if (replay.replayMissing !== true) {
+        return replay.success ? { replay } : { failure: { ...replay, merged: false } };
+      }
+    } catch (error) {
+      return { failure: {
+        success: false,
+        merged: false,
+        error: `Merged PR terminal evidence replay failed: ${error.message}`,
+      } };
+    }
+    return {};
+  };
+
   const loadConfig = deps.loadConfig || loadRawConfig;
   let config;
   try {
@@ -675,7 +1203,6 @@ async function handler(args, _flags, projectRoot, deps = {}) {
     process.stdout.write(`${reason}\n`);
     return { success: true, merged: false, enabled: false, reason };
   }
-
   // Opted in but no rules → refuse (fail-closed): an empty ruleset is vacuously
   // "allowed", which would merge unconditionally. Treat that as misconfiguration.
   if (rules.length === 0) {
@@ -684,21 +1211,12 @@ async function handler(args, _flags, projectRoot, deps = {}) {
     return { success: false, merged: false, enabled: true, reason };
   }
 
-  if (parsed.error || !parsed.expectedHead || !parsed.issueId) {
+  if (!exactMergeIdentity) {
     const reason = parsed.error
       || 'Enabled auto-merge requires --expect-head <full 40-character SHA> and --issue <Forge issue ID>.';
     return { success: false, merged: false, enabled: true, error: reason };
   }
 
-  const verifyIssueOwnership = deps.verifyIssueOwnership || defaultVerifyIssueOwnership;
-  const ownershipEnv = deps.env || process.env;
-  const ownershipActor = resolveOwnershipActor(ownershipEnv);
-  const ownershipInput = {
-    issueId: parsed.issueId,
-    projectRoot: root,
-    actor: ownershipActor,
-    env: { ...ownershipEnv },
-  };
   let ownership;
   try {
     ownership = await verifyIssueOwnership(ownershipInput);
@@ -707,35 +1225,55 @@ async function handler(args, _flags, projectRoot, deps = {}) {
   }
   if (!ownership || ownership.owned !== true || ownership.expired !== false
     || typeof ownership.actor !== 'string' || ownership.actor !== ownershipActor
-    || typeof ownership.claimedBy !== 'string' || ownership.claimedBy !== ownershipActor) {
+    || typeof ownership.claimedBy !== 'string' || ownership.claimedBy !== ownershipActor
+    || ownership.sessionId !== ownershipSessionId) {
     return {
       success: false,
       merged: false,
-      error: `Active Kernel ownership claim is required for issue ${parsed.issueId}; refusing to merge.`,
+      error: `Active Kernel ownership claim with the exact session is required for issue ${parsed.issueId}; refusing to merge.`,
     };
   }
+  const preProvider = await replayBeforeProvider();
+  if (preProvider.failure) return preProvider.failure;
+  if (preProvider.replay) return preProvider.replay;
 
-  const fetchPrContext = deps.fetchPrContext || defaultFetchPrContext;
-  const mergePr = deps.mergePr || defaultMergePr;
-  const verifyPrIssueBinding = deps.verifyPrIssueBinding || defaultVerifyPrIssueBinding;
-  const gh = deps.gh || defaultGh;
-
-  let prContext;
   try {
     prContext = await fetchPrContext({ pr, projectRoot: root, gh, now: deps.now || Date.now() });
   } catch (err) {
     return { success: false, merged: false, error: `Failed to fetch PR context: ${err.message}` };
   }
+  prState = prContext?.state ? String(prContext.state).toUpperCase() : '';
+  if (prState === 'MERGED') {
+    try {
+      const replay = await recoverMergedTerminal({
+        pr, parsed, root, config: {}, prContext, ownershipActor, ownershipSessionId, deps, replayOnly: true,
+      });
+      if (replay.replayMissing !== true) return replay;
+    } catch (error) {
+      return { success: false, merged: true, error: `Merged PR terminal evidence replay failed: ${error.message}` };
+    }
+  }
 
-  // Pre-flight: a PR that is already merged or closed is terminal. Re-running the
-  // command must be an idempotent NO-OP — never an error and never a second merge
-  // attempt. (An absent/unknown state falls through to the fail-closed rules.)
-  const prState = prContext && prContext.state ? String(prContext.state).toUpperCase() : '';
-  if (prState === 'MERGED' || prState === 'CLOSED') {
+  if (prState === 'MERGED') {
+    if (!ownershipSessionId) {
+      return { success: false, merged: true, error: 'An exact FORGE_SESSION_ID session identity is required to recover terminal merge evidence.' };
+    }
+    try {
+      return await recoverMergedTerminal({
+        pr, parsed, root, config, prContext, ownershipActor, ownershipSessionId, deps,
+      });
+    } catch (error) {
+      return { success: false, merged: true, error: `Merged PR terminal linkage recovery failed: ${error.message}` };
+    }
+  }
+  if (prState === 'CLOSED') {
     const reason = `PR #${pr} is ${prState} (not OPEN) — nothing to merge. No action taken.`;
     process.stdout.write(`${reason}\n`);
     return { success: true, merged: false, enabled: true, state: prState, reason };
   }
+  if (!ownershipSessionId) {
+    return { success: false, merged: false, error: 'An exact FORGE_SESSION_ID session identity is required before merge.' };
+  }
 
   const mandatoryError = mandatoryContextError(prContext, parsed.expectedHead);
   if (mandatoryError) return { success: false, merged: false, error: mandatoryError };
@@ -784,7 +1322,16 @@ async function handler(args, _flags, projectRoot, deps = {}) {
   // Re-apply the terminal-state guard on the FRESH context: the PR may have been
   // merged or closed between the first fetch and now. Never merge a terminal PR.
   const freshState = freshContext && freshContext.state ? String(freshContext.state).toUpperCase() : '';
-  if (freshState === 'MERGED' || freshState === 'CLOSED') {
+  if (freshState === 'MERGED') {
+    try {
+      return await recoverMergedTerminal({
+        pr, parsed, root, config, prContext: freshContext, ownershipActor, ownershipSessionId, deps,
+      });
+    } catch (error) {
+      return { success: false, merged: true, error: `Merged PR terminal linkage recovery failed: ${error.message}` };
+    }
+  }
+  if (freshState === 'CLOSED') {
     const reason = `PR #${pr} became ${freshState} (not OPEN) before merge — nothing to merge. No action taken.`;
     process.stdout.write(`${reason}\n`);
     return { success: true, merged: false, enabled: true, state: freshState, reason };
@@ -828,12 +1375,62 @@ async function handler(args, _flags, projectRoot, deps = {}) {
   }
   if (!finalOwnership || finalOwnership.owned !== true || finalOwnership.expired !== false
     || typeof finalOwnership.actor !== 'string' || finalOwnership.actor !== ownershipActor
-    || typeof finalOwnership.claimedBy !== 'string' || finalOwnership.claimedBy !== ownershipActor) {
+    || typeof finalOwnership.claimedBy !== 'string' || finalOwnership.claimedBy !== ownershipActor
+    || finalOwnership.sessionId !== ownershipSessionId) {
     return { success: false, merged: false, error: 'Kernel ownership changed or expired before merge; refusing to merge.' };
   }
 
+  const decisionAt = currentTimestamp(deps.now || Date.now);
+  const verifyMergeGate = deps.verifyMergeGate || defaultVerifyMergeGate;
+  let gateApproval;
+  try {
+    gateApproval = await verifyMergeGate({
+      issueId: parsed.issueId,
+      projectRoot: root,
+      actor: ownershipActor,
+      now: decisionAt,
+    });
+  } catch (err) {
+    return { success: false, merged: false, error: `Failed to verify ${MERGE_GATE}: ${err.message}` };
+  }
+  if (gateApproval !== true && gateApproval?.approved !== true && gateApproval?.disabled !== true) {
+    return { success: false, merged: false, error: `${MERGE_GATE} is not approved for this issue.` };
+  }
+  if (gateApproval?.disabled === true) {
+    return {
+      success: false,
+      merged: false,
+      error: 'The disabled merge gate cannot produce broker-verifiable terminal authority; refusing to mutate GitHub.',
+    };
+  }
+
+  const prepareMergeDecision = deps.prepareMergeDecision || defaultPrepareMergeDecision;
+  let decision;
   try {
-    const mergeResult = await mergePr({
+    decision = await prepareMergeDecision({
+      issueId: parsed.issueId,
+      pr,
+      expectedHead: parsed.expectedHead,
+      repository: leasedRepository,
+      binding: freshBinding,
+      actor: ownershipActor,
+      sessionId: ownershipSessionId,
+      env: ownershipEnv,
+      requireMergeGate: gateApproval?.disabled !== true,
+      config,
+      projectRoot: root,
+      now: decisionAt,
+    });
+  } catch (err) {
+    return { success: false, merged: false, error: `Failed to prepare merge decision: ${err.message}` };
+  }
+  if (!decision || typeof decision.decisionId !== 'string' || !decision.decisionId) {
+    return { success: false, merged: false, error: 'Merge decision evidence is unavailable.' };
+  }
+
+  let mergeResult;
+  try {
+    mergeResult = await mergePr({
       pr,
       expectedHead: parsed.expectedHead,
       repository: leasedRepository,
@@ -841,28 +1438,78 @@ async function handler(args, _flags, projectRoot, deps = {}) {
       projectRoot: root,
       gh,
     });
-    process.stdout.write(`All ${rules.length} merge rule(s) passed — merged PR #${pr}.\n`);
+  } catch (err) {
+    return { success: false, merged: false, decisionId: decision.decisionId, error: `Merge failed: ${err.message}` };
+  }
+  if (mergeResult?.merged !== true) {
+    return {
+      success: false,
+      merged: false,
+      decisionId: decision.decisionId,
+      error: `Merge failed: ${mergeResult?.reason || 'provider did not confirm the merge'}`,
+    };
+  }
+
+  const recordMergeDecision = deps.recordMergeDecision || defaultRecordMergeDecision;
+  let terminal;
+  try {
+    terminal = await recordMergeDecision({
+      decision,
+      mergeResult,
+      pr,
+      expectedHead: parsed.expectedHead,
+      repository: leasedRepository,
+      projectRoot: root,
+      buildBroker: deps.buildMergeBroker,
+    });
+  } catch (err) {
     return {
-      success: true,
+      success: false,
       merged: true,
       enabled: true,
       allowed: true,
-      reason: 'all merge rules passed',
-      ...(mergeResult && typeof mergeResult === 'object' ? mergeResult : {}),
+      decisionId: decision.decisionId,
+      error: `Merge succeeded but terminal linkage failed: ${err.message}`,
     };
-  } catch (err) {
-    return { success: false, merged: false, error: `Merge failed: ${err.message}` };
   }
+  if (!terminal || typeof terminal.receiptId !== 'string' || !terminal.receiptId) {
+    return {
+      success: false,
+      merged: true,
+      enabled: true,
+      allowed: true,
+      decisionId: decision.decisionId,
+      error: 'Merge succeeded but terminal receipt evidence is unavailable.',
+    };
+  }
+
+  process.stdout.write(`All ${rules.length} merge rule(s) passed — merged PR #${pr}.\n`);
+  const providerFields = typeof mergeResult?.method === 'string' ? { method: mergeResult.method } : {};
+  return {
+    ...providerFields,
+    success: true,
+    merged: true,
+    enabled: true,
+    allowed: true,
+    reason: 'all merge rules passed',
+    decisionId: decision.decisionId,
+    ...terminal,
+  };
 }
 
 module.exports = {
   name: 'merge',
+  githubAuth: true,
   description: 'Opt-in conditional auto-merge: merge a PR only when all user-configured rules pass (OFF by default)',
   usage: 'Usage: forge merge --auto <pr> --expect-head <40-char-sha> --issue <issue-id>',
   handler,
   // Exported seams for testing / reuse.
   defaultFetchPrContext,
+  defaultResolveLocalRepository,
   defaultMergePr,
+  defaultPrepareMergeDecision,
+  defaultRecordMergeDecision,
+  defaultVerifyMergeGate,
   defaultVerifyPrIssueBinding,
   defaultVerifyIssueOwnership,
   evaluateProtectedRequiredChecks,