@jeffober/thatch 0.2.4 → 0.2.6

package/src/runtime.ts

@@ -1,6 +1,8 @@
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { createDebugLog } from "./debug";
+import { createDebugLog, type DebugLog } from "./debug";
 import { ThatchDB, repoPathCache } from "./db";
+import { chatOpenTabs as chatOpenTabsProvider } from "./tab-state";
 import { SharedModelPool } from "./embeddings";
 import { detectRepo, detectWorktreeKind, resolveSpawnCwd } from "./git";
 import { buildCoreContext } from "./tool-defs";
@@ -25,9 +27,9 @@ import { installOpencodeCommands, opencodeActionCommandDefs, removeWrapUpCommand
 import { hygieneReport } from "./hygiene";
 import { seedDefaultBehaviors } from "./seed-behaviors";
 import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
-import { WatcherRegistry, ghApiRun, ghAvailable, runWatchedCommand, watcherTarget, withCwdFallback, type Watcher } from "./watchers";
+import { WatcherRegistry, ghApiRun, ghAvailable, runWatchedCommand, watcherTarget, withCwdFallback, type Watcher, type WatcherEvent } from "./watchers";
 import { watcherNotificationNudge, watcherRearmNotice, watcherDeathNotice, chatNotificationNudge, chatEchoText, isChatEchoParts } from "./prompts";
-import { ChatPoller, createWakeGate, hostedSessionIds, isDefaultSessionTitle, unexpiredGraceRehosts } from "./chat";
+import { ChatPoller, createWakeGate, EXTRACTION_CHILD_TITLE, hostedSessionIds, isDefaultSessionTitle, isMachinerySessionTitle, nowIso, unexpiredGraceRehosts } from "./chat";
 import { chatEnabled, chatAutoRegister, loadConfig, alertMode, notificationDefaults } from "./config";
 import { sendNotification } from "./notify";
 import { osProcessArgs, startupSessionId, continuesLastSessionFromArgv, continuesLastSessionId } from "./os-args";
@@ -134,12 +136,60 @@ export interface ThatchRuntime {
   dispose(): Promise<void>;
 }
 
+/**
+ * Whether a wake delivery's target directory can host the attempt right
+ * now. existsSync cannot say WHY a path is absent - deleted worktree,
+ * broken symlink, permission on a parent - and none of those states can
+ * host a wake attempt, so one false answer covers the class (deliberate:
+ * the alternative, surfacing non-ENOENT errors through the attempt, buys
+ * a toast back for no recovery the mail does not already get from its
+ * pending-and-retry cycle). Synchronous on purpose: fire-and-forget
+ * callers and test harnesses observe promptSession timing with no added
+ * microtask between the gate and the wrapped call.
+ */
+export function directoryAvailable(path: string): boolean {
+  return existsSync(path);
+}
+
+/**
+ * The delivery guard: wraps the host's promptSession so a wake attempt
+ * never runs against a session whose directory has been deleted. The
+ * attempt itself would error, and opencode surfaces that failure to the
+ * user as a toast. Skipping instead leaves the pending mail queued - the
+ * check runs fresh on every attempt, so a worktree recreated at the same
+ * path (or a session revived in a live directory) resumes delivery with
+ * nothing lost. This covers every wake site at once because chat nudges,
+ * watcher notifications, watcher death notices, rehydrate pings, chat
+ * echoes, and extraction-child dispatch all funnel through promptSession,
+ * and a host instance is bound to its sessions' own directory.
+ */
+export function guardDelivery(
+  promptSession: HostCapabilities["promptSession"],
+  directory: string,
+  debug: DebugLog,
+): HostCapabilities["promptSession"] {
+  return (sessionID, body, mode) => {
+    if (!directoryAvailable(directory)) {
+      debug("runtime:delivery", `skipped wake to ${sessionID}: directory ${directory} no longer exists`);
+      return Promise.resolve();
+    }
+    return promptSession(sessionID, body, mode);
+  };
+}
+
 export async function createRuntime(input: {
   capabilities: HostCapabilities;
   directory: string;
   worktree: string;
+  /**
+   * True on the opencode v2 adapter: the system prompt's Tools list then
+   * includes the v2-only session-tab tool. v1 and MCP hosts omit it - the
+   * tool does not exist there, and a prompt listing a nonexistent tool is
+   * the first-call-mistake class.
+   */
+  v2Tools?: boolean;
 }): Promise<ThatchRuntime> {
-  const { capabilities: caps, directory, worktree } = input;
+  const { capabilities, directory, worktree, v2Tools } = input;
   // The opencode server's cwd is wherever the server happened to start;
   // `worktree` is the project this plugin instance actually serves.
   // `directory` is the session's own directory - on resume after the
@@ -162,7 +212,10 @@ export async function createRuntime(input: {
 
   // The DB must exist before identity detection: detectRepo consults the
   // repo_paths cache when the session directory is gone.
-  const db = new ThatchDB(dbPath);
+  // chatOpenTabs composes the tab-state reader (tabs.json across channels,
+  // minus confirmed closes) lazily per call - never cached - so roster
+  // rendering and broadcast targeting see the current tab state.
+  const db: ThatchDB = new ThatchDB(dbPath, { chatOpenTabs: chatOpenTabsProvider(() => db.chatTabClosures()) });
   const repoCache = repoPathCache(db);
   const repo = await detectRepo(directory ?? worktree, repoCache);
 
@@ -174,6 +227,16 @@ export async function createRuntime(input: {
 
   const debug = createDebugLog(dbPath);
 
+  // The delivery guard wraps the host's promptSession once, so no wake
+  // attempt in this instance runs against a deleted directory (see
+  // guardDelivery). The v2 wrap-up command in opencode/v2.ts calls
+  // capabilities.promptSession directly and deliberately bypasses this
+  // wrapper: it is user-invoked in a live tab, not a wake.
+  const caps: HostCapabilities = {
+    ...capabilities,
+    promptSession: guardDelivery(capabilities.promptSession, directory ?? worktree, debug),
+  };
+
   // Shared embedding model: refcounted per db path (see SharedModelPool).
   const model = sharedModels.acquire(dbPath, modelName);
   const releaseModel = () => sharedModels.release(dbPath);
@@ -221,7 +284,7 @@ export async function createRuntime(input: {
   // process may deliver chat mail to - the map's keys).
   const sessionStatus = new Map<string, string>();
 
-  // LLM alerts (docs/plans/llm-alerts.md): notify when the LLM pauses for
+  // LLM alerts (docs/dev/features/notifications.md): notify when the LLM pauses for
   // human input or finishes a round of real work. Plain in-memory state -
   // a v2 reload mid-turn loses that turn's transition and stays silent
   // (accepted). Delivery reuses the notify_user dispatcher; the alerts
@@ -287,7 +350,56 @@ export async function createRuntime(input: {
     console.error(`[thatch] project directory ${from} deleted; watcher falling back to main checkout ${to}`);
   });
 
+  /** Tells one live same-project session about a dead session's watchers
+   *  (promptAsync, the watcher-notification path) and clears the durable
+   *  death row on success. No live peer = the row waits for the next
+   *  prompt-time surfacing pass. The dead session's project is the one
+   *  captured at death time (onSessionDeath), not a re-read of the chat
+   *  roster: the wrap-up exit unregisters the row between the death record
+   *  and this delivery, and a re-read would strand a placed death as
+   *  unplaceable. */
+  const deliverWatcherDeathNotices = async (
+    deadSessionID: string,
+    death: { chatName: string | null; targets: string[] },
+    deadProject: string | null,
+  ) => {
+    if (death.targets.length === 0) {
+      // A watchless death is nobody's news, and onSessionDeath never
+      // writes a row for one - so there is nothing to deliver or clean
+      // here. Deleting unconditionally would erase an earlier placed row
+      // for the same session (a reopened session's second greenlit
+      // /thatch/exit); the surfacing pass cleans any legacy empty row.
+      return;
+    }
+    if (!deadProject) return; // unplaceable death - the row waits for surfacing
+    for (const peerID of sessionStatus.keys()) {
+      if (peerID === deadSessionID) continue;
+      const peerRow = db.findChatSession(peerID);
+      if (!peerRow || peerRow.project !== deadProject) continue;
+      if (!(await canPromptSession(peerID))) continue;
+      try {
+        await caps.promptSession(
+          peerID,
+          { parts: [{ type: "text", text: watcherDeathNotice(death.targets, { name: death.chatName, sessionID: deadSessionID }, { rearmsOnResume: false }), synthetic: true }] },
+          "async",
+        );
+        // Delayed journal writer (post-await): the reload ownership rule
+        // applies - a disposed runtime's rows belong to the reloaded
+        // instance (docs/dev/gotchas.md).
+        if (disposed) return;
+        db.runtimeStateDelete("watcher_death", deadSessionID);
+        return;
+      } catch (err) {
+        console.error(`[thatch] death-notice delivery to ${peerID} failed: ${err}`);
+      }
+    }
+  };
+
   const watchers = new WatcherRegistry({
+    // Scope the per-process live handoff to THIS location: a worktree
+    // subordinate's instance boots in the same serve process and must not
+    // stop this coordinator's poller (one registry polls per directory).
+    directory,
     // Journal watcher definitions so a v2 plugin reload (same process) can
     // re-arm them; the registry journals after every membership change.
     // Disposed check FIRST: a poll cycle suspended at an await can outlive
@@ -333,6 +445,43 @@ export async function createRuntime(input: {
     canDeliver: canPromptSession,
     ghRunner: ghApiRun,
     commandRunner: watchedCommandRunner,
+    journalPending: (sessionID, pending) => {
+      if (pending === undefined) db.runtimeStateDelete("watcher_pending", sessionID);
+      else db.runtimeStatePut("watcher_pending", sessionID, pending, directory);
+    },
+    isHostedSession: (sessionID) =>
+      hostedSessionIds({
+        statusKeys: sessionStatus.keys(),
+        resumedSessions,
+        rehostedSessions: [...rehostedSessions, ...unexpiredGraceRehosts(rehostGrace, Date.now())],
+        exclude: childToParent.keys(),
+      }).includes(sessionID),
+    onSessionDeath: (deadSessionID, death) => {
+      // The dead tab's chat-hosting state dies with it - the session.deleted
+      // cleanup minus the chat unregister (the session is not deleted, only
+      // its tab: unregistering would tombstone a legitimate resume, and the
+      // roster row ages out through the reaper).
+      sessionStatus.delete(deadSessionID);
+      rehostGrace.delete(deadSessionID);
+      const hostedRow = db.runtimeStateAll().find((r) => r.kind === "hosted" && r.sessionID === directory);
+      if (hostedRow && Array.isArray(hostedRow.value)) {
+        db.runtimeStatePut("hosted", directory, (hostedRow.value as string[]).filter((sid) => sid !== deadSessionID), directory);
+      }
+      // Durable death record first, then best-effort live delivery - the
+      // row is deleted when a live same-project session has the news. The
+      // project is captured HERE (while the chat row still places it): the
+      // wrap-up exit unregisters the row right after recording, so the
+      // project cannot be re-derived at delivery time. A watchless death
+      // writes no row at all: runtimeStatePut upserts, so an empty-targets
+      // write would erase an earlier placed row for the same session (a
+      // reopened session that greenlights /thatch/exit a second time).
+      const deadRow = db.findChatSession(deadSessionID);
+      const deadProject = deadRow?.project ?? null;
+      if (death.targets.length > 0) {
+        db.runtimeStatePut("watcher_death", deadSessionID, { name: death.chatName, targets: death.targets, project: deadProject, at: nowIso() }, directory);
+      }
+      void deliverWatcherDeathNotices(deadSessionID, death, deadProject);
+    },
   });
   // gh presence decides whether watch_create and watch_branch_create work;
   // checked lazily by the tools, but log once at startup so misconfiguration
@@ -638,6 +787,13 @@ export async function createRuntime(input: {
         }
         continue;
       }
+      if (row.kind === "watcher_pending" || row.kind === "watcher_death") {
+        // Durable pending events and death records survive restarts: the
+        // pending queue rides a resumed session's rearm, the death record
+        // surfaces at a live session's next prompt. Both are deleted on
+        // consumption.
+        continue;
+      }
       db.runtimeStateDelete(row.kind, row.sessionID);
       continue;
     }
@@ -705,6 +861,28 @@ export async function createRuntime(input: {
         continue;
       }
       pendingWrapUp.set(row.sessionID, row.value as { token: string; kind: "compact" | "exit" });
+    } else if (row.kind === "watcher_pending") {
+      // Journaled pending watcher events (the reload-loss fix). On a
+      // same-process reload the plugin re-ran in place and its sessions are
+      // still live, so hand the events straight back to the rehydrated
+      // registry - before this branch they fell into "unknown kind" and
+      // notifications queued while a session was busy were stranded until a
+      // full process restart. The startup-resume case rides along: the
+      // registry rehydrated this session's watcher definitions above, and
+      // its queued events belong with them. hydratePending re-journals the
+      // queue, so the events stay durable until delivery even across
+      // repeated reloads. (Foreign-pid non-startup rows took the dormant
+      // path above; scanDormantWatchers hydrates those at the resumed
+      // session's first message.)
+      db.runtimeStateDelete("watcher_pending", row.sessionID);
+      if (Array.isArray(row.value) && row.value.length > 0) {
+        watchers.hydratePending(row.sessionID, row.value as { event: WatcherEvent; queuedAt: number }[]);
+      }
+    } else if (row.kind === "watcher_death") {
+      // Death records are surfaced at the live session's next prompt
+      // (surfaceWatcherDeaths), not through registry hydration - leave the
+      // row for that consumption to delete.
+      continue;
     } else {
       continue; // unknown kind - leave it for a future version
     }
@@ -776,6 +954,34 @@ export async function createRuntime(input: {
       return (err as NodeJS.ErrnoException).code !== "ESRCH";
     }
   };
+  /** Surfaces persisted watcher-death rows to this session (same project
+   *  only), deleting each row on surfacing. Runs per prompt - deaths are
+   *  rare and the row read is cheap - so the once-per-process
+   *  dormantScanned guard deliberately does NOT apply: a death row
+   *  persisted after this session's first prompt must still surface. */
+  const surfaceWatcherDeaths = (forSessionID: string): string[] => {
+    const ownRow = db.findChatSession(forSessionID);
+    const project = ownRow?.project ?? null;
+    if (!project) return [];
+    const notices: string[] = [];
+    for (const row of db.runtimeStateAll()) {
+      if (row.kind !== "watcher_death" || row.directory !== directory) continue;
+      const death = (row.value ?? {}) as { name?: string | null; targets?: string[]; project?: string | null };
+      if (!Array.isArray(death.targets) || death.targets.length === 0) {
+        // Malformed or fully-consumed row - clean it up.
+        db.runtimeStateDelete("watcher_death", row.sessionID);
+        continue;
+      }
+      // Only the dead session's own project hears the death. The "global"
+      // project matches globally - the same accepted class as the identity
+      // binding's unknown-to-global mapping.
+      if ((death.project ?? "global") !== project) continue;
+      notices.push(watcherDeathNotice(death.targets, { name: death.name ?? null, sessionID: row.sessionID }, { rearmsOnResume: false }));
+      db.runtimeStateDelete("watcher_death", row.sessionID);
+    }
+    return notices;
+  };
+
   const scanDormantWatchers = async (sessionID: string): Promise<string[]> => {
     if (dormantScanned.has(sessionID)) return [];
     dormantScanned.add(sessionID);
@@ -807,6 +1013,17 @@ export async function createRuntime(input: {
       const notices: string[] = [];
       if (own.length > 0) {
         const { rearmed, expired, failed } = await watchers.rearm(sessionID, own);
+        // Durable pending events ride along: the reload-loss fix journals
+        // the pending queue separately from the definitions, and a resumed
+        // session's undelivered notifications must still deliver.
+        const pendingRow = db.runtimeStateAll().find((r) => r.kind === "watcher_pending" && r.sessionID === sessionID);
+        if (pendingRow && Array.isArray(pendingRow.value) && pendingRow.value.length > 0) {
+          // Delete-then-hydrate: hydratePending re-journals the queue, so
+          // the events are durable again until delivery even across a
+          // second reload (hydrating without the re-journal lost them).
+          db.runtimeStateDelete("watcher_pending", sessionID);
+          watchers.hydratePending(sessionID, pendingRow.value as { event: WatcherEvent; queuedAt: number }[]);
+        }
         // This session came back to life: its own previous death notice is
         // obsolete - a future death deserves a fresh one.
         notifiedWatcherDeaths.delete(sessionID);
@@ -954,7 +1171,7 @@ export async function createRuntime(input: {
     console.error(`[thatch] command install failed: ${err}`);
   }
 
-  const sys = systemPrompt(repo, chatOn);
+  const sys = systemPrompt(repo, chatOn, v2Tools);
   const compact = compactionContext(repo);
 
   // Direct extraction: create a child session linked to the parent and prompt
@@ -982,13 +1199,22 @@ export async function createRuntime(input: {
 
     const result = await caps.sessionCreate({
       parentID,
-      title: "thatch-extraction",
+      title: EXTRACTION_CHILD_TITLE,
     });
     // session.created event fires here, setting childToParent and
     // parentSnapshots (snapshot of the full pending buffer, since we
     // have not called accept).
     const childId = result.id;
     extractionChildren.add(childId);
+    // Durable machinery marker: the in-memory maps below are lost to a
+    // plugin reload or daemon restart, and without a durable signal the
+    // chat auto-registration paths would register the child as a chat
+    // participant the moment its events land in an instance that lost the
+    // mapping (the thatch-extraction corpse rows, 81 by 2026-10-07). The
+    // marker is never removed on child cleanup - ids are never reused, so
+    // it can only ever refer to this machinery session, and it ages out
+    // with the auto-row TTL.
+    db.markChatMachinery(childId, "extraction");
     // v2's session API cannot create a CHILD session (no parentID in its
     // create input), so the adapter returns a top-level session and no
     // session.created event carries the parent mapping. Set both here
@@ -1133,6 +1359,7 @@ export async function createRuntime(input: {
 
   return {
     coreContext: buildCoreContext(db, model, repo, {
+      openTabs: chatOpenTabsProvider(() => db.chatTabClosures()),
       extractionPayloadProvider: (targetID: string, fetcherID?: string): string | null => {
         // A fetcher identity turns the fetch into the delivery record: the
         // claimed entries stay accepted, and THAT fetcher's completion
@@ -1377,8 +1604,12 @@ export async function createRuntime(input: {
       // nudges take, so the model sees them on every call of the turn -
       // plus a best-effort toast for the human.
       const rearmNotices = !childToParent.has(input.sessionID) ? await scanDormantWatchers(input.sessionID) : [];
-      if (rearmNotices.length > 0) {
-        for (const text of rearmNotices) {
+      // Death records surface per prompt, not once-per-process: a death
+      // row persisted after this session's first prompt must still reach
+      // it.
+      const deathNotices = surfaceWatcherDeaths(input.sessionID);
+      if (rearmNotices.length + deathNotices.length > 0) {
+        for (const text of [...rearmNotices, ...deathNotices]) {
           output.parts.push({
             id: `prt_thatch_watch_${Math.random().toString(36).slice(2)}`,
             sessionID: input.sessionID,
@@ -1409,6 +1640,7 @@ export async function createRuntime(input: {
         chatAutoRegister(loadConfig(dbPath).config) &&
         input.sessionID &&
         !childToParent.has(input.sessionID) &&
+        !db.isChatMachinery(input.sessionID) &&
         !db.hasChatLeaveTombstone(input.sessionID)
       ) {
         try {
@@ -1695,6 +1927,23 @@ export async function createRuntime(input: {
         }
         return;
       }
+      if (event.type === "session.tab_closed") {
+        // The session-tab tool's TUI plugin confirmed a tab close (tool-
+        // initiated only). CONFIRMED death: skip the delivery-persistence
+        // heuristic entirely and run the death path now.
+        const props = event.properties as { sessionID?: string; chatName?: string | null };
+        if (props.sessionID) {
+          // Roster demotion record: a confirmed close lets every reader
+          // (roster render, broadcast targeting) distrust a residue tab
+          // row for this session instantly, instead of waiting for
+          // tabs.json to agree or the heartbeat to age out. Self-expiring
+          // (CHAT_TAB_CLOSED_OVERRIDE_MS) and superseded by any later
+          // heartbeat, so a session that regains a tab reads OPEN again.
+          db.runtimeStatePut("chat_tab_closed", props.sessionID, { at: nowIso() }, directory);
+          watchers.sessionDied(props.sessionID, { chatName: props.chatName ?? null });
+        }
+        return;
+      }
       if (event.type === "session.status") {
         const sessionID = event.properties.sessionID;
         const statusType = event.properties.status?.type;
@@ -1736,6 +1985,13 @@ export async function createRuntime(input: {
         const wrapUp = sessionID ? pendingWrapUp.get(sessionID) : undefined;
         if (wrapUp) {
           pendingWrapUp.delete(sessionID);
+          // Reload ownership rule (docs/dev/gotchas.md): after a v2 plugin
+          // reload this instance's journal rows belong to the reloaded
+          // instance - resolve nothing further once disposed. Safe today
+          // because the only producer of this branch (the v2 pump) is
+          // settled before dispose, but the guard makes that invariant
+          // local instead of transitive.
+          if (disposed) return;
           db.runtimeStateDelete("wrapup", sessionID);
           let ready = false;
           try {
@@ -1751,13 +2007,24 @@ export async function createRuntime(input: {
             console.error(`[thatch] wrap-up message fetch failed: ${err}`);
           }
           if (ready) {
-            // An exit-greenlit session is leaving the process: leave the
-            // chat directory too, so other sessions stop addressing mail to
-            // a roster entry whose host is about to vanish. The unregister
+            // An exit-greenlit session is closing out: leave the chat
+            // directory too, so other sessions stop addressing mail to a
+            // roster entry whose host is about to vanish. The unregister
             // tombstone also stops any straggler auto-register from
             // resurrecting the row during shutdown. Compact keeps the
             // session alive, so only the exit path does this.
             if (wrapUp.kind === "exit") {
+              // Watcher deaths run BEFORE the unregister: onSessionDeath
+              // places the death row by the session's chat row, and the
+              // unregister deletes that row. The v2 exit action's emit is
+              // TUI-only (the pump never translates it into a second
+              // death pass, which would erase the placed row), so this is
+              // the exit's only death recording.
+              try {
+                watchers.sessionDied(sessionID, { chatName: db.findChatSession(sessionID)?.name ?? null });
+              } catch (err) {
+                console.error(`[thatch] watcher death recording on exit failed: ${err}`);
+              }
               try {
                 db.unregisterChatSession(sessionID);
               } catch (err) {
@@ -1768,7 +2035,7 @@ export async function createRuntime(input: {
               if (wrapUp.kind === "compact") {
                 await caps.compactSession(sessionID);
               } else {
-                await caps.exitHost();
+                await caps.exitHost(sessionID);
               }
             } catch (err) {
               console.error(`[thatch] wrap-up action failed: ${err}`);
@@ -1804,7 +2071,10 @@ export async function createRuntime(input: {
         // task sub-agents) are machinery, not chat participants - without
         // this check every fact-extractor run registered a roster row
         // (the "thatch-extraction" corpse flood, September 2026). The
-        // prompt-register path above has the same check.
+        // prompt-register path above has the same check. The childToParent
+        // map alone is not enough: it is in-memory and lost to a plugin
+        // reload or daemon restart, so the IIFE below also checks the
+        // durable chat_machinery marker and the fetched title.
         if (
           chatOn &&
           chatAutoRegister(loadConfig(dbPath).config) &&
@@ -1814,10 +2084,23 @@ export async function createRuntime(input: {
         ) {
           void (async () => {
             try {
+              // Machinery marker check first: a plugin-created extraction
+              // child whose in-memory mapping was lost (reload/restart
+              // window) must not register - and a corpse row an earlier
+              // race did register is deleted here (self-healing).
+              if (db.isChatMachinery(sessionID)) {
+                db.unregisterChatSession(sessionID);
+                return;
+              }
               const data = await caps.sessionGet(sessionID);
               const title = data?.title ?? "";
               // Placeholder titles never become topics (the real one
               // converges on a later idle via refreshChatTopic).
+              // Machinery titles (the extraction child) never register at
+              // all - the durable marker above is the primary guard; this
+              // title check covers a marked session whose marker aged out
+              // or was never written.
+              if (isMachinerySessionTitle(title)) return;
               const topic = title && !isDefaultSessionTitle(title) ? title : null;
               const res = db.registerChatSession(sessionID, repo, topic, "opencode", null, detectWorktreeKind(worktree));
               // The topic converges as the auto-titler lands a real title:

package/src/scoring-engine.ts

@@ -288,13 +288,29 @@ export class ScoringEngine {
 
   createEdge(matcherId: string, itemId: string, weight: number): void {
     const now = new Date().toISOString();
-    const { edgesTable, itemForeignKey } = this.#cfg;
-    this.#db.run(
-      `INSERT INTO ${edgesTable} (matcher_id, ${itemForeignKey}, weight, created_at)
-       VALUES (?, ?, ?, ?)
-       ON CONFLICT(matcher_id, ${itemForeignKey}) DO NOTHING`,
-      [matcherId, itemId, weight, now] as any,
-    );
+    const { edgesTable, itemForeignKey, matchersTable } = this.#cfg;
+    // Insert and bump run atomically: an edge that landed without its
+    // updated_at bump would read as older than it is. bun:sqlite nests
+    // transaction functions via savepoints, so this composes with a
+    // caller's outer transaction (prediction_update's, for one).
+    // Bump only when the insert landed - a re-link to an existing edge
+    // changes nothing.
+    // A matcher's updated_at means "last change to the matcher row or its
+    // edge set" (not "matcher text written"): re-linking a matcher to a
+    // corrected item is graph activity the planned staleness audit must
+    // see. No reader consumes matcher updated_at yet; the bump keeps the
+    // timestamp truthful for when that audit lands.
+    this.#db.transaction(() => {
+      const result = this.#db.run(
+        `INSERT INTO ${edgesTable} (matcher_id, ${itemForeignKey}, weight, created_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(matcher_id, ${itemForeignKey}) DO NOTHING`,
+        [matcherId, itemId, weight, now] as any,
+      );
+      if (result.changes > 0) {
+        this.#db.run(`UPDATE ${matchersTable} SET updated_at = ? WHERE id = ?`, [now, matcherId] as any);
+      }
+    })();
   }
 
   adjustConfidence(itemId: string, signal: "confirm" | "disconfirm" | "soft"): void {
@@ -349,8 +365,23 @@ export class ScoringEngine {
   }
 
   deleteItem(itemId: string): boolean {
-    const result = this.#db.run(`DELETE FROM ${this.#cfg.itemsTable} WHERE id = ?`, [itemId]);
-    return result.changes > 0;
+    const { itemsTable, edgesTable, itemForeignKey, matchersTable } = this.#cfg;
+    // Bump the matchers whose edges are about to cascade away with the
+    // item (edge rows have ON DELETE CASCADE, so the DELETE below removes
+    // them implicitly). Same updated_at meaning as createEdge: last change
+    // to the matcher row or its edge set. Bump and delete run atomically
+    // (bun:sqlite nests via savepoints): a bump whose delete then failed
+    // would record graph activity that never happened.
+    return this.#db.transaction(() => {
+      const now = new Date().toISOString();
+      this.#db.run(
+        `UPDATE ${matchersTable} SET updated_at = ?
+         WHERE id IN (SELECT matcher_id FROM ${edgesTable} WHERE ${itemForeignKey} = ?)`,
+        [now, itemId] as any,
+      );
+      const result = this.#db.run(`DELETE FROM ${itemsTable} WHERE id = ?`, [itemId]);
+      return result.changes > 0;
+    })();
   }
 
   listItems(store: string): {

package/src/session-db.ts

@@ -77,7 +77,7 @@ export function mostRecentTopLevelSessionId(directory: string): string | null {
       .query(
         "SELECT id FROM session WHERE directory = ? AND (parent_id IS NULL OR parent_id = '') ORDER BY time_updated DESC LIMIT 1",
       )
-      .get(directory) as { id: string } | undefined;
+      .get(directory) as { id: string } | null;
     return row?.id ?? null;
   } catch {
     return null;
@@ -152,7 +152,7 @@ export class SessionDB {
       )
       .get(sessionID) as
       | { id: string; title: string; directory: string; agent: string | null; model: string | null; time_created: number; time_updated: number }
-      | undefined;
+      | null;
     if (!row) return null;
     return {
       id: row.id,
@@ -221,7 +221,7 @@ export class SessionDB {
       )
       .get(partID) as
       | { part_id: string; message_id: string; session_id: string; time_created: number; part_data: string; message_data: string }
-      | undefined;
+      | null;
     if (!row) return null;
     const partData = JSON.parse(row.part_data) as Record<string, unknown>;
     const messageData = JSON.parse(row.message_data) as Record<string, unknown>;
@@ -240,7 +240,7 @@ export class SessionDB {
   getMessage(messageID: string): { messageId: string; sessionId: string; timeCreated: number; role: MessageRole; data: Record<string, unknown>; parts: SessionPart[] } | null {
     const row = this.#db
       .query("SELECT id, session_id, time_created, data FROM message WHERE id = ?")
-      .get(messageID) as { id: string; session_id: string; time_created: number; data: string } | undefined;
+      .get(messageID) as { id: string; session_id: string; time_created: number; data: string } | null;
     if (!row) return null;
     const decoded = JSON.parse(row.data) as Record<string, unknown>;
     const parts = this.listParts(row.session_id).filter((p) => p.messageId === messageID);