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

package/lib/kernel/claim-reconciler.js

@@ -0,0 +1,238 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+	DEFAULT_MANIFEST_DIR,
+	defaultGetProcessIdentity,
+	isValidManifest,
+	readProcessManifest,
+} = require('../../scripts/process-tree');
+
+function nonEmptyString(value) {
+	return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+
+function positivePid(value) {
+	return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function verifiedManifestForClaim(claim, manifest) {
+	const sessionId = nonEmptyString(claim?.session_id);
+	const worktreeId = nonEmptyString(claim?.worktree_id);
+	if (!nonEmptyString(claim?.id) || !nonEmptyString(claim?.issue_id) || !sessionId || !worktreeId) return null;
+	if (claim.state != null && claim.state !== 'active') return null;
+	if (!isValidManifest(manifest) || manifest.token !== sessionId) return null;
+
+	const owner = manifest.owner;
+	const pid = positivePid(owner?.pid);
+	const identity = nonEmptyString(owner?.identity);
+	const startedAt = nonEmptyString(owner?.startedAt);
+	if (!pid || !identity || identity.startsWith('unverified:') || !startedAt || !Array.isArray(manifest.children)) {
+		return null;
+	}
+
+	return { sessionId, worktreeId, pid, identity, startedAt };
+}
+
+function defaultIsProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error?.code === 'EPERM';
+	}
+}
+
+function createManifestReader(options = {}) {
+	const fsApi = options.fsApi || fs;
+	const processApi = options.processApi || process;
+	const manifestDir = options.manifestDir || DEFAULT_MANIFEST_DIR;
+	return async (sessionId) => {
+		let entries;
+		try {
+			entries = fsApi.readdirSync(manifestDir, { withFileTypes: true });
+		} catch {
+			return null;
+		}
+		const matches = [];
+		for (const entry of entries) {
+			const name = typeof entry === 'string' ? entry : entry?.name;
+			if (!name || !name.endsWith('.json')) continue;
+			if (typeof entry !== 'string' && entry.isFile && !entry.isFile()) continue;
+			const manifest = readProcessManifest(path.join(manifestDir, name), fsApi, processApi);
+			if (manifest?.token === sessionId) matches.push(manifest);
+		}
+		return matches.length === 1 ? matches[0] : null;
+	};
+}
+
+function createWorktreeInspector(driver, fsApi = fs) {
+	return async (worktreeId, claim) => {
+		let rows;
+		try {
+			rows = await driver.listWorktrees({});
+		} catch {
+			return null;
+		}
+		const linked = (Array.isArray(rows) ? rows : []).filter(row => row
+			&& row.issue_id === claim.issue_id
+			&& row.state === 'active'
+			&& (row.id === worktreeId || path.basename(row.path || '') === worktreeId));
+		if (linked.length !== 1 || !nonEmptyString(linked[0].path)) return null;
+		try {
+			if (typeof fsApi.lstatSync === 'function') {
+				fsApi.lstatSync(linked[0].path);
+				return { exists: true, row: linked[0] };
+			}
+			return { exists: fsApi.existsSync(linked[0].path), row: linked[0] };
+		} catch (error) {
+			if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+				return { exists: false, row: linked[0] };
+			}
+			return null;
+		}
+	};
+}
+
+function createMissingPathVerifier(fsApi = fs) {
+	return (worktreePath) => {
+		try {
+			if (typeof fsApi.lstatSync === 'function') fsApi.lstatSync(worktreePath);
+			else if (fsApi.existsSync(worktreePath)) return false;
+			else return true;
+			return false;
+		} catch (error) {
+			return error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
+		}
+	};
+}
+
+async function reconcileClaims(options = {}) {
+	const claims = Array.isArray(options.claims) ? options.claims : [];
+	const readManifest = options.readManifest;
+	const worktreeExists = options.worktreeExists;
+	const isProcessAlive = options.isProcessAlive;
+	const getProcessIdentity = options.getProcessIdentity;
+	const releaseClaim = options.releaseClaim;
+	const released = [];
+	const attempted = new Set();
+
+	if (![readManifest, worktreeExists, isProcessAlive, getProcessIdentity, releaseClaim]
+		.every(dependency => typeof dependency === 'function')) {
+		return { examined: claims.length, released };
+	}
+
+	for (const claim of claims) {
+		if (!nonEmptyString(claim?.id) || attempted.has(claim.id)) continue;
+
+		let manifest;
+		try {
+			manifest = await readManifest(claim.session_id, claim);
+		} catch {
+			continue;
+		}
+		const verified = verifiedManifestForClaim(claim, manifest);
+		if (!verified) continue;
+
+		let worktreeInspection;
+		try {
+			worktreeInspection = await worktreeExists(verified.worktreeId, claim);
+		} catch {
+			continue;
+		}
+		const worktreeMissing = worktreeInspection === false
+			|| worktreeInspection?.exists === false;
+		if (!worktreeMissing) continue;
+
+		let ownerAlive;
+		try {
+			ownerAlive = await isProcessAlive(verified.pid);
+		} catch {
+			continue;
+		}
+		if (ownerAlive !== false) {
+			if (ownerAlive !== true) continue;
+			let currentIdentity;
+			try {
+				currentIdentity = await getProcessIdentity(verified.pid);
+			} catch {
+				continue;
+			}
+			// A matching owner is live. A mismatch is PID reuse or otherwise
+			// unverifiable; neither authorizes releasing its claim.
+			if (currentIdentity !== verified.identity) continue;
+			continue;
+		}
+
+		attempted.add(claim.id);
+		const evidence = Object.freeze({
+			claim_id: claim.id,
+			issue_id: claim.issue_id,
+			session_id: verified.sessionId,
+			worktree_id: verified.worktreeId,
+			manifest_version: manifest.version,
+			manifest_token: manifest.token,
+			owner_pid: verified.pid,
+			owner_identity: verified.identity,
+			owner_started_at: verified.startedAt,
+			run_state: 'dead',
+			worktree_state: 'missing',
+		});
+
+		try {
+			if (await releaseClaim(claim, evidence, worktreeInspection)) released.push(claim.id);
+		} catch {
+			// A failed release is not evidence that authority changed.
+		}
+	}
+
+	return { examined: claims.length, released };
+}
+
+async function reconcileKernelClaims(options = {}) {
+	const driver = options.driver;
+	if (!driver || typeof driver.listWorktrees !== 'function'
+		|| typeof driver.releaseExactClaimIfWorktreeMissing !== 'function') {
+		return { examined: 0, released: [] };
+	}
+
+	let claims;
+	try {
+		if (typeof driver.listActiveClaims === 'function') {
+			claims = await driver.listActiveClaims(options.context || {}, options.config || {});
+		} else {
+			const response = await driver.issueOperation('claims', [], options.context || {}, options.config || {});
+			claims = response?.data?.claims;
+		}
+	} catch {
+		return { examined: 0, released: [] };
+	}
+
+	return reconcileClaims({
+		claims,
+		readManifest: options.readManifest || createManifestReader(options),
+		worktreeExists: options.worktreeExists || createWorktreeInspector(driver, options.fsApi || fs),
+		isProcessAlive: options.isProcessAlive || defaultIsProcessAlive,
+		getProcessIdentity: options.getProcessIdentity || (pid => defaultGetProcessIdentity(pid, options)),
+		releaseClaim: async (claim, evidence, inspection) => {
+			const released = await driver.releaseExactClaimIfWorktreeMissing(
+				claim,
+				inspection?.row,
+				createMissingPathVerifier(options.fsApi || fs),
+				evidence,
+				options.config || {},
+			);
+			if (released && typeof options.onEvidence === 'function') options.onEvidence(evidence);
+			return released;
+		},
+	});
+}
+
+module.exports = {
+	createManifestReader,
+	createWorktreeInspector,
+	reconcileClaims,
+	reconcileKernelClaims,
+	verifiedManifestForClaim,
+};

