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

package/lib/capabilities/probes.js

@@ -0,0 +1,347 @@
+'use strict';
+
+const { createProbeResult } = require('./model');
+
+const PROBE_REVISION = 'forge.harness-capability-probe.v1';
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024;
+const MAX_TIMEOUT_MS = 30 * 1000;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const EXECUTABLE_IDENTITY_PATTERN = /^[0-9a-f]{64}$/;
+const SECRET_PATTERNS = Object.freeze([
+  /gh[pousr]_[a-z0-9]{20,}/i,
+  /sk-(?:live-|test-)?[a-z0-9]{16,}/i,
+  /(?:api[_ -]?key|authorization|credential|password|private[_ -]?key|secret|token)\s*[:=]\s*\S{8,}/i,
+]);
+const PRIVATE_PATH_PATTERN = /(?:[a-z]:\\Users\\[^\\\s]+|\/(?:Users|home)\/[^/\s]+\/)/i;
+
+const HARNESS_IDS = Object.freeze(['claude', 'codex', 'cursor', 'hermes']);
+const CAPABILITY_IDS = Object.freeze([
+  'native_streaming_monitor',
+  'bounded_background_tasks',
+  'wake_resume',
+  'cancellation',
+  'session_scoped_cleanup',
+  'initiating_agent_delivery',
+]);
+
+function capability(id, probeId, args, requiredTokens) {
+  if (args.length === 0 || args.at(-1) !== '--help') {
+    throw new TypeError(`Capability probe ${probeId} must use a side-effect-free help command`);
+  }
+  return Object.freeze({
+    id,
+    probeId,
+    args: Object.freeze(args),
+    requiredTokens: Object.freeze(requiredTokens),
+  });
+}
+
+function harnessSpec(command, versionPattern, capabilities) {
+  return Object.freeze({
+    command,
+    versionArgs: Object.freeze(['--version']),
+    versionPattern,
+    capabilities: Object.freeze(capabilities),
+  });
+}
+
+const HARNESS_PROBE_SPECS = Object.freeze({
+  claude: harnessSpec('claude', /^(?:claude(?:\s+code)?\s+)?v?(\d+\.\d+\.\d+(?:[-+][0-9a-z.-]+)?)$/i, [
+    capability('native_streaming_monitor', 'claude.stream-json-help.v1', ['--help'], ['--output-format', 'stream-json']),
+    capability('bounded_background_tasks', 'claude.remote-help.v1', ['--help'], ['--remote']),
+    capability('wake_resume', 'claude.resume-help.v1', ['--help'], ['--resume']),
+    capability('cancellation', 'claude.cancel-help.v1', ['--help'], ['--cancel']),
+    capability('session_scoped_cleanup', 'claude.session-cleanup-help.v1', ['--help'], ['session', 'delete']),
+    capability('initiating_agent_delivery', 'claude.stream-delivery-help.v1', ['--help'], ['--output-format', 'stream-json']),
+  ]),
+  codex: harnessSpec('codex', /^(?:codex(?:-cli)?\s+)?v?(\d+\.\d+\.\d+(?:[-+][0-9a-z.-]+)?)$/i, [
+    capability('native_streaming_monitor', 'codex.json-help.v1', ['--help'], ['--json', 'output-schema']),
+    capability('bounded_background_tasks', 'codex.cloud-help.v1', ['cloud', '--help'], ['task']),
+    capability('wake_resume', 'codex.resume-help.v1', ['resume', '--help'], ['resume']),
+    capability('cancellation', 'codex.cloud-cancel-help.v1', ['cloud', '--help'], ['cancel']),
+    capability('session_scoped_cleanup', 'codex.cloud-cleanup-help.v1', ['cloud', '--help'], ['delete']),
+    capability('initiating_agent_delivery', 'codex.delivery-help.v1', ['--help'], ['event', 'initiating', 'agent']),
+  ]),
+  cursor: harnessSpec('cursor-agent', /^(?:cursor(?:-agent)?\s+)?v?(\d+\.\d+\.\d+(?:[-+][0-9a-z.-]+)?)$/i, [
+    capability('native_streaming_monitor', 'cursor.json-help.v1', ['--help'], ['--json']),
+    capability('bounded_background_tasks', 'cursor.background-help.v1', ['--help'], ['background']),
+    capability('wake_resume', 'cursor.resume-help.v1', ['resume', '--help'], ['resume']),
+    capability('cancellation', 'cursor.cancel-help.v1', ['cancel', '--help'], ['cancel']),
+    capability('session_scoped_cleanup', 'cursor.session-cleanup-help.v1', ['sessions', '--help'], ['sessions', 'delete']),
+    capability('initiating_agent_delivery', 'cursor.follow-up-help.v1', ['--help'], ['follow-up', 'initiating', 'agent']),
+  ]),
+  hermes: harnessSpec('hermes', /^(?:hermes(?:-agent)?\s+)?v?(\d+\.\d+\.\d+(?:[-+][0-9a-z.-]+)?)$/i, [
+    capability('native_streaming_monitor', 'hermes.monitor-help.v1', ['monitor', '--help'], ['monitor', 'stream']),
+    capability('bounded_background_tasks', 'hermes.cron-help.v1', ['cron', '--help'], ['cron', 'task']),
+    capability('wake_resume', 'hermes.resume-help.v1', ['resume', '--help'], ['resume']),
+    capability('cancellation', 'hermes.cron-cancel-help.v1', ['cron', '--help'], ['pause', 'remove']),
+    capability('session_scoped_cleanup', 'hermes.session-cleanup-help.v1', ['sessions', '--help'], ['sessions', 'delete']),
+    capability('initiating_agent_delivery', 'hermes.origin-delivery-help.v1', ['cron', '--help'], ['origin', 'deliver']),
+  ]),
+});
+
+function getHarnessProbeSpec(harness) {
+  const spec = HARNESS_PROBE_SPECS[harness];
+  if (!spec) throw new TypeError(`Unsupported harness: ${harness}`);
+  return spec;
+}
+
+function assertBoundedPositiveInteger(value, name, maximum) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw new TypeError(`${name} must be an integer between 1 and ${maximum}`);
+  }
+}
+
+function isHostileOutput(output) {
+  return SECRET_PATTERNS.some((pattern) => pattern.test(output))
+    || PRIVATE_PATH_PATTERN.test(output)
+    || [...output].some((character) => {
+      const code = character.codePointAt(0);
+      return (code >= 0 && code <= 8)
+        || code === 11
+        || code === 12
+        || (code >= 14 && code <= 31)
+        || code === 127;
+    });
+}
+
+function normalizeExecution(response, maxOutputBytes) {
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    return { complete: false, reason: 'MALFORMED_RESULT' };
+  }
+  if (response.timedOut === true) return { complete: false, reason: 'PROBE_TIMEOUT' };
+  if (response.errorCode === 'ENOENT') return { complete: false, reason: 'EXECUTABLE_UNAVAILABLE' };
+  if (typeof response.stdout !== 'string' || typeof response.stderr !== 'string') {
+    return { complete: false, reason: 'MALFORMED_RESULT' };
+  }
+  const outputBytes = Buffer.byteLength(response.stdout, 'utf8') + Buffer.byteLength(response.stderr, 'utf8');
+  if (outputBytes > maxOutputBytes) return { complete: false, reason: 'OUTPUT_LIMIT' };
+  const output = `${response.stdout}\n${response.stderr}`;
+  if (isHostileOutput(output)) return { complete: false, reason: 'HOSTILE_OUTPUT' };
+  if (response.exitCode !== 0) return { complete: false, reason: 'PROBE_FAILED' };
+  return {
+    complete: true,
+    stdout: response.stdout,
+    stderr: response.stderr,
+    executableIdentity: response.executableIdentity,
+  };
+}
+
+async function executeBounded(execute, requestBase, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({ timedOut: true, stdout: '', stderr: '' });
+    }, timeoutMs);
+  });
+  const request = Object.freeze({ ...requestBase, signal: controller.signal });
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => execute(request)),
+      timeout,
+    ]);
+  } catch (_error) {
+    return { exitCode: null, stdout: '', stderr: '', errorCode: 'EXECUTION_ERROR' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function requestFor({ harness, kind, probeId, command, args, timeoutMs, maxOutputBytes }) {
+  return {
+    harness,
+    kind,
+    probeId,
+    command,
+    args: Object.freeze([...args]),
+    timeoutMs,
+    maxOutputBytes,
+    sideEffectFree: true,
+  };
+}
+
+function incompleteCapabilities(spec, reason) {
+  return spec.capabilities.map((item) => ({
+    id: item.id,
+    available: false,
+    status: 'INCOMPLETE',
+    reason,
+    probe_id: item.probeId,
+  }));
+}
+
+function buildResult({ harness, spec, observedAt, status, availability, identity, version, capabilities }) {
+  return createProbeResult({
+    probeRevision: PROBE_REVISION,
+    harnessId: harness,
+    status,
+    availability,
+    observedAt,
+    executable: { command: spec.command, identity, version },
+    capabilities,
+  });
+}
+
+function parseVersion(stdout, pattern) {
+  const normalized = stdout.trim();
+  if (normalized.includes('\n') || normalized.includes('\r')) return null;
+  const match = pattern.exec(normalized);
+  return match ? match[1] : null;
+}
+
+function capabilityFromExecution(item, execution, identity) {
+  let status = 'INCOMPLETE';
+  let reason = execution.reason;
+  let available = false;
+  if (execution.complete && execution.executableIdentity !== identity) {
+    reason = 'EXECUTABLE_IDENTITY_CHANGED';
+  } else if (execution.complete) {
+    const output = execution.stdout.toLowerCase();
+    available = item.requiredTokens.every((token) => output.includes(token.toLowerCase()));
+    status = available ? 'AVAILABLE' : 'UNAVAILABLE';
+    reason = available ? 'PROBED_SUPPORTED' : 'PROBED_UNSUPPORTED';
+  }
+  return {
+    id: item.id,
+    available,
+    status,
+    reason,
+    probe_id: item.probeId,
+  };
+}
+
+async function probeCapability(item, context, cache) {
+  const { execute, harness, spec, timeoutMs, maxOutputBytes, identity } = context;
+  const cacheKey = JSON.stringify(item.args);
+  let response = cache.get(cacheKey);
+  if (!response) {
+    response = executeBounded(execute, requestFor({
+      harness,
+      kind: 'behavior',
+      probeId: item.probeId,
+      command: spec.command,
+      args: item.args,
+      timeoutMs,
+      maxOutputBytes,
+    }), timeoutMs);
+    cache.set(cacheKey, response);
+  }
+  const execution = normalizeExecution(await response, maxOutputBytes);
+  return capabilityFromExecution(item, execution, identity);
+}
+
+async function probeCapabilities(context) {
+  const cache = new Map();
+  const capabilities = [];
+  for (const item of context.spec.capabilities) {
+    capabilities.push(await probeCapability(item, context, cache));
+  }
+  return capabilities;
+}
+
+async function probeHarness(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('probe options must be an object');
+  }
+  const { harness, execute } = options;
+  const spec = getHarnessProbeSpec(harness);
+  if (typeof execute !== 'function') throw new TypeError('execute must be a function');
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  assertBoundedPositiveInteger(timeoutMs, 'timeoutMs', MAX_TIMEOUT_MS);
+  assertBoundedPositiveInteger(maxOutputBytes, 'maxOutputBytes', MAX_OUTPUT_BYTES);
+  const observedAt = options.observedAt ?? new Date().toISOString();
+
+  const versionResponse = await executeBounded(execute, requestFor({
+    harness,
+    kind: 'version',
+    probeId: `${harness}.version.v1`,
+    command: spec.command,
+    args: spec.versionArgs,
+    timeoutMs,
+    maxOutputBytes,
+  }), timeoutMs);
+  const versionExecution = normalizeExecution(versionResponse, maxOutputBytes);
+  if (!versionExecution.complete) {
+    return buildResult({
+      harness,
+      spec,
+      observedAt,
+      status: 'INCOMPLETE',
+      availability: 'UNAVAILABLE',
+      identity: null,
+      version: null,
+      capabilities: incompleteCapabilities(spec, versionExecution.reason),
+    });
+  }
+  const identity = versionExecution.executableIdentity;
+  const version = parseVersion(versionExecution.stdout || versionExecution.stderr, spec.versionPattern);
+  if (!EXECUTABLE_IDENTITY_PATTERN.test(identity || '')) {
+    return buildResult({
+      harness,
+      spec,
+      observedAt,
+      status: 'INCOMPLETE',
+      availability: 'UNAVAILABLE',
+      identity: null,
+      version,
+      capabilities: incompleteCapabilities(spec, 'EXECUTABLE_IDENTITY_UNAVAILABLE'),
+    });
+  }
+  if (!version) {
+    return buildResult({
+      harness,
+      spec,
+      observedAt,
+      status: 'INCOMPLETE',
+      availability: 'UNAVAILABLE',
+      identity,
+      version: null,
+      capabilities: incompleteCapabilities(spec, 'MALFORMED_VERSION'),
+    });
+  }
+
+  const capabilities = await probeCapabilities({
+    execute,
+    harness,
+    spec,
+    timeoutMs,
+    maxOutputBytes,
+    identity,
+  });
+
+  return buildResult({
+    harness,
+    spec,
+    observedAt,
+    status: capabilities.some((item) => item.status === 'INCOMPLETE') ? 'INCOMPLETE' : 'PASS',
+    availability: 'AVAILABLE',
+    identity,
+    version,
+    capabilities,
+  });
+}
+
+async function probeAllHarnesses(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('probe options must be an object');
+  }
+  return Promise.all(HARNESS_IDS.map((harness) => probeHarness({ ...options, harness })));
+}
+
+module.exports = {
+  CAPABILITY_IDS,
+  DEFAULT_MAX_OUTPUT_BYTES,
+  DEFAULT_TIMEOUT_MS,
+  MAX_OUTPUT_BYTES,
+  MAX_TIMEOUT_MS,
+  HARNESS_IDS,
+  HARNESS_PROBE_SPECS,
+  PROBE_REVISION,
+  getHarnessProbeSpec,
+  probeAllHarnesses,
+  probeHarness,
+};

