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

package/lib/grounding/context-events.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * @module grounding/context-events
+ *
+ * The state primitive behind gate.read_first: "this issue's context was loaded"
+ * recorded as a durable kernel EVENT, structurally identical to gate.approved
+ * (lib/gate-events.js). `forge recap`/`forge show` append a `context.loaded`
+ * event to the issue's stream on a successful render; `forge claim` refuses to
+ * proceed until such an event exists for the issue this session/window.
+ *
+ * Mechanism (mirrors gate-events, deliberately): a PURE APPEND via the driver
+ * primitives (`insertKernelEvent` + `listKernelEvents`), NOT the guarded
+ * issue-mutation pipeline — context.loaded does not mutate the issue, so it must
+ * not participate in the issue-revision CAS. Idempotency is enforced by a
+ * window-bucketed key (so a re-read inside the freshness window mints no
+ * duplicate, but a re-read in the NEXT window mints a fresh event that clears a
+ * re-block) plus the unique idempotency index catching a concurrent race.
+ *
+ * Config-surface note: whether the gate is enabled lives in the runtime graph +
+ * `.forge/config.yaml`; this module only records/reads the events.
+ */
+
+const { resolveOwnedKernel, closeIfOwned } = require('../kernel/owned-kernel');
+const { resolveIssueActor } = require('../forge-issues');
+
+const CONTEXT_LOADED_EVENT = 'context.loaded';
+const ISSUE_ENTITY_TYPE = 'issue';
+const CONTEXT_EVENT_ORIGIN = 'cli';
+// Tier-2 agnostic freshness floor: a stale-but-loaded issue re-blocks after this
+// window; one `forge recap` clears it. Overridable via
+// `workflow.gates.gate.read_first.window` at the call site (P2).
+const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+// Kernel lifecycle (resolve + close-what-you-built) is shared with gate-events
+// via lib/kernel/owned-kernel; `resolveOwnedKernel`/`closeIfOwned` are imported.
+
+/** Coarse window bucket for a timestamp — the roll-over that makes re-reads fresh. */
+function windowBucket(nowMs, windowMs) {
+  return Math.floor(nowMs / windowMs);
+}
+
+/**
+ * Idempotency key for a context.loaded event. Scoped to issue + scope
+ * (session id when present, else actor) + window bucket so a re-read inside the
+ * window is idempotent, while the next window mints a fresh event.
+ */
+function contextLoadedIdempotencyKey(issueId, scope, bucket) {
+  return `${CONTEXT_LOADED_EVENT}:${issueId}:${scope}:${bucket}`;
+}
+
+/** Shape a stored kernel_events row into the context-event view callers consume. */
+function parseContextEvent(row) {
+  let payload;
+  try {
+    payload = row.payload_json ? JSON.parse(row.payload_json) : {};
+  } catch {
+    payload = {};
+  }
+  const view = {
+    event_type: row.event_type,
+    actor: row.actor,
+    created_at: row.created_at,
+  };
+  if (payload.session !== undefined) view.session = payload.session;
+  if (payload.cmd !== undefined) view.cmd = payload.cmd;
+  if (payload.budget !== undefined) view.budget = payload.budget;
+  return view;
+}
+
+function isIdempotencyRace(error) {
+  const message = error && error.message ? String(error.message) : '';
+  return /UNIQUE constraint failed/i.test(message) && /idempotency_key/i.test(message);
+}
+
+/**
+ * Record that an issue's context was loaded. Idempotent per issue+scope+window.
+ * Validates the issue exists (no orphan events).
+ *
+ * @param {string} projectRoot
+ * @param {Object} params
+ * @param {string} params.issueId
+ * @param {string} [params.cmd] - the command that loaded the context (recap|show).
+ * @param {string} [params.session] - harness session id (Tier-1 scoping) when known.
+ * @param {number|string} [params.budget]
+ * @param {Object} [params.env] - env source for actor resolution.
+ * @param {Object} [params.deps] - injected { kernelBroker, kernelDriver }.
+ * @param {string} [params.now] - ISO timestamp (defaults to now).
+ * @param {number} [params.windowMs] - freshness window (defaults to 24h).
+ * @returns {Promise<{ ok: boolean, duplicate?: boolean, issueMissing?: boolean, event?: Object, actor?: string }>}
+ */
+async function recordContextLoaded(projectRoot, params = {}) {
+  const { issueId, cmd, session, budget, env, deps, now, windowMs } = params;
+  const actor = resolveIssueActor(env || process.env) || 'forge';
+  const kernel = await resolveOwnedKernel(projectRoot, deps);
+  const { driver, config } = kernel;
+
+  try {
+    const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    if (!entity) {
+      return { ok: false, issueMissing: true, actor };
+    }
+
+    const nowIso = now || new Date().toISOString();
+    const win = Number.isFinite(windowMs) ? windowMs : DEFAULT_WINDOW_MS;
+    const bucket = windowBucket(Date.parse(nowIso), win);
+    const scope = session || actor;
+    const idempotencyKey = contextLoadedIdempotencyKey(issueId, scope, bucket);
+
+    const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+    if (existing) {
+      return { ok: true, duplicate: true, event: parseContextEvent(existing), actor };
+    }
+
+    const payload = { actor };
+    if (typeof session === 'string' && session.length > 0) payload.session = session;
+    if (typeof cmd === 'string' && cmd.length > 0) payload.cmd = cmd;
+    if (budget !== undefined) payload.budget = budget;
+
+    const event = {
+      entity_type: ISSUE_ENTITY_TYPE,
+      entity_id: issueId,
+      event_type: CONTEXT_LOADED_EVENT,
+      idempotency_key: idempotencyKey,
+      expected_revision: 0,
+      actor,
+      origin: CONTEXT_EVENT_ORIGIN,
+      payload,
+      created_at: nowIso,
+    };
+
+    try {
+      const inserted = await driver.insertKernelEvent(event, {}, config);
+      return { ok: true, duplicate: false, event: parseContextEvent(inserted), actor };
+    } catch (error) {
+      if (isIdempotencyRace(error)) {
+        const winner = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+        return { ok: true, duplicate: true, event: winner ? parseContextEvent(winner) : parseContextEvent(event), actor };
+      }
+      throw error;
+    }
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+/**
+ * List every context.loaded event on an issue, oldest first.
+ *
+ * @returns {Promise<Array<{ event_type: string, actor: string, created_at: string, session?: string, cmd?: string }>>}
+ */
+async function listContextLoadedEvents(projectRoot, issueId, options = {}) {
+  const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+  try {
+    const rows = await kernel.driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, kernel.config);
+    return (rows || [])
+      .filter(row => row.event_type === CONTEXT_LOADED_EVENT)
+      .map(parseContextEvent);
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+/**
+ * True iff the issue has a context.loaded event that satisfies scoping:
+ * - Tier-1 (session given): an event stamped with the SAME session.
+ * - Tier-2 (no session): an event newer than the freshness window.
+ *
+ * @param {string} projectRoot
+ * @param {string} issueId
+ * @param {{ session?: string, windowMs?: number, now?: string, deps?: Object }} [options]
+ * @returns {Promise<boolean>}
+ */
+async function hasFreshContextLoaded(projectRoot, issueId, options = {}) {
+  const { session, windowMs, now, deps } = options;
+  const events = await listContextLoadedEvents(projectRoot, issueId, { deps });
+  return eventsSatisfyFreshness(events, { session, windowMs, now });
+}
+
+/** Shared freshness predicate over an already-listed event set. */
+function eventsSatisfyFreshness(events, { session, windowMs, now } = {}) {
+  if (!events || events.length === 0) return false;
+  if (typeof session === 'string' && session.length > 0) {
+    return events.some(event => event.session === session);
+  }
+  const nowMs = now ? Date.parse(now) : Date.now();
+  const win = Number.isFinite(windowMs) ? windowMs : DEFAULT_WINDOW_MS;
+  return events.some(event => {
+    const ts = Date.parse(event.created_at);
+    return Number.isFinite(ts) && (nowMs - ts) <= win;
+  });
+}
+
+/**
+ * The gate.read_first verdict for an issue, resolving the kernel ONCE:
+ * - 'missing': the issue does not exist in the consulted kernel. The gate is
+ *   INERT — grounding a phantom issue is meaningless and the real claim will
+ *   fail on its own; this is also what keeps unit doubles (fake runner, no real
+ *   store) from being false-blocked. No bypass for a REAL issue: a claim on a
+ *   non-existent issue fails regardless.
+ * - 'loaded': a context.loaded event satisfies session/window scoping -> allow.
+ * - 'unread': the issue exists but has no fresh context.loaded event -> BLOCK.
+ *
+ * @returns {Promise<'missing'|'loaded'|'unread'>}
+ */
+async function readFirstVerdict(projectRoot, issueId, options = {}) {
+  const { session, windowMs, now, deps } = options;
+  const kernel = await resolveOwnedKernel(projectRoot, deps);
+  const { driver, config } = kernel;
+  try {
+    const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    if (!entity) return 'missing';
+    const rows = await driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    const events = (rows || []).filter(row => row.event_type === CONTEXT_LOADED_EVENT).map(parseContextEvent);
+    return eventsSatisfyFreshness(events, { session, windowMs, now }) ? 'loaded' : 'unread';
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+module.exports = {
+  CONTEXT_LOADED_EVENT,
+  DEFAULT_WINDOW_MS,
+  contextLoadedIdempotencyKey,
+  parseContextEvent,
+  recordContextLoaded,
+  listContextLoadedEvents,
+  hasFreshContextLoaded,
+  readFirstVerdict,
+};

package/lib/grounding/read-first.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * @module grounding/read-first
+ *
+ * gate.read_first — the first gate that DENIES (fd4c03b3's first real payment):
+ * acting on an issue requires having read it. Consulted at the `forge claim`
+ * chokepoint (P1) exactly like gate.issue_verify is consulted at the _issue.js
+ * boundary (isIssueVerifyEnabled). Fail-closed: no context.loaded event for the
+ * issue this session/window -> a block result whose remedy IS the load action
+ * (`forge recap <id>`), so the cheapest path through the gate is the correct
+ * behavior. Disabling rail.grounding (master) or gate.read_first allows the
+ * action (logged), same toggle surface as rail.kernel_tracking.
+ */
+
+const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+const { readFirstVerdict } = require('./context-events');
+
+const GROUNDING_RAIL_ID = 'rail.grounding';
+const READ_FIRST_GATE_ID = 'gate.read_first';
+
+/**
+ * The block message. Contract: exit != 0, remedy is one copy-pastable command,
+ * and running that command both satisfies the gate AND injects the context.
+ */
+function buildReadFirstBlockMessage(issueId) {
+  return [
+    `✗ ${READ_FIRST_GATE_ID}: issue ${issueId} has not been read this session.`,
+    `  Run: forge recap ${issueId} first`,
+    `  Then retry. (Override: forge gate disable ${READ_FIRST_GATE_ID} — logged.)`,
+  ].join('\n');
+}
+
+/**
+ * Resolve whether grounding + read_first are BOTH enabled. Mirrors
+ * isIssueVerifyEnabled: an injected opts.resolveRuntimeGraph wins (tests); an
+ * unresolvable config (lint errors) yields `unknown` so the caller can fail-open
+ * on a broken config rather than bricking claim.
+ *
+ * @returns {{ enabled: boolean, disabledPrimitive?: string, unknown?: boolean }}
+ */
+function resolveReadFirstEnabled(projectRoot, opts = {}) {
+  const resolveGraph = opts.resolveRuntimeGraph || getResolvedRuntimeGraph;
+  let graph;
+  try {
+    graph = resolveGraph({ projectRoot });
+  } catch {
+    return { enabled: false, unknown: true };
+  }
+  const rail = (graph.rails || []).find(candidate => candidate.id === GROUNDING_RAIL_ID);
+  const gate = (graph.gates || []).find(candidate => candidate.id === READ_FIRST_GATE_ID);
+  const railOn = rail ? rail.enabled !== false : true;
+  const gateOn = gate ? gate.enabled !== false : true;
+  if (!railOn) return { enabled: false, disabledPrimitive: GROUNDING_RAIL_ID };
+  if (!gateOn) return { enabled: false, disabledPrimitive: READ_FIRST_GATE_ID };
+  return { enabled: true };
+}
+
+/**
+ * Consult gate.read_first for an issue. Returns `null` when the action is
+ * allowed (gate off, or a fresh context.loaded event exists), or a block result
+ * `{ success:false, error, exitCode }` when the issue has not been read.
+ *
+ * @param {string} projectRoot
+ * @param {string} issueId
+ * @param {Object} [opts] - { resolveRuntimeGraph, kernelBroker, kernelDriver, session, windowMs, now }
+ * @returns {Promise<null | { success: false, error: string, exitCode: number }>}
+ */
+async function checkReadFirst(projectRoot, issueId, opts = {}) {
+  const state = resolveReadFirstEnabled(projectRoot, opts);
+  if (!state.enabled) {
+    // Disabled (or unresolvable config) -> allow. Log the deliberate skip.
+    if (state.disabledPrimitive) {
+      console.error(`forge: ${state.disabledPrimitive} disabled — claim on ${issueId} allowed without grounding check.`);
+    }
+    return null;
+  }
+
+  const deps = (opts.kernelBroker && opts.kernelDriver)
+    ? { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver }
+    : undefined;
+
+  let verdict;
+  try {
+    verdict = await readFirstVerdict(projectRoot, issueId, {
+      session: opts.session,
+      windowMs: opts.windowMs,
+      now: opts.now,
+      deps,
+    });
+  } catch {
+    // Kernel unavailable (broken env) -> fail-open, like issue_verify on a
+    // config error. In production the project kernel resolves; the enforced
+    // path is the normal one.
+    return null;
+  }
+
+  // 'missing' -> the issue is not in the consulted kernel; the gate is inert (a
+  // real claim on a non-existent issue fails on its own — no grounding bypass).
+  // 'loaded' -> a fresh context.loaded event exists. Both allow.
+  if (verdict !== 'unread') return null;
+
+  return { success: false, error: buildReadFirstBlockMessage(issueId), exitCode: 6 };
+}
+
+module.exports = {
+  GROUNDING_RAIL_ID,
+  READ_FIRST_GATE_ID,
+  buildReadFirstBlockMessage,
+  resolveReadFirstEnabled,
+  checkReadFirst,
+};

package/lib/hook-renderer.js

@@ -75,6 +75,21 @@ const FORGE_CONTEXT_MARKER = 'hooks session-start';
 // re-merge recognizes + replaces the Forge-owned UserPromptSubmit entry in place, exactly
 // as FORGE_CONTEXT_MARKER does for the SessionStart entry.
 const FORGE_INBOX_CONTEXT_MARKER = 'hooks inbox-pickup';
+// The PR-shepherd events context hook (a SECOND UserPromptSubmit-tier hook). Its own
+// marker so a re-merge recognizes + replaces the Forge-owned entry in place. The whole
+// Forge UserPromptSubmit group is already recognized via the inbox marker, but this keeps
+// the shepherd-events command independently identifiable (symmetry with the other tiers).
+const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
+// The capture-on-exit context hook (PreCompact + Stop tier). A THIRD context marker so a
+// re-merge recognizes + replaces the Forge-owned PreCompact/Stop entries in place. Both
+// events share this one marker (they differ only by a --trigger suffix on the command).
+//
+// It matches the FULL resolved Forge invocation (`node "<abs bin/forge.js>" hooks capture`),
+// NOT the bare `hooks capture` verb: a bare-substring check would treat ANY user hook command
+// that merely mentions "hooks capture" as Forge-owned and DELETE it on re-merge (data-integrity
+// bug, CodeRabbit on #397). Only Forge's own rendered capture command contains this prefix, so
+// the merge replaces exactly Forge's group and preserves the user's.
+const FORGE_CAPTURE_CONTEXT_MARKER = `${FORGE_CLI} hooks capture`;
 
 // Per-harness SessionStart context-injection capability. Honest capability matrix —
 // only Claude exposes a native session-start surface that can inject additionalContext.
@@ -99,6 +114,18 @@ const USER_PROMPT_SUBMIT_SUPPORT = Object.freeze({
   hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
 });
 
+// Per-harness session-END (capture-on-exit) capability. Only Claude exposes native
+// PreCompact + Stop hook surfaces where Forge can snapshot session learnings BEFORE
+// context is compacted or the session ends. Cursor 1.7 hooks are deny-oriented with no
+// session-end surface; Codex and Hermes hooks live in GLOBAL home config project setup
+// never writes. Same honesty rule as the other context tiers — no faked parity.
+const SESSION_END_SUPPORT = Object.freeze({
+  claude: Object.freeze({ rendered: true }),
+  cursor: Object.freeze({ rendered: false, reason: 'no-session-end-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
+  hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
+});
+
 // Claude exposes $CLAUDE_PROJECT_DIR (absolute project root) to hook commands and
 // documents it as THE cwd-independent way to reference project-local hook scripts —
 // a bare relative path breaks whenever Claude runs the hook from another cwd. Cursor
@@ -114,7 +141,7 @@ function adapterInvocation(harness) {
  * (per-commit) so the rendered Claude PreToolUse groups read write-guard first.
  */
 const FORGE_HOOK_CONTRACT = Object.freeze({
-  schemaVersion: '1.1.0',
+  schemaVersion: '1.2.0',
   kind: 'forge.hookContract',
   adapter: FORGE_HOOK_ADAPTER,
   intents: Object.freeze([
@@ -152,6 +179,35 @@ const FORGE_HOOK_CONTRACT = Object.freeze({
       lifecycle: 'user-prompt-submit',
       command: `${FORGE_CLI} hooks inbox-pickup`,
     }),
+    Object.freeze({
+      id: 'shepherd-events',
+      kind: 'context',
+      cliAction: 'shepherd-events',
+      // PR-SHEPHERD DELTAS: surfaces a compact, capped digest of NEW PR-monitor events
+      // (verdict changes, failed checks, new threads, merged/closed) since the last read,
+      // then advances the per-PR consumer cursor. This is the CONSUMER side of the constant
+      // watcher — the watch loop writes the journal, this pushes the deltas each turn. Reads
+      // the user's OWN local journal via a supported hook — NEVER stdin injection, never
+      // drives the agent (Anthropic Usage Policy).
+      enforces: 'PR shepherd events: on each UserPromptSubmit, surface a compact, capped digest of NEW PR-monitor events (verdict changes, failed checks, new threads, merged/closed) since the last read across open-PR journals, then advance the cursor. Compact to avoid additionalContext accumulation. Additive and FAIL-OPEN — a missing digest never blocks a prompt.',
+      lifecycle: 'user-prompt-submit',
+      command: `${FORGE_CLI} hooks shepherd-events`,
+    }),
+    Object.freeze({
+      id: 'memory-capture',
+      kind: 'context',
+      cliAction: 'capture',
+      // CAPTURE-ON-EXIT: the write half of Forge memory. SessionStart INJECTS remembered
+      // notes but nothing ever CAPTURES on the way out, so long sessions lose learnings and
+      // memory stays orphaned (the eval scored memory pull-only). PreCompact + Stop fire this
+      // to snapshot a bounded session-summary note BEFORE context is compacted / the session
+      // ends. Persists to the memory store — it NEVER injects into the turn and never drives
+      // the agent (Anthropic Usage Policy). The trigger (precompact|stop) rides as a --trigger
+      // suffix stamped by the rendered hook, so the CLI never has to read hook stdin.
+      enforces: 'Capture-on-exit: snapshot a bounded session-summary note (trigger + in-progress issues) into the memory store on PreCompact and Stop, BEFORE context is compacted or the session ends. Additive and FAIL-OPEN — a capture failure never blocks a session.',
+      lifecycle: 'session-end',
+      command: `${FORGE_CLI} hooks capture`,
+    }),
   ]),
 });
 
@@ -202,6 +258,16 @@ function userPromptSubmitCapability(harness) {
   return USER_PROMPT_SUBMIT_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
 }
 
+/**
+ * Report the per-harness session-END (capture-on-exit) capability (the honest matrix for
+ * the PreCompact + Stop capture tier).
+ * @param {string} harness
+ * @returns {{ rendered: boolean, reason?: string }}
+ */
+function sessionEndCapability(harness) {
+  return SESSION_END_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
+}
+
 /**
  * Render the Claude `.claude/settings.json` `hooks` block (PreToolUse groups only).
  * Write/Edit/MultiEdit/NotebookEdit → protected-path deny; Bash → TDD gate.
@@ -229,8 +295,27 @@ function renderClaudeHooks(contract) {
     // Surfaces pending targeted dashboard instruction comments (fenced kernel DATA) on each
     // prompt; the command emits { hookSpecificOutput.additionalContext }. Reads the user's
     // own kernel data via a supported hook — NEVER stdin injection (Anthropic Usage Policy).
+    // Both UserPromptSubmit context hooks share ONE Forge-owned group (inbox-pickup +
+    // PR-shepherd deltas). Claude runs every hook in the group and appends each hook's
+    // additionalContext; keeping them in one group means a re-merge replaces the pair
+    // atomically (the group is Forge-owned via either marker). Both are compact + fail-open.
     UserPromptSubmit: [
-      { hooks: [{ type: 'command', command: harnessCommand(contract, 'inbox-pickup', 'claude') }] },
+      {
+        hooks: [
+          { type: 'command', command: harnessCommand(contract, 'inbox-pickup', 'claude') },
+          { type: 'command', command: harnessCommand(contract, 'shepherd-events', 'claude') },
+        ],
+      },
+    ],
+    // Capture-on-exit (memory capture). PreCompact fires before context is compacted; Stop
+    // fires when the agent finishes. Both call the same capture command; the event stamps the
+    // --trigger so the CLI never reads hook stdin. The command persists a bounded session
+    // summary — it emits NO stdout (a Stop hook that printed text would inject into the turn).
+    PreCompact: [
+      { hooks: [{ type: 'command', command: `${harnessCommand(contract, 'memory-capture', 'claude')} --trigger precompact` }] },
+    ],
+    Stop: [
+      { hooks: [{ type: 'command', command: `${harnessCommand(contract, 'memory-capture', 'claude')} --trigger stop` }] },
     ],
   };
 }
@@ -311,7 +396,9 @@ function isForgeCommand(command) {
   return typeof command === 'string'
     && (command.includes(FORGE_HOOK_MARKER)
       || command.includes(FORGE_CONTEXT_MARKER)
-      || command.includes(FORGE_INBOX_CONTEXT_MARKER));
+      || command.includes(FORGE_INBOX_CONTEXT_MARKER)
+      || command.includes(FORGE_SHEPHERD_EVENTS_MARKER)
+      || command.includes(FORGE_CAPTURE_CONTEXT_MARKER));
 }
 
 /** True when a hook group/entry is Forge-owned (any inner command is Forge-owned). */
@@ -436,10 +523,13 @@ module.exports = {
   FORGE_HOOK_MARKER,
   FORGE_CONTEXT_MARKER,
   FORGE_INBOX_CONTEXT_MARKER,
+  FORGE_CAPTURE_CONTEXT_MARKER,
   SESSION_START_SUPPORT,
   USER_PROMPT_SUBMIT_SUPPORT,
+  SESSION_END_SUPPORT,
   sessionStartCapability,
   userPromptSubmitCapability,
+  sessionEndCapability,
   HookConfigParseError,
   renderClaudeHooks,
   renderCursorHooks,

package/lib/kernel/backing-issue.js

@@ -171,7 +171,12 @@ function findExistingLink(driver, { worktreePath, branch }) {
     }
     if (typeof driver.listWorktrees === 'function') {
       const rows = driver.listWorktrees() || [];
-      const match = rows.find(row => row && row.branch === branch && row.issue_id);
+      // Match ACTIVE (live) rows only: a superseded/stale registration for a
+      // reused branch name must not be treated as the existing link (be18881c —
+      // the third resolver, kept consistent with resolveActiveIssueId and
+      // currentBranchIssueFromDriver). Tolerate a null state for legacy rows.
+      const match = rows.find(row => row && row.branch === branch && row.issue_id
+        && (row.state === 'active' || row.state == null));
       if (match) return match;
     }
   } catch {
@@ -298,6 +303,7 @@ module.exports = {
   classifyBranch,
   deriveTitle,
   extractEncodedIssueId,
+  findExistingLink,
   matchesIgnoreGlob,
   DEFAULT_PROTECTED_BRANCHES,
   DEFAULT_IGNORE_GLOBS,

package/lib/kernel/owned-kernel.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * @module kernel/owned-kernel
+ *
+ * Shared kernel-lifecycle helper for the pure-append event modules
+ * (grounding/context-events, gate-events). Both resolve a kernel driver the same
+ * way and carry the same close-what-you-built invariant, so it lives here once
+ * instead of being copied per module.
+ *
+ * The invariant: an INJECTED (shared) kernel is caller-owned and must NEVER be
+ * closed here — closing it would break the next operation that reuses it. A
+ * kernel this module BUILDS for a single short-lived read/append it MUST close —
+ * an unclosed SQLite handle leaks and, on Windows, locks the DB directory
+ * (`EBUSY` on `rmSync`, kernel issue e62e4bde).
+ */
+
+const { buildMigratedKernelIssueDeps } = require('./cli-broker-factory');
+
+/**
+ * Resolve the kernel driver + config. An injected (shared) kernel is returned
+ * untouched with `ownsKernel:false` — the caller owns its lifecycle. Otherwise a
+ * fresh one is built (via `deps.kernelBuilder`, a test seam over
+ * `buildMigratedKernelIssueDeps`, or the real builder) and tagged
+ * `ownsKernel:true` so {@link closeIfOwned} closes it.
+ */
+async function resolveOwnedKernel(projectRoot, deps = {}) {
+  if (deps.kernelBroker && deps.kernelDriver) {
+    return { broker: deps.kernelBroker, driver: deps.kernelDriver, config: deps.kernelBroker.config, ownsKernel: false };
+  }
+  const build = deps.kernelBuilder || buildMigratedKernelIssueDeps;
+  const built = await build({ projectRoot });
+  return { broker: built.kernelBroker, driver: built.kernelDriver, config: built.kernelBroker.config, ownsKernel: true };
+}
+
+/** Close a kernel driver only when this module built it (never an injected one). */
+function closeIfOwned(kernel) {
+  if (kernel && kernel.ownsKernel && kernel.driver && typeof kernel.driver.close === 'function') {
+    try { kernel.driver.close(); } catch { /* best-effort: closing is cleanup, never fatal */ }
+  }
+}
+
+module.exports = { resolveOwnedKernel, closeIfOwned };

package/lib/kernel/sqlite-driver.js

@@ -1113,8 +1113,41 @@ function loadWorktreeRowByPath(runtime, db, worktreePath) {
 	return rows[0] || null;
 }
 
+// The idempotent upsert key. `forge plan` registers MULTIPLE branches from ONE
+// checkout (same absolute path), so keying by path ALONE made a second plan-first
+// feature UPDATE-in-place over the first branch's row and dead-end its ship (R1).
+// Key by (path, branch) so each branch keeps its own row; fall back to path-only
+// when no branch is supplied (worktree flows use distinct paths, so behavior there
+// is unchanged).
+function loadWorktreeRowByPathAndBranch(runtime, db, worktreePath, branch) {
+	if (!worktreePath) return null;
+	if (!branch) return loadWorktreeRowByPath(runtime, db, worktreePath);
+	const rows = safeAll(
+		runtime,
+		db,
+		'SELECT * FROM kernel_worktrees WHERE path = ? AND branch = ? ORDER BY registered_at DESC LIMIT 1',
+		[worktreePath, branch],
+	);
+	return rows[0] || null;
+}
+
+// A git branch is checked out in exactly ONE worktree, so a NEW active registration
+// for a branch supersedes any prior ACTIVE row carrying that same branch under a
+// different id (be18881c): a reused/deleted-and-recreated branch must not keep a
+// stale binding to the OLD issue. Marking those rows state='superseded' lets the
+// active-only branch resolver skip them regardless of their timestamp.
+function supersedePriorBranchRegistrations(runtime, db, branch, keepId) {
+	if (!branch) return;
+	runParams(
+		runtime,
+		db,
+		"UPDATE kernel_worktrees SET state = 'superseded' WHERE branch = ? AND state = 'active' AND id != ?",
+		[branch, keepId || ''],
+	);
+}
+
 function upsertWorktreeRow(runtime, db, input) {
-	const existing = loadWorktreeRowByPath(runtime, db, input.path);
+	const existing = loadWorktreeRowByPathAndBranch(runtime, db, input.path, input.branch);
 	const row = {
 		id: input.id || existing?.id || randomUUID(),
 		git_common_dir: input.git_common_dir,
@@ -1142,6 +1175,9 @@ function upsertWorktreeRow(runtime, db, input) {
 			KERNEL_WORKTREE_COLUMNS.map(column => row[column]),
 		);
 	}
+	if (row.state === 'active') {
+		supersedePriorBranchRegistrations(runtime, db, row.branch, row.id);
+	}
 	return row;
 }