forge-workflow 0.1.0-beta.2 → 0.1.0-beta.3

package/lib/commands/shepherd.js

@@ -36,8 +36,10 @@ const { validatePrStateAdapter } = require('../pr-state-validator');
 const { gatherMonitorSnapshot } = require('../pr-monitor/gather');
 const { pollEvents } = require('../pr-monitor/monitor');
 const { watchLoop } = require('../pr-monitor/watch');
+const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
 const monitorJournal = require('../pr-monitor/journal');
 const { EVENT_TYPES: T } = require('../pr-monitor/events');
+const { autoShepherdRailEnabled } = require('./ship');
 
 const DEFAULT_RERUN_BUDGET = 3;
 
@@ -270,11 +272,74 @@ function wireSignals() {
  * @param {object} [deps]
  * @returns {Promise<object>}
  */
+/**
+ * List every OPEN PR number via `gh pr list`. Fail-open: any error yields an
+ * empty list (adopt then arms nothing) rather than throwing.
+ *
+ * @param {Function} [exec] - gh runner (test injection).
+ * @returns {number[]}
+ */
+function defaultListOpenPrs(exec = execFileSync) {
+  try {
+    const out = exec('gh', ['pr', 'list', '--state', 'open', '--json', 'number', '-q', '.[].number'], {
+      encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return String(out)
+      .split(/\r?\n/)
+      .map((s) => Number.parseInt(s.trim(), 10))
+      .filter((n) => Number.isInteger(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * `forge shepherd watch --adopt` — arm a detached watcher for EVERY currently-open
+ * PR (covers PRs created via gh/UI, or before this rail existed). Idempotent: the
+ * watch loop's PID/journal lock means an already-watched PR is not double-started.
+ * Fail-open per PR and overall — never throws. Honors the default-ON
+ * `rail.auto_shepherd` rail: when a maintainer has disabled it, adoption is a
+ * no-op — no PR listing, no watcher spawn — matching `forge push`/`forge ship`.
+ *
+ * @param {string} projectRoot
+ * @param {object} [deps]
+ * @returns {{ success: true, adopted: number[], total: number, reason?: string }}
+ */
+function handleAdopt(projectRoot, deps = {}) {
+  const railEnabled = deps.railEnabled || autoShepherdRailEnabled;
+  // Gate BEFORE listing PRs / spawning watchers: a disabled rail must not spawn
+  // detached watchers. No-op result mirrors the fail-open (empty) adoption shape.
+  if (!railEnabled(projectRoot)) {
+    return { success: true, adopted: [], total: 0, reason: 'rail.auto_shepherd disabled' };
+  }
+  const listOpenPrs = deps.listOpenPrs || defaultListOpenPrs;
+  const startWatcher = deps.startWatcher || startPrWatcherDetached;
+  let prs;
+  try {
+    prs = listOpenPrs();
+  } catch {
+    prs = [];
+  }
+  if (!Array.isArray(prs)) prs = [];
+  const adopted = [];
+  for (const pr of prs) {
+    try {
+      const res = startWatcher({ prNumber: pr, cwd: projectRoot });
+      if (res?.started) adopted.push(pr);
+    } catch { /* fail-open per PR: one bad arm never blocks the rest */ }
+  }
+  return { success: true, adopted, total: prs.length };
+}
+
 async function handleWatch(args, projectRoot, deps = {}) {
   const rawArgs = args || [];
+  // `--adopt` (no PR arg): arm a detached watcher for every open PR.
+  if (rawArgs.includes('--adopt')) {
+    return handleAdopt(projectRoot, deps);
+  }
   const pr = rawArgs.find((a) => !String(a).startsWith('--') && a !== 'watch');
   if (!pr) {
-    return { success: false, error: 'Usage: forge shepherd watch <pr>' };
+    return { success: false, error: 'Usage: forge shepherd watch <pr> | forge shepherd watch --adopt' };
   }
 
   const built = await buildMonitorContext(pr, projectRoot, deps);
@@ -424,7 +489,7 @@ async function handler(args, _flags, projectRoot, deps = {}) {
 module.exports = {
   name: 'shepherd',
   description: 'Run one bounded monitor pass over a PR (rerun flaky checks, escalate, hand off — never merges)',
-  usage: 'Usage: forge shepherd <pr> [--auto-rebase] [--bundle --json] [--pull --json] | forge shepherd events <pr> --since <seq> [--json] | forge shepherd watch <pr>',
+  usage: 'Usage: forge shepherd <pr> [--auto-rebase] [--bundle --json] [--pull --json] | forge shepherd events <pr> --since <seq> [--json] | forge shepherd watch <pr> | forge shepherd watch --adopt',
   handler,
   handleEvents,
   handleWatch,

package/lib/commands/ship.js

@@ -13,6 +13,32 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
+const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+
+const AUTO_SHEPHERD_RAIL = 'rail.auto_shepherd';
+
+/**
+ * Whether the default-ON `rail.auto_shepherd` rail permits auto-starting the PR
+ * watcher. Reads the SAME resolved runtime graph the `forge gate enable|disable`
+ * surface writes (`workflow.gates.rail.auto_shepherd.enabled`), so the toggle is
+ * config-honest. FAIL-OPEN: only an explicit `enabled === false` disables it — a
+ * missing rail or any resolution error falls back to enabled (the default), and
+ * this NEVER throws (ship must not fail on a config read).
+ *
+ * @param {string} [projectRoot]
+ * @param {Function} [resolveGraph] - injectable graph resolver (tests).
+ * @returns {boolean}
+ */
+function autoShepherdRailEnabled(projectRoot = process.cwd(), resolveGraph = getResolvedRuntimeGraph) {
+	try {
+		const graph = resolveGraph({ projectRoot });
+		const rail = [...(graph.rails || []), ...(graph.gates || [])]
+			.find(entry => entry.id === AUTO_SHEPHERD_RAIL);
+		return !(rail && rail.enabled === false);
+	} catch {
+		return true;
+	}
+}
 
 function getExecOptions() {
 	return { encoding: 'utf8', cwd: process.cwd(), timeout: 120000 };
@@ -490,12 +516,21 @@ async function createPR(options) { // NOSONAR S3776
  * ship: `startWatcher` (startPrWatcherDetached) already never throws, and this
  * guard keeps even a surprise error from surfacing to the ship caller.
  *
- * @param {{ dryRun: boolean, prNumber?: string|number, startWatcher: Function }} params
+ * Gated by the default-ON `rail.auto_shepherd` rail: when a maintainer has
+ * disabled it (`forge gate disable rail.auto_shepherd`), the watcher is skipped
+ * so the auto-start is honestly toggleable. The rail check is fail-open and
+ * wrapped in the same try/catch, so neither a disabled rail nor a config-read
+ * error ever fails ship.
+ *
+ * @param {{ dryRun: boolean, prNumber?: string|number, startWatcher: Function, railEnabled?: Function }} params
  * @returns {{ started: boolean, reason?: string }}
  */
-function maybeStartPrWatcher({ dryRun, prNumber, startWatcher }) {
+function maybeStartPrWatcher({ dryRun, prNumber, startWatcher, railEnabled = autoShepherdRailEnabled }) {
 	if (dryRun || !prNumber) return { started: false, reason: 'skipped' };
 	try {
+		if (!railEnabled(process.cwd())) {
+			return { started: false, reason: 'rail.auto_shepherd disabled' };
+		}
 		return startWatcher({ prNumber, cwd: process.cwd() });
 	} catch (err) {
 		return { started: false, reason: err.message };
@@ -503,7 +538,7 @@ function maybeStartPrWatcher({ dryRun, prNumber, startWatcher }) {
 }
 
 async function executeShip(options) {
-	const { featureSlug, title, dryRun = false, startWatcher = startPrWatcherDetached } = options || {};
+	const { featureSlug, title, dryRun = false, startWatcher = startPrWatcherDetached, railEnabled = autoShepherdRailEnabled } = options || {};
 
 	// Validate feature slug
 	if (!featureSlug || typeof featureSlug !== 'string' || featureSlug.trim() === '') {
@@ -555,7 +590,7 @@ async function executeShip(options) {
 		});
 		const result = await createPR({ title, body: prBody, dryRun });
 		if (!result.success) return result;
-		maybeStartPrWatcher({ dryRun, prNumber: result.prNumber, startWatcher });
+		maybeStartPrWatcher({ dryRun, prNumber: result.prNumber, startWatcher, railEnabled });
 		return {
 			success: true,
 			prUrl: result.prUrl,
@@ -589,6 +624,7 @@ module.exports = {
 		};
 	},
 	maybeStartPrWatcher,
+	autoShepherdRailEnabled,
 	extractKeyDecisions,
 	extractTestScenarios,
 	getTestCoverage,

package/lib/commands/worktree.js

@@ -3,6 +3,7 @@
 const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const { detectDefaultBranch } = require('../beads-sync-scaffold');
 
 /**
  * Forge Worktree Command
@@ -53,6 +54,40 @@ function branchExists(branchName, runFile) {
   }
 }
 
+/**
+ * True when a git ref resolves to a commit (branch, tag, remote-tracking ref, or SHA).
+ * @param {string} ref - The ref to check
+ * @param {string} projectRoot - Repo root to run git in
+ * @param {Function} runFile - execFileSync function (for DI)
+ * @returns {boolean}
+ */
+function refExists(ref, projectRoot, runFile) {
+  try {
+    runFile('git', ['-C', projectRoot, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch (_err) { /* intentional: ref does not resolve */ // NOSONAR S2486
+    return false;
+  }
+}
+
+/**
+ * Resolve the base ref a NEW worktree branch should fork from. Defaults to the
+ * repo's DEFAULT branch (NOT the checkout's current HEAD) so a worktree created
+ * off a WIP branch never silently inherits unrelated commits. Prefers the remote
+ * default (`origin/<default>`) when present, else the local default branch, and
+ * falls back to the detected name so git surfaces a clear error if neither exists.
+ * @param {string} projectRoot - Repo root
+ * @param {Function} runFile - execFileSync function (for DI)
+ * @returns {string} The base ref to pass to `git worktree add ... <base>`
+ */
+function resolveDefaultBase(projectRoot, runFile) {
+  const def = detectDefaultBranch(projectRoot, { _exec: runFile });
+  const originRef = `origin/${def}`;
+  if (refExists(originRef, projectRoot, runFile)) return originRef;
+  if (refExists(def, projectRoot, runFile)) return def;
+  return def;
+}
+
 /**
  * True when a link failure is a privilege/support problem (Windows without the
  * symlink privilege, restricted FS) rather than a real error. In that case we
@@ -278,6 +313,14 @@ async function handleCreate(slug, flags, projectRoot, opts) {
 
   const worktreePath = path.resolve(worktreesDir, slug);
 
+  // Validate an explicit --base up front so a bad ref errors BEFORE anything is
+  // created (no branch, no worktree dir). Base only applies when creating a NEW
+  // branch; an existing branch is checked out as-is.
+  const explicitBase = flags['--base'] || null;
+  if (explicitBase && !refExists(explicitBase, projectRoot, runFile)) {
+    return { success: false, error: `Invalid --base: ref '${explicitBase}' not found. Verify it exists (git rev-parse --verify ${explicitBase}).` };
+  }
+
   // Step 0: Check if worktree already exists
   if (fsApi.existsSync(worktreePath)) {
     // A pre-existing worktree may be checked out on a different branch than the
@@ -303,12 +346,17 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   // Step 1: Ensure .worktrees/ dir exists
   fsApi.mkdirSync(worktreesDir, { recursive: true });
 
-  // Step 2: Create git worktree
+  // Step 2: Create git worktree. For a NEW branch, fork from an explicit --base or
+  // the repo's DEFAULT branch — NOT the checkout's current HEAD — so the worktree
+  // never silently inherits unrelated WIP commits (B2). An existing branch is
+  // checked out as-is (no base applies).
   const hasBranch = branchExists(branchName, runFile);
+  let base = null;
   if (hasBranch) {
     runFile('git', ['worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
   } else {
-    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName], { stdio: 'pipe' });
+    base = explicitBase || resolveDefaultBase(projectRoot, runFile);
+    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName, base], { stdio: 'pipe' });
   }
 
   // Step 3: Populate node_modules (link to the shared install, else install).
@@ -329,14 +377,19 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: branchName, issueId, workFolder, opts });
   const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: branchName, issueId, opts });
 
+  // Report the base so the fork point is never silent. `base` is null when an
+  // existing branch was checked out (no fork happened).
+  const baseNote = base ? `based on ${base}` : `existing branch ${branchName}`;
   return {
     success: true,
     worktreePath,
     branch: branchName,
+    base,
     depsLinked: deps.linked,
     depsInstalled: deps.installed,
     linkage,
     backing,
+    output: `Created worktree ${worktreePath} on ${branchName} (${baseNote}).`,
   };
 }
 
@@ -383,8 +436,8 @@ async function handleRemove(slug, projectRoot, opts) {
 }
 
 // Long flags that take a value, in both `--flag value` and `--flag=value` forms.
-const WORKTREE_VALUE_FLAGS = ['--branch', '--issue', '--work-folder'];
-const WORKTREE_USAGE_HINT = 'Usage: forge worktree create <slug> [--branch <name>] [--issue <id>] [--work-folder <path>]';
+const WORKTREE_VALUE_FLAGS = ['--branch', '--issue', '--work-folder', '--base'];
+const WORKTREE_USAGE_HINT = 'Usage: forge worktree create <slug> [--branch <name>] [--base <ref>] [--issue <id>] [--work-folder <path>]';
 
 function parseWorktreeArgs(args, flags) {
   const positional = [];
@@ -429,6 +482,7 @@ module.exports = {
   usage: 'forge worktree <create|remove|list> <slug>',
   flags: {
     '--branch': 'Custom branch name (default: feat/<slug>)',
+    '--base': 'Base ref a new branch forks from (default: the repo default branch, e.g. origin/main)',
     '--issue': 'Kernel issue id to link this worktree to (records issue → worktree)',
     '--work-folder': 'Repo-relative work-folder this issue owns (records worktree → work-folder + drops a .forge-issue marker)',
   },
@@ -486,5 +540,7 @@ module.exports = {
     setupWorktreeDeps,
     runInstall,
     autoFileBackingIssue,
+    refExists,
+    resolveDefaultBase,
   },
 };

package/lib/core/runtime-graph.js

@@ -412,6 +412,27 @@ const RESOLVED_RUNTIME_GRAPH = {
       label: 'Issue write verification (check-after-write)',
       requires: [],
     }),
+    // Grounding gates (epic 6ef96e92, design docs/work/2026-07-16-grounding-
+    // enforcement/design.md) — the first gates that DENY (fd4c03b3's first real
+    // payment). gate.read_first: acting on an issue requires having read it —
+    // consulted fail-closed at the `forge claim` boundary against a
+    // `context.loaded` kernel event (lib/grounding/context-events.js), remedy
+    // `forge recap <id>`. gate.cite: shipped artifacts must cite their sources —
+    // registered here (togglable) but its scanner lands in P3; it denies nothing
+    // yet. Both phase-less, default-ON, UNLOCKED, same toggle surface as
+    // gate.issue_verify (`forge gate disable gate.read_first`). Master switch is
+    // the unlocked rail.grounding below. `requires: []` — the context.loaded
+    // event (not evidence) is the exit condition.
+    Gate({
+      id: 'gate.read_first',
+      label: 'Read the issue before acting on it',
+      requires: [],
+    }),
+    Gate({
+      id: 'gate.cite',
+      label: 'Cite sources in shipped artifacts',
+      requires: [],
+    }),
   ],
   evidence: [
     Evidence({
@@ -446,12 +467,18 @@ const RESOLVED_RUNTIME_GRAPH = {
   // may opt out via `forge gate disable rail.kernel_tracking`, consumed by the
   // resolver's rail-aware gate loop over workflow.gates.<id>.enabled).
   rails: [
-    { key: 'tdd_intent', label: 'TDD intent evidence', description: 'Source changes require test intent and TDD evidence.' },
+    { key: 'tdd_intent', label: 'TDD intent evidence', description: 'Source changes require test intent and TDD evidence. Strong default (ON), but not a hard floor — disable with `forge gate disable rail.tdd_intent`.', locked: false },
     { key: 'secret_scan', label: 'Secret scan', description: 'Validation must not knowingly ship secrets.' },
     { key: 'branch_protection', label: 'Branch protection', description: 'Ship through reviewed branches instead of direct protected-branch edits.' },
     { key: 'signed_commits', label: 'Signed commits', description: 'Preserve commit provenance requirements where configured.' },
     { key: 'schema_integrity', label: 'Schema integrity', description: 'Keep runtime graph and config schemas internally consistent.' },
     { key: 'kernel_tracking', label: 'Kernel issue tracking', description: 'Every issue, idea, bug, and decision discussed is filed to the Forge Kernel.', locked: false },
+    { key: 'auto_shepherd', label: 'Auto-start PR shepherd watch', description: 'On `forge ship` success, auto-start the detached, self-stopping `forge shepherd watch <pr>` monitor so a shipped PR is tended without a manual trigger. Default-ON, UNLOCKED — opt out with `forge gate disable rail.auto_shepherd`.', locked: false },
+    // grounding — the one-switch master toggle over gate.read_first + gate.cite.
+    // UNLOCKED, default-ON (like kernel_tracking): a maintainer may opt out via
+    // `forge gate disable rail.grounding`, which the read_first consult treats as
+    // "allow, logged". Ingrains "read the documented source before acting; cite it".
+    { key: 'grounding', label: 'Documented-grounding enforcement', description: 'Read the issue before acting on it; cite sources in shipped artifacts.', locked: false },
   ].map(def => Rail({ id: `rail.${def.key}`, ...def })),
   adapters: [
     Adapter({
@@ -605,14 +632,18 @@ function applyRailConfig(graph, config, errors) {
     if (!enabled.valid) {
       continue;
     }
-    if (enabled.value === false) {
+    if (enabled.value === false && rail.locked === true) {
+      // Locked L1 rails remain a non-negotiable floor; only unlocked rails
+      // (e.g. tdd_intent, kernel_tracking) may be disabled via config.
       errors.push({
         code: 'LOCKED_L1_RAIL_DISABLED',
         message: `Cannot disable locked L1 rail '${key}'.`,
       });
       continue;
     }
-    if (options && Object.keys(options).length > 0) {
+    if (enabled.present) {
+      markConfigured(rail, { enabled: enabled.value });
+    } else if (options && Object.keys(options).length > 0) {
       rail.configSource = CONFIG_SOURCE;
     }
   }

package/lib/gate-events.js

@@ -23,7 +23,7 @@
  * runtime graph + `.forge/config.yaml`; this module only records/reads the events.
  */
 
-const { buildMigratedKernelIssueDeps } = require('./kernel/cli-broker-factory');
+const { resolveOwnedKernel, closeIfOwned } = require('./kernel/owned-kernel');
 const { resolveIssueActor } = require('./forge-issues');
 
 const GATE_APPROVED_EVENT = 'gate.approved';
@@ -37,22 +37,12 @@ const GATE_EVENT_TYPES = {
 const ISSUE_ENTITY_TYPE = 'issue';
 const GATE_EVENT_ORIGIN = 'cli';
 
-/**
- * Resolve the kernel broker + driver + config. Tests (and the orchestrator) inject
- * a shared, already-migrated kernel via `deps`; the CLI path builds a fresh one for
- * the (short-lived) process.
- *
- * @param {string} projectRoot
- * @param {{ kernelBroker?: Object, kernelDriver?: Object }} [deps]
- * @returns {Promise<{ broker: Object, driver: Object, config: Object }>}
- */
-async function resolveGateKernel(projectRoot, deps = {}) {
-  if (deps.kernelBroker && deps.kernelDriver) {
-    return { broker: deps.kernelBroker, driver: deps.kernelDriver, config: deps.kernelBroker.config };
-  }
-  const built = await buildMigratedKernelIssueDeps({ projectRoot });
-  return { broker: built.kernelBroker, driver: built.kernelDriver, config: built.kernelBroker.config };
-}
+// Kernel lifecycle (resolve + close-what-you-built) is shared with
+// grounding/context-events via lib/kernel/owned-kernel. A gate read/append that
+// builds its own kernel must close it — an unclosed SQLite handle leaks and, on
+// Windows, locks the DB directory (EBUSY on rmSync, kernel issue e62e4bde). Safe
+// here today because gate events only fire on explicit `forge gate` commands,
+// but the leak is identical so we close proactively via closeIfOwned.
 
 /**
  * Idempotency key for a gate event. Scoped to issue + gate + actor + decision so a
@@ -110,44 +100,49 @@ async function recordGateEvent(projectRoot, params = {}) {
   }
 
   const actor = resolveIssueActor(env || process.env) || 'forge';
-  const { driver, config } = await resolveGateKernel(projectRoot, deps);
-
-  const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
-  if (!entity) {
-    return { ok: false, issueMissing: true, actor };
-  }
+  const kernel = await resolveOwnedKernel(projectRoot, deps);
+  const { driver, config } = kernel;
 
-  const idempotencyKey = gateIdempotencyKey(eventType, issueId, gateId, actor);
+  try {
+    const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    if (!entity) {
+      return { ok: false, issueMissing: true, actor };
+    }
 
-  const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
-  if (existing) {
-    return { ok: true, duplicate: true, event: parseGateEvent(existing), actor };
-  }
+    const idempotencyKey = gateIdempotencyKey(eventType, issueId, gateId, actor);
 
-  const payload = { gate: gateId, actor };
-  if (typeof reason === 'string' && reason.length > 0) payload.reason = reason;
-
-  const event = {
-    entity_type: ISSUE_ENTITY_TYPE,
-    entity_id: issueId,
-    event_type: eventType,
-    idempotency_key: idempotencyKey,
-    expected_revision: 0,
-    actor,
-    origin: GATE_EVENT_ORIGIN,
-    payload,
-    created_at: now || new Date().toISOString(),
-  };
+    const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+    if (existing) {
+      return { ok: true, duplicate: true, event: parseGateEvent(existing), actor };
+    }
 
-  try {
-    const inserted = await driver.insertKernelEvent(event, {}, config);
-    return { ok: true, duplicate: false, event: parseGateEvent(inserted), actor };
-  } catch (error) {
-    if (isIdempotencyRace(error)) {
-      const winner = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
-      return { ok: true, duplicate: true, event: winner ? parseGateEvent(winner) : parseGateEvent(event), actor };
+    const payload = { gate: gateId, actor };
+    if (typeof reason === 'string' && reason.length > 0) payload.reason = reason;
+
+    const event = {
+      entity_type: ISSUE_ENTITY_TYPE,
+      entity_id: issueId,
+      event_type: eventType,
+      idempotency_key: idempotencyKey,
+      expected_revision: 0,
+      actor,
+      origin: GATE_EVENT_ORIGIN,
+      payload,
+      created_at: now || new Date().toISOString(),
+    };
+
+    try {
+      const inserted = await driver.insertKernelEvent(event, {}, config);
+      return { ok: true, duplicate: false, event: parseGateEvent(inserted), actor };
+    } catch (error) {
+      if (isIdempotencyRace(error)) {
+        const winner = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+        return { ok: true, duplicate: true, event: winner ? parseGateEvent(winner) : parseGateEvent(event), actor };
+      }
+      throw error;
     }
-    throw error;
+  } finally {
+    closeIfOwned(kernel);
   }
 }
 
@@ -160,11 +155,15 @@ async function recordGateEvent(projectRoot, params = {}) {
  * @returns {Promise<Array<{ event_type: string, gate: string, actor: string, created_at: string, reason?: string }>>}
  */
 async function listGateEvents(projectRoot, issueId, options = {}) {
-  const { driver, config } = await resolveGateKernel(projectRoot, options.deps);
-  const rows = await driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, config);
-  return (rows || [])
-    .filter(row => typeof row.event_type === 'string' && row.event_type.startsWith('gate.'))
-    .map(parseGateEvent);
+  const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+  try {
+    const rows = await kernel.driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, kernel.config);
+    return (rows || [])
+      .filter(row => typeof row.event_type === 'string' && row.event_type.startsWith('gate.'))
+      .map(parseGateEvent);
+  } finally {
+    closeIfOwned(kernel);
+  }
 }
 
 /**

package/lib/global-flags.js

@@ -67,8 +67,38 @@ function stripGlobalFlags(args) {
   return kept;
 }
 
+/**
+ * Index of the first positional token (a bare, non-flag argument), skipping any
+ * leading global flags and their consumed values. Returns -1 when no positional
+ * exists. Uses the SAME flag-consumption rules as {@link stripGlobalFlags} so the
+ * two agree on what counts as a positional. Unlike stripGlobalFlags this returns
+ * an index into the ORIGINAL array, so callers can splice out the positional
+ * while preserving the intervening flags.
+ *
+ * @param {string[]} args - Raw command arguments.
+ * @param {number} [start=0] - Index to begin scanning from.
+ * @returns {number} Index into `args` of the first positional token, or -1.
+ */
+function firstPositionalIndex(args, start = 0) {
+  for (let index = start; index < args.length; index += 1) {
+    const arg = args[index];
+    if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
+    if (GLOBAL_VALUE_FLAG_PREFIXES.some((prefix) => arg.startsWith(prefix))) continue;
+    if (GLOBAL_VALUE_FLAGS.has(arg)) {
+      const next = args[index + 1];
+      if (next !== undefined && !next.startsWith('-')) index += 1;
+      continue;
+    }
+    // Any other dash-prefixed token is a non-global flag, not the positional.
+    if (arg.startsWith('-')) continue;
+    return index;
+  }
+  return -1;
+}
+
 module.exports = {
   GLOBAL_BOOLEAN_FLAGS,
   GLOBAL_VALUE_FLAGS,
   stripGlobalFlags,
+  firstPositionalIndex,
 };