package/lib/codex-skills.js

@@ -135,9 +135,9 @@ function resolveCodexRepoSkillsDir(projectRoot) {
  * @param {boolean} [params.clean=false] - Remove stale canonical-managed dirs first.
  * @returns {{targetSkillsDir: string, written: string[]}}
  */
-function populateCodexRepoSkills({ sourceRoot, projectRoot, clean = false }) {
+function populateCodexRepoSkills({ sourceRoot, projectRoot, clean = false, excludeRelativePaths }) {
   const targetSkillsDir = resolveCodexRepoSkillsDir(projectRoot);
-  const { written } = populateAgentSkills({ sourceRoot, targetSkillsDir, clean });
+  const { written } = populateAgentSkills({ sourceRoot, targetSkillsDir, clean, excludeRelativePaths });
   return { targetSkillsDir, written };
 }
 

package/lib/commands/_manifest.js

@@ -39,6 +39,7 @@ const commands = [
   { file: "explain.js", module: require("./explain") },
   { file: "export.js", module: require("./export") },
   { file: "gate.js", module: require("./gate") },
+  { file: "github.js", module: require("./github") },
   { file: "hooks.js", module: require("./hooks") },
   { file: "inbox.js", module: require("./inbox") },
   { file: "init.js", module: require("./init") },

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,23 +211,13 @@ 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
@@ -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

@@ -617,6 +617,52 @@ function createIssueCloser(projectRoot, runFile, opts) {
   };
 }
 
+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)
@@ -654,7 +700,10 @@ async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts, closer
     // 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 ghMergedPrs = getGhMergedPrs(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));
 
@@ -703,6 +752,11 @@ async function handler(_args, flags, projectRoot, opts = {}) {
   }
   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;
   if (masterSyncEnabled && !dryRun) {
@@ -723,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: {
@@ -739,6 +794,7 @@ module.exports = {
     getGhMergedPrs,
     prEvidenceFor,
     createIssueCloser,
+    reconcileDeadClaims,
     isSquashMerged,
     hasMergedPrEvidence,
     isUnstartedBranch,

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 };
 	}
 }