package/lib/kernel/cli-broker-factory.js

@@ -113,7 +113,18 @@ async function buildMigratedKernelIssueDeps(options = {}) {
     databasePath: deps.kernelDatabasePath,
     driver: deps.kernelDriver,
   });
-  await ensureKernelMigrated(broker);
+  const close = async () => {
+    if (typeof deps.kernelDriver.close === 'function') {
+      await deps.kernelDriver.close();
+    }
+  };
+  broker.close = close;
+  try {
+    await ensureKernelMigrated(broker);
+  } catch (error) {
+    try { await close(); } catch { /* preserve the migration failure */ }
+    throw error;
+  }
   return {
     useKernelBroker: true,
     kernelBroker: broker,

package/lib/kernel/close-on-merge.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * Close-on-merge linkage (kernel issue 18f1988e).
+ *
+ * The branch->issue linkage backbone shipped (kernel_worktrees rows written by
+ * `forge worktree create` and the auto-file rail), but nothing ever consumed it:
+ * a merged PR closed no kernel issue, so finished work stayed open forever. A
+ * hygiene sweep on 2026-07-25 closed 104 such issues, 61 of them auto-stubs
+ * minted on branch push whose merged PR closed nothing.
+ *
+ * This module is the consumer. Given a branch whose PR is known to be MERGED, it
+ * comments the merge evidence onto the linked kernel issue and closes it.
+ *
+ * Safety properties (each covered by test/kernel/close-on-merge.test.js):
+ *   - LINKED ONLY. The issue comes from the kernel_worktrees linkage registry via
+ *     resolveActiveIssueId — the same authoritative resolver `forge ship` stage
+ *     state uses. An issue is never guessed from the branch/PR title, so a merge
+ *     can only ever close the issue the branch was actually bound to.
+ *   - IDEMPOTENT. The issue's status is read back first; a terminal issue
+ *     (`done` / `cancelled` — the kernel's real terminal vocabulary) is a pure
+ *     no-op that writes neither a comment nor a close. Running clean twice
+ *     closes once.
+ *   - NEVER CLOSES BLIND. An unreadable status is a skip, not an assumption.
+ *   - BEST EFFORT. Every failure path — no kernel, a throwing driver, a rejected
+ *     mutation — resolves to `{ closed: false, reason }`. Nothing throws, so
+ *     `forge clean` still removes worktrees when tracking is broken.
+ *
+ * Writes go through the supported `runIssueOperation` seam (lib/forge-issues.js),
+ * the same path `forge inbox ack` uses, so kernel events/provenance are recorded
+ * exactly as a hand-run `forge comment` / `forge close` would be.
+ *
+ * @module kernel/close-on-merge
+ */
+
+const { resolveActiveIssueId } = require('../workflow/enforce-stage');
+const { isWorkableStatus } = require('./readiness-model');
+
+/**
+ * Render the merge-evidence comment posted onto the issue before it is closed.
+ * Stays honest when the PR could not be resolved: `forge clean` also detects a
+ * merge by git patch-equivalence, with no GitHub data to cite.
+ *
+ * @param {object} params
+ * @param {string} params.branch - Merged branch name
+ * @param {{number: number, title?: string, mergeCommitOid?: string}|null} [params.pr]
+ * @returns {string} Comment body
+ */
+function buildMergeEvidence({ branch, pr }) {
+  const lines = ['Closed automatically: the branch backing this issue was merged.', '', `branch: ${branch}`];
+  if (pr && pr.number) {
+    lines.push(`pull request: #${pr.number}${pr.title ? ` — ${pr.title}` : ''}`);
+    if (pr.mergeCommitOid) lines.push(`merge commit: ${pr.mergeCommitOid}`);
+  } else {
+    lines.push('pull request: no pull request resolved (merge detected from git history)');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render the `--reason` recorded on the close event.
+ *
+ * @param {object} params
+ * @param {string} params.branch
+ * @param {{number: number}|null} [params.pr]
+ * @returns {string}
+ */
+function buildCloseReason({ branch, pr }) {
+  return pr && pr.number ? `merged in PR #${pr.number}` : `branch ${branch} merged`;
+}
+
+/**
+ * Read an issue's current status through the supported read path.
+ *
+ * @param {Function} runIssueOperation
+ * @param {string} issueId
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>} the status, or null when it could not be read.
+ */
+async function readIssueStatus(runIssueOperation, issueId, projectRoot) {
+  const result = await runIssueOperation('show', [issueId, '--json'], projectRoot);
+  if (!result || result.ok !== true || !result.data) return null;
+  const status = result.data.status;
+  return typeof status === 'string' && status ? status : null;
+}
+
+/** @returns {boolean} whether a mutation envelope reports success. */
+function mutationSucceeded(result) {
+  return Boolean(result && (result.ok === true || result.success === true));
+}
+
+/**
+ * Comment the merge evidence onto the linked kernel issue and close it.
+ * See the module doc for the full contract. NEVER throws.
+ *
+ * @param {object} options
+ * @param {string} options.branch - The merged branch.
+ * @param {string} [options.projectRoot] - Repo root threaded to the issue runner.
+ * @param {{number: number, title?: string, mergeCommitOid?: string}|null} [options.pr]
+ *   Merge evidence from GitHub, when available.
+ * @param {object} options.driver - Kernel driver exposing the worktree linkage registry.
+ * @param {Function} options.runIssueOperation - (operation, args, projectRoot) => envelope.
+ * @param {Function} [options.resolveIssueId] - Override the branch->issue resolver (tests).
+ * @returns {Promise<{closed: boolean, issueId?: string|null, reason?: string,
+ *   commented?: boolean, status?: string, error?: string}>}
+ */
+async function closeLinkedIssueOnMerge(options = {}) {
+  const { branch, projectRoot, pr = null, driver, runIssueOperation } = options;
+  try {
+    if (!branch || typeof branch !== 'string') return { closed: false, reason: 'no-branch' };
+    if (!driver || typeof runIssueOperation !== 'function') {
+      return { closed: false, reason: 'unavailable' };
+    }
+
+    // Linked only — never a title/heuristic match.
+    const resolveIssueId = options.resolveIssueId || resolveActiveIssueId;
+    const issueId = await resolveIssueId(driver, branch);
+    if (!issueId) return { closed: false, reason: 'not-linked' };
+
+    // Idempotency + never-close-blind: read the current status first.
+    const status = await readIssueStatus(runIssueOperation, issueId, projectRoot);
+    if (!status) return { closed: false, reason: 'read-failed', issueId };
+    if (!isWorkableStatus(status)) {
+      return { closed: false, reason: 'already-closed', issueId, status };
+    }
+
+    // Evidence first, so it survives even if the close is rejected.
+    const commentResult = await runIssueOperation(
+      'comment',
+      [issueId, buildMergeEvidence({ branch, pr })],
+      projectRoot,
+    );
+    const commented = mutationSucceeded(commentResult);
+
+    const closeResult = await runIssueOperation(
+      'close',
+      [issueId, '--reason', buildCloseReason({ branch, pr })],
+      projectRoot,
+    );
+    if (!mutationSucceeded(closeResult)) {
+      return { closed: false, reason: 'close-failed', issueId, commented };
+    }
+    return { closed: true, issueId, commented };
+  } catch (error) {
+    // Best-effort: cleanup must never break on tracking.
+    return { closed: false, reason: 'error', error: error && error.message };
+  }
+}
+
+module.exports = {
+  closeLinkedIssueOnMerge,
+  buildMergeEvidence,
+  buildCloseReason,
+};

package/lib/kernel/fs-class.js

@@ -284,7 +284,7 @@ function driveLetterOf(absPath) {
 
 // Bounded exec options for the Windows drive probes. The timeout is the BLOCKER-1
 // fix: execFileSync's try/catch only catches throws, never hangs, so an
-// unresponsive `net use` / PowerShell (e.g. a wedged network redirector) would
+// an unresponsive `net use` probe (e.g. a wedged network redirector) would
 // hang the whole process indefinitely. With a timeout, a hang becomes a throw
 // that the gatherSignals catch turns into driveType='unknown' → warn (never
 // refuse), symmetric with the G1 fail-safe. killSignal forces the child dead.
@@ -310,18 +310,21 @@ function parseNetUseDriveType(stdout, driveLetter) {
 	return null;
 }
 
-// PURE (M5): a non-empty PowerShell DisplayRoot means the PSDrive is backed by a
-// network/remote root. Returns 'network' when non-blank, else null.
-function parseDisplayRoot(stdout) {
-	return String(stdout || '').trim() ? 'network' : null;
-}
-
 // Windows: detect whether a drive letter is a mapped network drive.
-// FAIL-SAFE FALLBACK (locked decision G1, option a): try `net use`, then a
-// PowerShell DisplayRoot fallback; on ANY probe failure (including a timeout-
-// induced throw, per BLOCKER 1) the caller treats the result as 'unknown'.
-// Probes use arg ARRAYS (no shell) so they remain injection-free.
+// The conventional local C: drive is fixed without a subprocess. `net use` is
+// authoritative for other mapped drive letters, while a no-match remains
+// unknown because it does not prove that an SMB/cloud redirector is absent. The unknown
+// result is fail-open (warn), while UNC and cloud path signals still refuse.
+// Do not launch a second shell process for every kernel child. Under a heavily
+// sharded suite those redundant fallback probes contend for host resources and
+// can leave a shard blocked indefinitely.
+// A probe failure still propagates to the gatherer, which maps it to the
+// fail-safe `unknown`/warn classification.
+// The probe uses an arg ARRAY (no shell) so it remains injection-free.
 function defaultProbeDriveType(driveLetter, deps = {}) {
+	const normalizedDriveLetter = String(driveLetter || '').trim().toUpperCase();
+	if (normalizedDriveLetter === 'C:') return 'fixed';
+
 	const exec = deps.execFileSync || execFileSync;
 
 	// Primary: `net use` lists mapped drive letters (and their remote paths).
@@ -330,17 +333,9 @@ function defaultProbeDriveType(driveLetter, deps = {}) {
 		return 'network';
 	}
 
-	// Secondary: PowerShell DisplayRoot — non-empty for network-backed PSDrives.
-	const psLetter = String(driveLetter).replace(':', '');
-	const psCmd =
-		`(Get-PSDrive -Name '${psLetter}' -ErrorAction SilentlyContinue).DisplayRoot`;
-	const psOut = exec('powershell', ['-NoProfile', '-Command', psCmd], WIN_PROBE_EXEC_OPTIONS);
-	if (parseDisplayRoot(psOut) === 'network') {
-		return 'network';
-	}
-
-	// Letter exists, no network backing detected → fixed.
-	return 'fixed';
+	// `net use` completed successfully without listing this non-system letter.
+	// A no-match is not evidence that an SMB/cloud redirector is absent.
+	return 'unknown';
 }
 
 // Linux: read /proc/mounts, return fs type of the longest mountpoint prefixing absPath.
@@ -443,27 +438,49 @@ function isUnsafeFsOverrideActive(env = {}) {
 	return value === '1' || value === 'true';
 }
 
+// The gate runs on every broker instance, and one command builds several
+// (`forge status` and `forge prime` each build four), so an un-memoized advisory
+// printed four times per command. The advisory describes the process's database
+// path, not the broker, so it is emitted once per (tier, class, path) per
+// process. Keyed rather than a single flag so a second path — or a path that
+// reclassifies — is still reported. Warnings only: `refuse` still throws on
+// every call, so deduping can never turn a refusal into a pass.
+const warnedFilesystemKeys = new Set();
+
+function resetFilesystemWarningMemo() {
+	warnedFilesystemKeys.clear();
+}
+
 function assertFilesystemSafeForKernel(dbPath, deps = {}) {
 	const env = deps.env || process.env;
+	// console.warn writes to stderr, which is the contract here: `--json`
+	// consumers parse stdout, so an advisory on stdout would corrupt the envelope.
 	const warn = deps.warn || (msg => console.warn(msg));
 	const classify = deps.classifyFilesystem || classifyFilesystem;
 
 	const classification = classify(dbPath, deps);
 	const remediation = REMEDIATION[classification.remediationKey] || REMEDIATION.unknown;
 
+	const warnOnce = message => {
+		const key = `${classification.riskTier}|${classification.class}|${dbPath}`;
+		if (warnedFilesystemKeys.has(key)) return;
+		warnedFilesystemKeys.add(key);
+		warn(message);
+	};
+
 	if (classification.riskTier === 'safe') {
 		return classification;
 	}
 
 	if (classification.riskTier === 'warn') {
-		warn(`forge kernel filesystem warning (${classification.class}):\n${remediation}`);
+		warnOnce(`forge kernel filesystem warning (${classification.class}):\n${remediation}`);
 		return classification;
 	}
 
 	// refuse
 	const overrideActive = isUnsafeFsOverrideActive(env);
 	if (overrideActive) {
-		warn(
+		warnOnce(
 			`forge kernel filesystem REFUSE downgraded by FORGE_KERNEL_ALLOW_UNSAFE_FS ` +
 			`(${classification.class}) — override active:\n${remediation}`,
 		);
@@ -487,9 +504,9 @@ module.exports = {
 	gatherSignals,
 	classifyFilesystem,
 	assertFilesystemSafeForKernel,
+	resetFilesystemWarningMemo,
 	isUnsafeFsOverrideActive,
 	defaultProbeDriveType,
 	parseNetUseDriveType,
-	parseDisplayRoot,
 	REMEDIATION,
 };

package/lib/kernel/lease-enforcer.js

@@ -78,12 +78,17 @@ function isValidExpiresAt(value) {
 	return new Date(timestamp).toISOString() === value;
 }
 
-// A lease with no expires_at never expires. Timestamps are validated UTC ISO-8601
-// with a trailing 'Z' (see isValidExpiresAt), so lexicographic comparison equals
-// chronological comparison.
+// A lease with no expires_at never expires. Normalize both instants before comparing:
+// callers supply `now`, so it may be non-canonical or unusable even though stored
+// expires_at is canonical. Without a usable clock expiry is not proven; conservatively
+// keep the lease live rather than allowing a false reclaim or ready projection.
 function isLeaseExpired(claim, now) {
 	if (!claim?.expires_at) return false;
-	return claim.expires_at <= now;
+	if (typeof now !== 'string') return false;
+	const expiresAt = Date.parse(claim.expires_at);
+	const clock = Date.parse(now);
+	if (!Number.isFinite(expiresAt) || !Number.isFinite(clock)) return false;
+	return expiresAt <= clock;
 }
 
 function buildClaimRow(event, now) {