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

package/lib/commands/plan.js

@@ -13,6 +13,10 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { resolveIssueBackend } = require('../issue-backend');
 const { runIssueOperation } = require('../forge-issues');
+const {
+	findPlanWorkFolder,
+	reconcilePlanAuthority,
+} = require('../workflow/plan-authority');
 
 // Constants for security
 // Note: cwd is resolved at call-time via getExecOptions() to avoid stale require-time snapshots
@@ -483,7 +487,7 @@ async function registerBranchIssueLinkage(options, branch, issueId) {
 				branch,
 				actor: null,
 				issue_id: issueId,
-				work_folder: null,
+				work_folder: options.workFolder || null,
 				registered_at: new Date().toISOString(),
 				state: 'active',
 			});
@@ -976,11 +980,38 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 			};
 		}
 
+		const workFolder = options.workFolder || findPlanWorkFolder(options.projectRoot || process.cwd(), featureSlug);
+
 		// F1: persist the branch->issue linkage so a plan-created branch resolves
 		// to its issue for kernel-authoritative stage state (dev/validate/ship).
 		// Kernel-only, best-effort.
 		if (issueBackend === 'kernel') {
-			await registerBranchIssueLinkage({ ...options, issueBackend }, branch.branchName, issue.issueId);
+			await registerBranchIssueLinkage({ ...options, issueBackend, workFolder }, branch.branchName, issue.issueId);
+			await withPlanDriver(options, driver => {
+				if (!driver || typeof driver.loadPlanSnapshot !== 'function') return null;
+				let existing;
+				try {
+					existing = driver.loadPlanSnapshot({ issue_id: issue.issueId }, {});
+				} catch (error) {
+					// Injectable issue runners used by embedding callers may not persist into
+					// this driver's store. With no repository artifacts there is nothing to
+					// reconcile; preserve that legacy embedding contract.
+					if (/^Issue .* not found in the kernel$/i.test(error.message)) {
+						if (!workFolder) return null;
+						throw new Error(`Issue ${issue.issueId} is not available for plan authority persistence`);
+					}
+					throw error;
+				}
+				if (!existing && !workFolder) return null;
+				return reconcilePlanAuthority({
+					driver,
+					issueId: issue.issueId,
+					projectRoot: options.projectRoot || process.cwd(),
+					workFolder,
+					mode: 'plan',
+					repairCommand: `forge plan ${JSON.stringify(featureName)} --issue ${issue.issueId}`,
+				});
+			});
 		}
 
 		// Build result summary

package/lib/commands/pr.js

@@ -33,7 +33,7 @@ const SUBCOMMANDS = {
   },
   merge: {
     module: merge,
-    summary: 'Opt-in conditional auto-merge, OFF by default (= forge merge --auto <pr>)',
+    summary: 'Opt-in guarded merge, OFF by default (= forge merge --auto <pr> --expect-head <sha> --issue <id>)',
   },
 };
 
