forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/commands/_registry.js

@@ -13,6 +13,7 @@ const { existsSync, readdirSync } = require('node:fs');
 const path = require('node:path');
 const { normalizeStageId } = require('../workflow/stages');
 const { ensureForgeHome, isMutatingVerb } = require('../activation/ensure-forge-home');
+const { createGithubContext } = require('../github-context');
 
 // Static command manifest (bundleable fast path). This is a static require so
 // `bun build --compile` can bundle the command graph; the file is generated by
@@ -36,6 +37,7 @@ try {
  * @property {function(Array, Object, string, Object=): Promise<*>} handler - Async command handler (4th arg: resolved command opts)
  * @property {string} [usage] - Usage string (optional)
  * @property {Object<string, string>} [flags] - Flag descriptions (optional)
+ * @property {boolean|function(Array, Object, Object): boolean} [githubAuth] - Whether this invocation needs repository GitHub context
  */
 
 /**
@@ -57,6 +59,9 @@ function validateCommand(mod) {
   if (typeof mod.handler !== 'function') {
     return { valid: false, reason: 'missing or invalid "handler" export' };
   }
+  if (mod.githubAuth !== undefined && !['boolean', 'function'].includes(typeof mod.githubAuth)) {
+    return { valid: false, reason: 'invalid "githubAuth" export: expected boolean or function' };
+  }
   return { valid: true };
 }
 
@@ -174,6 +179,31 @@ function isStageCommand(commandName) {
   return normalizeStageId(commandName) !== null;
 }
 
+function isHelpInvocation(args, flags) {
+  if (flags.help || flags['--help'] || flags['-h']) return true;
+  // Child arguments belong to the launcher, including its help flags.
+  const delimiter = args.indexOf('--');
+  const ownArgs = delimiter === -1 ? args : args.slice(0, delimiter);
+  return ownArgs.includes('--help') || ownArgs.includes('-h');
+}
+
+async function enforceCommandStage(options, commandName, args, flags, projectRoot, command) {
+  if (typeof options.enforceStage !== 'function' || !isStageCommand(commandName)) return null;
+  return options.enforceStage({ commandName, args, flags, projectRoot, command });
+}
+
+async function resolveCommandOptions(command, commandName, args, flags, projectRoot, options) {
+  const commandOpts = options.commandOpts ?? {};
+  if (!command.githubAuth || isHelpInvocation(args, flags)) return commandOpts;
+  const required = typeof command.githubAuth === 'function'
+    ? await command.githubAuth(args, flags, { commandName, projectRoot, command })
+    : command.githubAuth;
+  if (typeof required !== 'boolean') throw new TypeError('Invalid GitHub auth predicate result');
+  if (!required) return commandOpts;
+  const githubContext = await (options.prepareGithubContext || createGithubContext)(projectRoot);
+  return { ...commandOpts, githubContext };
+}
+
 async function executeCommand(commands, commandName, args, flags, projectRoot, options = {}) {
   const command = commands.get(commandName);
   if (!command) {
@@ -181,28 +211,18 @@ async function executeCommand(commands, commandName, args, flags, projectRoot, o
   }
 
   try {
-    let enforcement = null;
-    if (typeof options.enforceStage === 'function' && isStageCommand(commandName)) {
-      enforcement = await options.enforceStage({
-        commandName,
-        args,
-        flags,
-        projectRoot,
-        command,
-      });
-
-      if (enforcement?.allowed === false) {
-        return {
-          success: false,
-          error: enforcement.error ?? `Stage ${commandName} is blocked.`,
-          enforcement,
-        };
-      }
+    const enforcement = await enforceCommandStage(options, commandName, args, flags, projectRoot, command);
+    if (enforcement?.allowed === false) {
+      return {
+        success: false,
+        error: enforcement.error ?? `Stage ${commandName} is blocked.`,
+        enforcement,
+      };
     }
 
     // Lazy `.forge/` home (activation foundation): the FIRST mutating verb in a
-    // bare repo materializes the gates-disabled skeleton on demand. Read-only
-    // verbs never enter this branch, so they write nothing; an already-inited
+    // bare repo materializes the default-enabled config skeleton on demand.
+    // Read-only verbs never enter this branch, so they write nothing; an already-inited
     // repo is a no-op (never clobbered). Failure to create the home must not
     // crash the command — degrade to a warning. Opt out via `skipEnsureHome`.
     if (projectRoot && options.skipEnsureHome !== true && isMutatingVerb(commandName, command)) {
@@ -217,7 +237,17 @@ async function executeCommand(commands, commandName, args, flags, projectRoot, o
     // alias handlers read it (shouldUseKernelBroker(opts)); other handlers ignore
     // it. Backward-compatible: defaults to {} so existing 3-arg handlers are
     // unaffected.
-    const result = await command.handler(args, flags, projectRoot, options.commandOpts ?? {});
+    let commandOpts;
+    try {
+      commandOpts = await resolveCommandOptions(command, commandName, args, flags, projectRoot, options);
+    } catch {
+      // Even injected errors can contain subprocess output or credentials.
+      return {
+        success: false,
+        error: 'Unable to verify this clone\'s GitHub account. Run forge github status for recovery.',
+      };
+    }
+    const result = await command.handler(args, flags, projectRoot, commandOpts);
 
     // Record stage COMPLETION into the kernel only when the command SUCCEEDED, so
     // a stage counts as 'done' (which gates ship/review) only when its command

package/lib/commands/clean.js

@@ -118,13 +118,15 @@ function parseMainWorktree(output) {
 }
 
 /**
- * GitHub tier: collect head refs of merged PRs (one memoized call).
- * Returns an empty Set when gh is unavailable or errors — a safe no-signal.
+ * GitHub tier: collect merged PRs keyed by head branch (one memoized call).
+ * Returns an empty Map when gh is unavailable or errors — a safe no-signal.
+ * The number/title/merge-commit ride along so a merge can be CITED as evidence on
+ * the kernel issue the branch was linked to (18f1988e), not just detected.
  * @param {Function} runFile - execFileSync-compatible function
- * @returns {Map<string, string>} Map of merged PR head branch name -> head commit OID
+ * @returns {Map<string, {headRefOid: string, number: number, title: string, mergeCommitOid: string|null}>}
  */
-function getGhMergedRefs(runFile) {
-  const out = tryRun(runFile, 'gh', ['pr', 'list', '--state', 'merged', '--json', 'headRefName,headRefOid', '--limit', '200']);
+function getGhMergedPrs(runFile) {
+  const out = tryRun(runFile, 'gh', ['pr', 'list', '--state', 'merged', '--json', 'number,title,headRefName,headRefOid,mergeCommit', '--limit', '200']);
   if (!out) return new Map();
   try {
     const arr = JSON.parse(out);
@@ -133,7 +135,14 @@ function getGhMergedRefs(runFile) {
     // Record the head OID too: a reused/advanced branch name must NOT be treated as
     // merged unless its current tip still matches the OID GitHub merged.
     for (const p of arr) {
-      if (p && p.headRefName && p.headRefOid) map.set(p.headRefName, p.headRefOid);
+      if (p && p.headRefName && p.headRefOid) {
+        map.set(p.headRefName, {
+          headRefOid: p.headRefOid,
+          number: p.number,
+          title: p.title,
+          mergeCommitOid: (p.mergeCommit && p.mergeCommit.oid) || null,
+        });
+      }
     }
     return map;
   } catch (_e) { /* intentional: malformed gh output → no signal */ // NOSONAR S2486
@@ -166,30 +175,63 @@ function isSquashMerged(branch, defaultBranch, runFile) {
   return cherry.startsWith('-');
 }
 
+/**
+ * GitHub tier: a merged PR whose head OID still matches the branch tip. This is
+ * direct evidence THIS tip was merged, not a git-topology inference — a
+ * reused/advanced branch name falls through to the git-only tiers instead.
+ * @param {string} branch - Branch name
+ * @param {object} ctx - Detection context (see detectMerged)
+ * @returns {boolean} True iff a merged PR is pinned to the current branch tip
+ */
+function hasMergedPrEvidence(branch, ctx) {
+  const pr = ctx.ghMergedPrs && ctx.ghMergedPrs.get(branch);
+  if (!pr || !pr.headRefOid) return false;
+  const tip = tryRun(ctx.runFile, 'git', ['rev-parse', branch]);
+  return Boolean(tip) && tip === pr.headRefOid;
+}
+
+/**
+ * Whether a branch has contributed nothing yet — zero commits ahead of the
+ * default branch (kernel c5ab529e).
+ *
+ * A branch created but not yet committed to points AT a default-branch commit,
+ * so `git branch --merged` lists it and squash patch-equivalence finds an empty
+ * diff already present: every git-only tier reads it as merged. It is unstarted
+ * work, and `forge clean` deleted a live agent's fresh worktree and closed its
+ * issue on that reading. Only a VERIFIED count of 0 counts as unstarted; an
+ * unreadable count leaves detection exactly as it was.
+ *
+ * @param {string} branch - Branch name
+ * @param {object} ctx - Detection context (see detectMerged)
+ * @returns {boolean} True iff the branch is verified to have no commits of its own
+ */
+function isUnstartedBranch(branch, ctx) {
+  const out = tryRun(ctx.runFile, 'git', ['rev-list', '--count', `${ctx.defaultBranch}..${branch}`]);
+  return out !== '' && parseInt(out, 10) === 0;
+}
+
 /**
  * Squash-aware merged detection over three short-circuiting tiers:
- *   (a) ancestry list (`git branch --merged`), (b) merged-PR head refs (gh),
+ *   (a) merged-PR head refs (gh), (b) ancestry list (`git branch --merged`),
  *   (c) git-only squash patch-equivalence. A branch confirmed by none stays.
+ *
+ * The gh tier runs first because it is the only tier that cites real merge
+ * evidence, so it still recognizes a fast-forward/merge-commit PR whose branch
+ * ends up 0 commits ahead. The git-only tiers below cannot tell that case apart
+ * from an unstarted branch, so they are gated on the branch having commits.
+ *
  * @param {string} branch - Branch name
  * @param {object} ctx - Detection context
  * @param {string} ctx.defaultBranch - Default branch name
  * @param {string[]} ctx.mergedBranches - Ancestry-merged branch names
- * @param {Map<string, string>} ctx.ghMergedRefs - Merged PR head branch -> head OID
+ * @param {Map<string, object>} ctx.ghMergedPrs - Merged PR head branch -> PR evidence
  * @param {Function} ctx.runFile - execFileSync-compatible function
  * @returns {boolean} True iff the branch is merged (any tier)
  */
 function detectMerged(branch, ctx) {
+  if (hasMergedPrEvidence(branch, ctx)) return true;
+  if (isUnstartedBranch(branch, ctx)) return false;
   if (ctx.mergedBranches.includes(branch)) return true;
-  if (ctx.ghMergedRefs) {
-    const mergedOid = ctx.ghMergedRefs.get(branch);
-    // Only trust the gh "merged" signal when the merged PR's head OID still matches
-    // the branch tip; a reused/advanced branch name with new commits falls through
-    // to the squash patch-equivalence check (never remove on doubt).
-    if (mergedOid) {
-      const tip = tryRun(ctx.runFile, 'git', ['rev-parse', branch]);
-      if (tip && tip === mergedOid) return true;
-    }
-  }
   return isSquashMerged(branch, ctx.defaultBranch, ctx.runFile);
 }
 
@@ -270,32 +312,40 @@ async function removeWorktreeRobust(wtPath, runFile, fsApi, opts = {}) {
  * @param {Function} runFile - execFileSync-compatible function
  * @param {object} fsApi - fs-compatible module
  * @param {object} opts - Removal injection options
- * @returns {Promise<{ status: string, path: string, branch: string|null, error?: string }>}
+ * @returns {Promise<{ status: string, path: string, branch: string|null,
+ *   closeIssue: boolean, error?: string }>}
  */
 async function cleanWorktree(dir, worktreeMap, isMergedFn, worktreesDir, dryRun, runFile, fsApi, opts) {
   const wtPath = path.resolve(worktreesDir, dir);
   // Lookup by canonical key (86b04c20): porcelain emits C:/ paths, resolve emits C:\.
   const branch = worktreeMap.get(normalizeWorktreeKey(wtPath)) || null;
 
+  // `closeIssue` rides on the SAME outcome that decides removal (kernel c5ab529e).
+  // Closing is irreversible — `done` is terminal — so it may never be recomputed
+  // independently and drift away from what cleanup actually decided to do.
   if (!branch || !isMergedFn(branch)) {
-    return { status: 'active', path: wtPath, branch };
+    return { status: 'active', path: wtPath, branch, closeIssue: false };
   }
 
   // Merged, but never blow away uncommitted local edits. Checked BEFORE the dry-run
   // branch so a dry run reports the same "dirty" skip the real run would take.
+  // Held back for safety => the work is not confirmed finished => never closed.
   if (isWorktreeDirty(wtPath, runFile)) {
-    return { status: 'dirty', path: wtPath, branch };
+    return { status: 'dirty', path: wtPath, branch, closeIssue: false };
   }
 
+  // A dry run reports what it would do and mutates nothing, kernel included.
   if (dryRun) {
-    return { status: 'cleaned', path: wtPath, branch };
+    return { status: 'cleaned', path: wtPath, branch, closeIssue: false };
   }
 
   const outcome = await removeWorktreeRobust(wtPath, runFile, fsApi, opts);
   if (outcome.removed) {
-    return { status: 'cleaned', path: wtPath, branch, method: outcome.method };
+    return { status: 'cleaned', path: wtPath, branch, method: outcome.method, closeIssue: true };
   }
-  return { status: 'survivor', path: wtPath, branch, error: outcome.error };
+  // Merged with a clean tree; only the directory removal lost to an FS lock. The
+  // work IS in the default branch, so the issue is finished either way.
+  return { status: 'survivor', path: wtPath, branch, error: outcome.error, closeIssue: true };
 }
 
 /**
@@ -449,6 +499,13 @@ function renderSurvivors(survivors, lines) {
   for (const s of survivors) lines.push(`  - ${s.path}${s.error ? ` (${s.error})` : ''}`);
 }
 
+/** Append the closed-linked-issue lines. */
+function renderClosedIssues(closedIssues, lines) {
+  if (!closedIssues || closedIssues.length === 0) return;
+  lines.push(`Closed ${closedIssues.length} linked issue(s) on merge:`);
+  for (const c of closedIssues) lines.push(`  - ${c.issueId} (${c.branch})`);
+}
+
 /** Append the master-sync outcome line(s). */
 function renderMasterSync(masterSync, lines) {
   if (!masterSync || !masterSync.attempted) return;
@@ -472,10 +529,140 @@ function formatOutput(summary) {
   lines.push(`${verb} ${summary.cleaned} merged worktree(s); ${summary.active} active kept.`);
   renderDirty(summary.dirty, lines);
   renderSurvivors(summary.survivors, lines);
+  renderClosedIssues(summary.closedIssues, lines);
   renderMasterSync(summary.masterSync, lines);
   return lines.join('\n');
 }
 
+/**
+ * Strip the merged-PR record down to the evidence cited on the kernel issue.
+ * @param {Map<string, object>} ghMergedPrs
+ * @param {string} branch
+ * @returns {{number: number, title: string, mergeCommitOid: string|null}|null}
+ */
+function prEvidenceFor(ghMergedPrs, branch) {
+  const pr = ghMergedPrs && ghMergedPrs.get(branch);
+  if (!pr || !pr.number) return null;
+  return { number: pr.number, title: pr.title, mergeCommitOid: pr.mergeCommitOid };
+}
+
+/**
+ * Bridge from a merged branch to the close-on-merge primitive (kernel 18f1988e).
+ *
+ * The kernel driver + issue runner are built ONCE and only on the first merged
+ * branch, so a clean run that removes nothing pays nothing. The driver is closed
+ * by `dispose()` — and ONLY when this helper owns it, since an injected driver
+ * belongs to the caller. Leaving an owned sqlite handle open keeps the kernel file
+ * locked and fails Windows cleanup.
+ *
+ * @param {string} projectRoot
+ * @param {Function} runFile - execFileSync-compatible function (repo probe)
+ * @param {object} opts - DI (`_closeLinkedIssue`, `_kernelDriver`, `_runIssueOperation`)
+ * @returns {{ close: Function, dispose: Function }}
+ */
+function createIssueCloser(projectRoot, runFile, opts) {
+  const injected = opts._closeLinkedIssue;
+  let built = null;
+  const unavailable = { driver: null, run: null, owned: false };
+
+  async function resolveDeps() {
+    if (built) return built;
+    if (opts._kernelDriver && opts._runIssueOperation) {
+      built = { driver: opts._kernelDriver, run: opts._runIssueOperation, owned: false };
+      return built;
+    }
+    // Only reach for the kernel inside a REAL git repo. buildMigratedKernelIssueDeps
+    // CREATES the store at <git-common-dir>/forge/kernel.sqlite, so probing first is
+    // what stops a clean run pointed at a non-repo path from minting a stray kernel
+    // there. An empty result (rev-parse failed) means "not a repo".
+    if (!tryRun(runFile, 'git', ['-C', projectRoot, 'rev-parse', '--git-common-dir'])) {
+      built = unavailable;
+      return built;
+    }
+    try {
+      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+      const { runIssueOperation } = require('../forge-issues');
+      const { kernelDriver, kernelBroker } = await buildMigratedKernelIssueDeps({ projectRoot });
+      // Thread the broker through so every op reuses THIS driver instead of opening
+      // a fresh kernel handle per call.
+      built = {
+        driver: kernelDriver,
+        run: (operation, args, root) => runIssueOperation(operation, args, root, { kernelBroker }),
+        owned: true,
+      };
+    } catch (_e) { /* intentional: no kernel → close nothing, clean normally */ // NOSONAR S2486
+      built = unavailable;
+    }
+    return built;
+  }
+
+  return {
+    async close(branch, pr) {
+      try {
+        if (injected) return await injected({ branch, pr, projectRoot });
+        const { driver, run } = await resolveDeps();
+        if (!driver || !run) return { closed: false, reason: 'unavailable' };
+        const { closeLinkedIssueOnMerge } = require('../kernel/close-on-merge');
+        return await closeLinkedIssueOnMerge({ branch, projectRoot, pr, driver, runIssueOperation: run });
+      } catch (error) {
+        // Best-effort: cleanup must never fail because tracking did.
+        return { closed: false, reason: 'error', error: error && error.message };
+      }
+    },
+    dispose() {
+      if (built && built.owned && built.driver && typeof built.driver.close === 'function') {
+        try { built.driver.close(); } catch (_e) { /* best-effort */ } // NOSONAR S2486
+      }
+    },
+  };
+}
+
+async function reconcileDeadClaims(projectRoot, runFile, opts = {}) {
+  try {
+    if (typeof opts._reconcileClaims === 'function') {
+      return await opts._reconcileClaims({ projectRoot });
+    }
+
+    let driver = opts._kernelDriver;
+    let owned = false;
+    if (!driver) {
+      const commonDirOutput = tryRun(runFile, 'git', ['-C', projectRoot, 'rev-parse', '--git-common-dir']);
+      if (!commonDirOutput) {
+        return { examined: 0, released: [] };
+      }
+      const gitCommonDir = path.isAbsolute(commonDirOutput)
+        ? commonDirOutput
+        : path.resolve(projectRoot, commonDirOutput);
+      const {
+        buildMigratedKernelIssueDeps,
+        resolveKernelDatabasePath,
+      } = require('../kernel/cli-broker-factory');
+      const databasePath = resolveKernelDatabasePath({ gitCommonDir });
+      const fsApi = opts._fs || fs;
+      if (!fsApi.existsSync(databasePath)) return { examined: 0, released: [] };
+      const deps = await buildMigratedKernelIssueDeps({ projectRoot, gitCommonDir, databasePath });
+      driver = deps.kernelDriver;
+      owned = true;
+    }
+    if (!driver) return { examined: 0, released: [] };
+
+    try {
+      const { reconcileKernelClaims } = require('../kernel/claim-reconciler');
+      return await reconcileKernelClaims({
+        driver,
+        fsApi: opts._fs || fs,
+        manifestDir: opts._manifestDir,
+        isProcessAlive: opts._isProcessAlive,
+        getProcessIdentity: opts._getProcessIdentity,
+      });
+    } finally {
+      if (owned && typeof driver.close === 'function') driver.close();
+    }
+  } catch (_e) { /* best-effort: unverifiable authority never aborts clean */ // NOSONAR S2486
+    return { examined: 0, released: [] };
+  }
+}
+
 /**
  * Main handler for the clean command.
  * @param {string[]} _args - Positional arguments (unused)
@@ -492,10 +679,11 @@ function formatOutput(summary) {
  * Scan .worktrees/ and remove the merged ones (squash-aware). Returns the tallies;
  * a no-op ({0,0,[],[]}) when .worktrees/ is absent or empty. Extracted from handler
  * so the top-level orchestration stays under the complexity gate.
- * @returns {Promise<{ cleaned: number, active: number, survivors: object[], dirty: string[] }>}
+ * @param {{close: Function}|null} [closer] - Close-on-merge bridge (null in dry-run)
+ * @returns {Promise<{ cleaned: number, active: number, survivors: object[], dirty: string[], closedIssues: object[] }>}
  */
-async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts) {
-  const acc = { cleaned: 0, active: 0, survivors: [], dirty: [] };
+async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts, closer = null) {
+  const acc = { cleaned: 0, active: 0, survivors: [], dirty: [], closedIssues: [] };
   if (!fsApi.existsSync(worktreesDir)) return acc;
 
   const entries = fsApi.readdirSync(worktreesDir, { withFileTypes: true });
@@ -512,8 +700,11 @@ async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts) {
     // ancestry fast path instead of falling through to the slower squash tier.
     mergedBranches = mergedOut.split('\n').map(b => b.trim().replace(/^[*+]\s*/, '')).filter(Boolean);
   }
-  const ghMergedRefs = getGhMergedRefs(runFile);
-  const ctx = { defaultBranch, mergedBranches, ghMergedRefs, runFile };
+  const ghRunner = opts.githubContext?.bound
+    ? (_cmd, args, options) => opts.githubContext.runGh(args, options)
+    : runFile;
+  const ghMergedPrs = getGhMergedPrs(ghRunner);
+  const ctx = { defaultBranch, mergedBranches, ghMergedPrs, runFile };
   const isMergedFn = opts._isMerged || (branch => detectMerged(branch, ctx));
 
   const listOutput = tryRun(runFile, 'git', ['worktree', 'list', '--porcelain']);
@@ -525,6 +716,16 @@ async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts) {
     else if (res.status === 'survivor') acc.survivors.push(res);
     else if (res.status === 'dirty') acc.dirty.push(res.path);
     else acc.active++;
+
+    // Close only what THIS outcome authorized (18f1988e, tightened by c5ab529e):
+    // `closeIssue` is set by cleanWorktree alongside the removal decision, so a
+    // worktree held back for any reason cannot have its issue closed.
+    if (closer && res.branch && res.closeIssue) {
+      const outcome = await closer.close(res.branch, prEvidenceFor(ghMergedPrs, res.branch));
+      if (outcome && outcome.closed) {
+        acc.closedIssues.push({ branch: res.branch, issueId: outcome.issueId });
+      }
+    }
   }
 
   if (!dryRun && acc.cleaned > 0) {
@@ -541,7 +742,20 @@ async function handler(_args, flags, projectRoot, opts = {}) {
   const worktreesDir = path.resolve(projectRoot, '.worktrees');
 
   // Worktree cleanup (no-op when .worktrees/ absent); master auto-update is independent.
-  const { cleaned, active, survivors, dirty } = await cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts);
+  // A dry run detects merges but must not mutate the kernel, so it gets no closer.
+  const closer = dryRun ? null : createIssueCloser(projectRoot, runFile, opts);
+  let scan;
+  try {
+    scan = await cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts, closer);
+  } finally {
+    if (closer) closer.dispose();
+  }
+  const { cleaned, active, survivors, dirty, closedIssues } = scan;
+
+  // Claim repair is an explicit clean-lifecycle maintenance action. Run after
+  // worktree removal so a newly-missing linked checkout can be observed, while
+  // dry-run remains mutation-free. Evidence gaps and Kernel failures fail closed.
+  if (!dryRun) await reconcileDeadClaims(projectRoot, runFile, opts);
 
   // Post-merge master auto-update (default-on; skipped in dry-run).
   let masterSync = null;
@@ -550,7 +764,7 @@ async function handler(_args, flags, projectRoot, opts = {}) {
     masterSync = await doSync();
   }
 
-  return finalize({ success: true, cleaned, active, dryRun, survivors, dirty }, masterSync);
+  return finalize({ success: true, cleaned, active, dryRun, survivors, dirty, closedIssues }, masterSync);
 }
 
 /**
@@ -563,6 +777,7 @@ function finalize(summary, masterSync) {
 
 module.exports = {
   name: 'clean',
+  githubAuth: true,
   description: 'Remove worktrees for merged branches (squash-aware) and fast-forward the default branch',
   usage: 'forge clean [--dry-run] [--no-master-sync]',
   flags: {
@@ -576,8 +791,13 @@ module.exports = {
     normalizeWorktreeKey,
     parseWorktreeList,
     parseMainWorktree,
-    getGhMergedRefs,
+    getGhMergedPrs,
+    prEvidenceFor,
+    createIssueCloser,
+    reconcileDeadClaims,
     isSquashMerged,
+    hasMergedPrEvidence,
+    isUnstartedBranch,
     detectMerged,
     isWorktreeDirty,
     removeWorktreeRobust,

package/lib/commands/dev.js

@@ -460,50 +460,21 @@ function withDevAuditEvidence(featureName, phase, result, options = {}) {
 		},
 	};
 
+	// Evidence is best-effort: it records what the dev cycle did, so a log the
+	// process could not write never changes the outcome it was recording.
 	try {
-		const auditEvidence = emitImplementerAuditEvidence(auditEvent, options.auditOptions || {});
-		if (auditEvidence.record?.success === false) {
-			const auditError = auditEvidence.record.error || 'bd audit record failed';
-			return {
-				...result,
-				success: false,
-				error: result.success === false ? result.error : `Audit evidence persistence failed: ${auditError}`,
-				auditEvidence,
-			};
-		}
-
 		return {
 			...result,
-			auditEvidence,
+			auditEvidence: emitImplementerAuditEvidence(auditEvent, options.auditOptions || {}),
 		};
 	} catch (error) {
-		if (isAuditCommandUnavailableError(error)) {
-			return {
-				...result,
-				auditEvidence: {
-					success: false,
-					skipped: true,
-					error: error.message,
-				},
-			};
-		}
-
 		return {
 			...result,
-			success: false,
-			error: result.success === false ? result.error : `Audit evidence persistence failed: ${error.message}`,
-			auditEvidence: {
-				success: false,
-				error: error.message,
-			},
+			auditEvidence: { success: false, error: error.message },
 		};
 	}
 }
 
-function isAuditCommandUnavailableError(error) {
-	return error?.code === 'ENOENT' || /\bbd\b.*not found/i.test(error?.message || '');
-}
-
 /**
  * Decision gate route constants
  *

package/lib/commands/doctor.js

@@ -38,10 +38,39 @@ function buildMemoryCheck(projectRoot, env) {
 			};
 		}
 		const serverPath = graphiti.mcpServerPath;
-		const serverPathExists = fs.existsSync(serverPath);
-		const reach = serverPathExists
-			? `mcp_server present at ${serverPath}`
-			: `mcp_server path not found locally (${serverPath}); run it before agents can use graph memory`;
+		const path = require('node:path');
+		const resolvedServerPath = path.isAbsolute(serverPath)
+			? serverPath
+			: path.resolve(projectRoot, serverPath);
+		const serverPathExists = fs.existsSync(resolvedServerPath);
+		let serverPathIsDirectory = false;
+		if (serverPathExists) {
+			try {
+				serverPathIsDirectory = fs.statSync(resolvedServerPath).isDirectory();
+			} catch {
+				serverPathIsDirectory = false;
+			}
+		}
+		const entrypointPath = path.join(resolvedServerPath, 'main.py');
+		let entrypointExists = false;
+		if (serverPathIsDirectory) {
+			try {
+				entrypointExists = fs.statSync(entrypointPath).isFile();
+			} catch {
+				entrypointExists = false;
+			}
+		}
+		const serverReady = serverPathExists && serverPathIsDirectory && entrypointExists;
+		let reach;
+		if (!serverPathExists) {
+			reach = `mcp_server path not found locally (${serverPath}); run it before agents can use graph memory`;
+		} else if (!serverPathIsDirectory) {
+			reach = `mcp_server path is not a directory (${serverPath})`;
+		} else if (!entrypointExists) {
+			reach = `mcp_server entrypoint not found (${path.join(serverPath, 'main.py')})`;
+		} else {
+			reach = `mcp_server present at ${serverPath}`;
+		}
 		return {
 			// Reflect reality in the line symbol: a graphiti backend whose MCP server
 			// isn't present yet renders as `!` (warn), not a misleading `✓`. This does
@@ -49,13 +78,15 @@ function buildMemoryCheck(projectRoot, env) {
 			// filesystem-class check (see buildDoctorReport), so an uninstalled opt-in
 			// memory server warns without failing `forge doctor`.
 			id: 'memory-backend',
-			ok: serverPathExists,
+			ok: serverReady,
 			backend,
 			serverPathExists,
+			serverPathIsDirectory,
+			entrypointExists,
 			detail: `memory backend: graphiti — served to agents via the graphiti-memory MCP server; ${reach}`,
 		};
 	} catch (err) {
-		const backend = memoryRouter.resolveMemoryBackend({ projectRoot, env, warn: () => {} });
+		const backend = err.backend || memoryRouter.resolveMemoryBackend({ projectRoot, env, warn: () => {} });
 		return { id: 'memory-backend', ok: false, backend, detail: err.message };
 	}
 }