@@ -81,6 +81,8 @@ async function handler(args, flags, projectRoot, opts) {
 
 module.exports = {
   name: 'pr',
+  githubAuth: (args = []) => ['ship', 'merge', 'shepherd']
+    .includes(stripGlobalFlags(args).find(arg => !arg.startsWith('-'))),
   description:
     'Unified pull-request surface: forge pr ship|preflight|shepherd|merge (wraps ship/preflight/shepherd/merge)',
   usage,

package/lib/commands/preflight.js

@@ -88,11 +88,19 @@ function resolveBaseRef(exec) {
  * @param {{ runAll?: boolean }} [opts]
  * @returns {{ resolved: boolean, changedFiles: string[], reason?: string, baseRef?: string }}
  */
-function resolveChangeSet(exec = execFileSync, { runAll = false } = {}) {
+function resolveChangeSet(exec = execFileSync, { runAll = false, baseRef: explicitBaseRef = null } = {}) {
   if (runAll) {
     return { resolved: true, changedFiles: [], reason: 'whole-tree scope (--all)' };
   }
-  const baseRef = resolveBaseRef(exec);
+  const baseRef = explicitBaseRef || resolveBaseRef(exec);
+  if (explicitBaseRef && !gitVerifyRef(exec, explicitBaseRef)) {
+    return {
+      resolved: false,
+      baseRef: explicitBaseRef,
+      changedFiles: [],
+      reason: `explicit base branch ${explicitBaseRef} is unavailable`,
+    };
+  }
   if (!baseRef) {
     return {
       resolved: false,
@@ -103,7 +111,16 @@ function resolveChangeSet(exec = execFileSync, { runAll = false } = {}) {
   // Diff against the SAME base we just resolved. getChangedFiles() re-resolves
   // its own diff ref (and can fall back to a different default branch), so use
   // baseRef directly to keep the file list consistent with the resolved base.
-  return { resolved: true, baseRef, changedFiles: changedFilesForBase(exec, baseRef) };
+  const changedFiles = changedFilesForBase(exec, baseRef);
+  if (changedFiles == null) {
+    return {
+      resolved: false,
+      baseRef,
+      changedFiles: [],
+      reason: `git diff failed or timed out for ${baseRef}`,
+    };
+  }
+  return { resolved: true, baseRef, changedFiles };
 }
 
 /** Files changed between the merge-base of HEAD and `baseRef` and HEAD. */
@@ -111,7 +128,7 @@ function changedFilesForBase(exec, baseRef) {
   const mergeBase = gitTryOut(exec, ['merge-base', 'HEAD', baseRef]);
   const range = mergeBase ? `${mergeBase}...HEAD` : `${baseRef}...HEAD`;
   const out = gitTryOut(exec, ['diff', '--name-only', range]);
-  if (out == null) return [];
+  if (out == null) return null;
   return out.split(/\r?\n/).filter(Boolean);
 }
 

package/lib/commands/prime.js

@@ -6,15 +6,28 @@ const {
   runOrientationCommand,
 } = require('../orientation');
 
+const DEPRECATION_NOTICE =
+  'forge prime is deprecated — run `forge status -v` for the same briefing.\n';
+
+// The single briefing renderer. `forge status -v` calls this so the full
+// session-entry briefing has exactly one implementation.
+// Async: the briefing leads with LIVE state (stage / claims / ready / gates / one
+// adoption nudge), which needs a best-effort (non-throwing) kernel read before the
+// synchronous build assembles it into the bounded orientation.
+async function renderBriefing(args, projectRoot) {
+  const liveState = await collectPrimeLiveState(projectRoot);
+  return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+}
+
 module.exports = {
   name: 'prime',
-  description: 'Emit session-entry bounded orientation for agents',
-  usage: 'Usage: forge prime [--budget N] [--json]',
-  // Async: prime leads with LIVE state (stage / claims / ready / gates / one adoption nudge),
-  // which needs a best-effort (non-throwing) kernel read before the synchronous build assembles
-  // it into the bounded orientation. All existing prime output/flags are unchanged.
-  handler: async (args, _flags, projectRoot) => {
-    const liveState = await collectPrimeLiveState(projectRoot);
-    return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+  description: 'Deprecated alias for `forge status -v`: session-entry bounded orientation',
+  usage: 'Usage: forge prime [--budget N] [--json]  (deprecated — use `forge status -v`)',
+  // Session-start hooks in consumer repos call this and consume stdout as context,
+  // so the notice goes to stderr and stdout stays byte-identical to `status -v`.
+  handler: async (args, _flags, projectRoot, options = {}) => {
+    (options.stderr || process.stderr).write(DEPRECATION_NOTICE);
+    return renderBriefing(args, projectRoot);
   },
+  renderBriefing,
 };

package/lib/commands/push.js

@@ -4,8 +4,8 @@ const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
-const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
-const { autoShepherdRailEnabled } = require('./ship');
+const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE, resolveFullSuiteTimeoutMs } = require('../../scripts/test');
+const { fireAndForget } = require('../pr-monitor/reconcile-executor');
 
 const isWindows = process.platform === 'win32';
 
@@ -113,54 +113,49 @@ async function autoFileBackingIssueForPush(projectRoot, execFn, deps = {}) {
 }
 
 /**
- * Resolve the OPEN PR number for the current branch via `gh pr view`. Returns
- * null when there is no PR, gh is unavailable, or anything errors (fail-open).
- * NEVER throws.
+ * Best-effort wake of the repository-wide singleton after a successful push.
+ * The shared trigger owns all containment and gate checks and never selects a
+ * per-PR watcher here.
  *
- * @param {function} execFn - execFileSync or mock
- * @returns {number|null}
+ * @param {object} params
+ * @returns {{ armed: boolean, reason?: string }}
  */
-function resolveOpenPrNumber(execFn) {
+function maybeTriggerShepherdAfterPush({
+	projectRoot,
+	fireAndForget: trigger = fireAndForget,
+}) {
 	try {
-		const out = execFn('gh', ['pr', 'view', '--json', 'number', '-q', '.number'], {
-			encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
-		});
-		const n = Number.parseInt(String(out).trim(), 10);
-		return Number.isInteger(n) && n > 0 ? n : null;
-	} catch (_err) { /* intentional: no open PR / gh missing → arm nothing */ // NOSONAR S2486
-		return null;
+		trigger({ projectRoot });
+		return { armed: true };
+	} catch {
+		return { armed: false, reason: 'shepherd-launch-failed' };
 	}
 }
 
 /**
- * Best-effort, NON-BLOCKING arm of the constant PR watcher after a successful
- * push, when an OPEN PR exists for the current branch. This closes the gap where
- * PRs not born from `forge ship` (gh pr create, the GitHub UI, an earlier push)
- * never got a watcher. Gated by the default-ON `rail.auto_shepherd`, idempotent
- * via the watch loop's own PID/journal lock, and reusing the same
- * `startPrWatcherDetached` as ship. MUST NEVER throw into or fail the push: a
- * disabled rail, no PR, a gh error, or a spawn error all degrade to
- * `{ armed: false }`.
+ * Build the environment for the spawned `git push`, declaring the push lane.
  *
- * @param {object} params
- * @returns {{ armed: boolean, reason?: string, prNumber?: number }}
+ * `--quick` skips the test step push.js controls, but the `git push` it spawns
+ * still fires the lefthook pre-push hook, whose tests job runs scripts/test.js —
+ * so --quick was quick only up to the push. This declares the lane to that hook
+ * so the quick lane is lint-only end to end.
+ *
+ * The declaration is set on the child env only, and is explicitly REMOVED for a
+ * full push so an inherited value from an outer shell can never silently drop
+ * the tests from a `forge push`.
+ *
+ * @param {boolean} quickMode - Whether this is a --quick push
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env] - Environment to derive from
+ * @returns {NodeJS.ProcessEnv} Environment for the git push child process
  */
-function maybeArmWatcherAfterPush({
-	projectRoot,
-	execFn,
-	startWatcher = startPrWatcherDetached,
-	railEnabled = autoShepherdRailEnabled,
-	prLookup = resolveOpenPrNumber,
-}) {
-	try {
-		if (!railEnabled(projectRoot)) return { armed: false, reason: 'rail.auto_shepherd disabled' };
-		const prNumber = prLookup(execFn);
-		if (!prNumber) return { armed: false, reason: 'no-open-pr' };
-		const res = startWatcher({ prNumber, cwd: projectRoot });
-		return { armed: !!(res && res.started), reason: res && res.reason, prNumber };
-	} catch (err) {
-		return { armed: false, reason: err.message };
+function buildPushEnv(quickMode, baseEnv = process.env) {
+	const env = { ...baseEnv };
+	if (quickMode) {
+		env[QUICK_LANE_ENV_VAR] = QUICK_LANE_VALUE;
+	} else {
+		delete env[QUICK_LANE_ENV_VAR];
 	}
+	return env;
 }
 
 /**
@@ -196,6 +191,94 @@ function runLint(spawnFn, pkgManager, projectRoot) {
 	return lintResult.status === 0;
 }
 
+/**
+ * Reports the kill signal a timed-out test run is terminated with. Shared by
+ * the spawn options and the timeout detector so the two cannot drift.
+ */
+const TEST_RUN_KILL_SIGNAL = 'SIGKILL';
+
+/**
+ * Reads the terminating signal under either field name.
+ *
+ * `node:child_process.spawnSync` reports `signal`; native `Bun.spawnSync`
+ * reports `signalCode`. Read both rather than assuming one.
+ *
+ * @param {Object} testResult - spawnSync result object
+ * @returns {string|null} Signal name, or null when none was reported
+ */
+function terminationSignalOf(testResult) {
+	return testResult.signal || testResult.signalCode || null;
+}
+
+/**
+ * Reports whether a test run was killed by its own wall-clock budget.
+ *
+ * Requires AFFIRMATIVE evidence. Verified against pinned Bun 1.3.12 on Windows:
+ * a `node:child_process` spawnSync timeout returns `status: null`,
+ * `signal: <killSignal>`, AND an error whose `code` is `ETIMEDOUT`. Native
+ * `Bun.spawnSync` instead sets `exitedDueToTimeout: true` with `signalCode`.
+ * Those two markers are the only proof of a timeout, and they are checked
+ * BEFORE the generic error branch — testing `error` first swallowed the timeout
+ * diagnostic in exactly the case it was written for.
+ *
+ * A bare kill signal with no marker is deliberately NOT treated as a timeout:
+ * an OOM kill or an operator `kill -9` produces the identical status/signal
+ * shape, and since a genuine budget kill always carries a marker, inferring
+ * from the signal alone buys nothing and costs a misdiagnosis (it would claim
+ * the budget elapsed and send the user to raise FORGE_TEST_TIMEOUT_MS).
+ *
+ * @param {Object} testResult - spawnSync result object
+ * @returns {boolean} True when the run hit its budget
+ */
+function isTimeoutTermination(testResult) {
+	if (testResult.exitedDueToTimeout === true) return true;
+	return Boolean(testResult.error) && testResult.error.code === 'ETIMEDOUT';
+}
+
+/**
+ * Explain a test run that never produced an exit status.
+ *
+ * `spawnSync` reports `status: null` when the child was killed by a signal
+ * (timeout kill included) or never started at all. Without this the push
+ * aborted with no summary at all, which is indistinguishable from a genuine
+ * test failure.
+ *
+ * @param {Object} testResult - spawnSync result object
+ * @param {number} timeoutMs - Wall-clock budget applied to the run
+ * @param {function} log - Logger function
+ */
+function reportTestRunTermination(testResult, timeoutMs, log) {
+	const signal = terminationSignalOf(testResult);
+
+	if (isTimeoutTermination(testResult)) {
+		log(
+			`Test run timed out after ${Math.round(timeoutMs / 1000)}s `
+			+ `(killed by ${signal || 'timeout'}) — push aborted.`,
+		);
+		log('Raise the budget with FORGE_TEST_TIMEOUT_MS if this machine is slower than the default.');
+		return;
+	}
+
+	if (testResult.error) {
+		log(`Test run could not complete: ${testResult.error.message}`);
+		return;
+	}
+
+	if (signal) {
+		// Signalled without timeout evidence: report the fact and the likely
+		// causes. Do NOT blame the budget — that sends the user after the wrong
+		// lever and hides the real failure.
+		log(
+			`Test run was terminated by ${signal} before finishing — push aborted. `
+			+ `The run had a ${Math.round(timeoutMs / 1000)}s budget but reported no timeout, `
+			+ 'so this is most likely an external kill or an out-of-memory kill.',
+		);
+		return;
+	}
+
+	log('Test run ended without an exit status — push aborted.');
+}
+
 /**
  * Run tests unless in quick mode, logging warnings for first push.
  * @param {function} spawnFn - spawnSync or mock
@@ -204,9 +287,10 @@ function runLint(spawnFn, pkgManager, projectRoot) {
  * @param {string} projectRoot - Absolute path to project root
  * @param {boolean} quickMode - Whether to skip tests
  * @param {function} log - Logger function
+ * @param {NodeJS.ProcessEnv} [env] - Environment used to resolve the test budget
  * @returns {boolean|undefined} True if tests passed, undefined if skipped
  */
-function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log) {
+function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, env = process.env) {
 	if (quickMode) {
 		log('Tests skipped (--quick) — CI will run full suite on GitHub');
 		const branch = getCurrentBranch(execFn);
@@ -216,12 +300,25 @@ function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log) {
 		return undefined;
 	}
 
+	// `forge push` runs the package-level `test` script, i.e. the whole suite.
+	// Budget it from the shared full-suite budget in scripts/test.js — which is
+	// sized as ~2x the measured healthy full-suite runtime and overridable with
+	// FORGE_TEST_TIMEOUT_MS — instead of an arbitrary local cap: the old fixed
+	// 120s killed a healthy full run mid-suite and pushed nothing. Never
+	// reintroduce a local constant here; change the shared budget with a fresh
+	// measurement instead.
+	const timeoutMs = resolveFullSuiteTimeoutMs(env);
 	const testResult = spawnFn(pkgManager, ['run', 'test'], {
 		stdio: 'inherit',
 		shell: isWindows,
 		cwd: projectRoot,
-		timeout: 120000,
+		timeout: timeoutMs,
+		killSignal: TEST_RUN_KILL_SIGNAL,
 	});
+	if (testResult.status === null || testResult.status === undefined) {
+		reportTestRunTermination(testResult, timeoutMs, log);
+		return false;
+	}
 	return testResult.status === 0;
 }
 
@@ -271,7 +368,7 @@ module.exports = {
 		}
 
 		// Step 3: Tests (skip in quick mode)
-		const testsPassed = runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log);
+		const testsPassed = runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, deps?.env || process.env);
 		if (!quickMode && !testsPassed) {
 			return { success: false, quickMode, lintPassed: true, testsPassed: false, pushed: false };
 		}
@@ -288,7 +385,7 @@ module.exports = {
 		// Step 5: git push with passthrough args
 		const gitArgs = args.filter(a => a !== '--quick');
 		try {
-			execFn('git', ['push', ...gitArgs], { stdio: 'inherit' });
+			execFn('git', ['push', ...gitArgs], { stdio: 'inherit', env: buildPushEnv(quickMode) });
 		} catch (_pushErr) { // NOSONAR S2486
 			log('git push failed.');
 			return {
@@ -300,15 +397,10 @@ module.exports = {
 			};
 		}
 
-		// Arm the constant PR watcher for this branch's open PR (best-effort,
-		// gated by rail.auto_shepherd, never fails the push). Covers PRs not born
-		// from `forge ship`.
-		maybeArmWatcherAfterPush({
+		// Wake the repository-wide singleton after a successful push.
+		maybeTriggerShepherdAfterPush({
 			projectRoot,
-			execFn,
-			startWatcher: deps?.startWatcher,
-			railEnabled: deps?.railEnabled,
-			prLookup: deps?.prLookup,
+			fireAndForget: deps?.fireAndForget,
 		});
 
 		return {
@@ -323,7 +415,7 @@ module.exports = {
 	// Exposed for unit tests; not part of the CLI surface.
 	_internal: {
 		autoFileBackingIssueForPush,
-		maybeArmWatcherAfterPush,
-		resolveOpenPrNumber,
+		buildPushEnv,
+		maybeTriggerShepherdAfterPush,
 	},
 };