@jeffober/thatch 0.2.7 → 0.2.8

package/docs/dev/features/cli.md

@@ -102,6 +102,8 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 | `THATCH_PREDICTION_THRESHOLD` | Cutoff for prediction auto-fire | `0.60` |
 | `THATCH_BEHAVIOR_THRESHOLD` | Cutoff for behavior auto-fire | `0.60` |
 | `THATCH_CHILD_RECONCILE_MS` | Reload window before a restored extraction child is judged finished (test knob) | `10000` |
+| `THATCH_STRAND_SWEEP_MS` | Interval for the stranded-session self-heal sweep | `21600000` (6h) |
+| `THATCH_STRAND_SWEEP` | Set to `off` (or `0`/`false`) to disarm the strand sweep (test knob) | falls through (sweep on) |
 | `CLAUDE_PROJECT_DIR` | Claude Code project dir | `process.cwd()` |
 | `CURSOR_PROJECT_DIR` | Cursor project dir | falls through |
 | `THATCH_WATCH_DEATH_MINUTES` | Pending-age threshold for watcher death detection | `120` |

package/docs/dev/features/cross-session-chat.md

@@ -429,7 +429,7 @@ last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages via `chatTailBacklog()`;
 `filterChatTailRows()` narrows every feed snapshot (backlog and follow
 polls alike) by body regexes, participant-name substrings, and a
 half-open time window. The diff itself is `chatTailDiff()` (unit-tested
-in `tests/chat.test.ts`): sent events on first view, then new sends and
+in `tests/chat-tail.test.ts`): sent events on first view, then new sends and
 newly-read messages per poll, with the diff state seeded from the full
 feed so neither the limit nor a mid-follow rename/unregister can
 resurface old rows as sent events. `chat_messages.via_broadcast` marks
@@ -589,8 +589,11 @@ within their clamps - invalid values silently fall back to the default.
 - `src/prompts.ts` - `chatNotificationNudge()`, `chatEchoText()` /
   `isChatEchoParts()`, system prompt Cross-Session Chat section, MCP
   absent-tools note
-- `tests/chat.test.ts` - store, pool, migration, echo-text, liveness, tail
-  diff/backlog, and poller unit tests (temp-dir SQLite, injected delivery)
+- `tests/chat-store.test.ts`, `tests/chat-poller.test.ts`,
+  `tests/chat-tail.test.ts`, `tests/chat-echo.test.ts` - store, pool,
+  migration, echo-text, liveness, tail diff/backlog, and poller unit tests
+  (temp-dir SQLite, injected delivery; shared fixtures in
+  `tests/mocks/chat-harness.ts`)
 - `tests/qa/auto/uc-097-chat.ts` - full lifecycle against a mocked poller
 - `tests/qa/auto/uc-099-chat-cli.ts` - `chat list` roster and `chat tail`
   JSONL contract over a seeded DB

package/docs/dev/features/notifications.md

@@ -203,7 +203,7 @@ rejected for that reason (plus v1 has no TUI plugin surface at all).
   records argv), AppleScript escaping, partial vs total failure, unsupported
   platform, plus tool-level tests (merge-no-wipe, echo, `mode: none` no-op,
   configured voice honored) with `THATCH_DB_PATH` pointed at a tempdir.
-- `tests/tool-defs.test.ts` -- registry count and name list (hardcoded literals that fail loudly when the surface changes).
+- `tests/tool-defs-catalog-session.test.ts` -- registry count and name list (hardcoded literals that fail loudly when the surface changes).
 - `tests/alerts.test.ts` -- the alert state machine: `deriveRoundShape`
   (idle-marker delimiter, v1 fallback, synthetic trigger detection), the
   real-work flag, pause dedup and re-arm, abort/shutdown silence,

package/docs/dev/features/opencode-plugin.md

@@ -66,17 +66,19 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
 | tool buffering | `tool.execute.after` hook | `tool.hook("execute.after")` | wired: feeds the same extraction buffer; `Tool.Result.content` is flattened (string passes through, content-part arrays contribute their text parts); the title is derived from the tool name and args (`deriveTitle`), since v2's `Tool.Result.output` is a typed output value, not a title |
 | noReply deliveries | `promptAsync` with `noReply` | none | gated off via `HostCapabilities.noReplyDelivery` -- chat echoes and the session-start reminder are skipped on v2 (delivering them would start real model turns: a feedback loop) |
 | synthetic wake deliveries | `promptAsync` with `synthetic` parts | `session.synthetic` endpoint | watcher + chat wake nudges route to v2's synthetic endpoint (TUI-hidden), matching v1 |
-| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete rides `session.remove` (upstream #52387, in v2.0.22), runtime-guarded like compact -- an older host keeps the documented gap (the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction) |
+| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete rides `session.remove` (upstream #52387, in v2.0.22), runtime-guarded like compact -- an older host keeps the documented gap (the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction); the strand sweep deletes such corpses opportunistically and moves stranded real sessions to their project's canonical checkout (see session-lifecycle.md) |
 | session status | `client.session.status` | none | returns `{}`; the wake gate treats unknown as idle and the event-fed status map does the gating |
 | session messages | `client.session.messages` | `session.context` | mapped into the v1 `{info: {role}, parts}` shape, so the wrap-up greenlight check works (the promise domain has no `message` accessor) |
 | session list | `client.session.list` | none | degrade (`-c` resume listing loses its data source) |
+| session enumeration (strand sweep) | `client.session.list` | readonly read of opencode.db | v2's promise domain has no session list, and the sweep needs machine-wide rows (dead-worktree sessions belong to no live instance), so the v2 adapter reads `session_v2` + `project` directly -- the same readonly pattern as the `-c` inheritance resolution; null on schema drift, which the sweep treats as "nothing known, do nothing" |
+| session move | none | `session.move` (promise domain) | the strand sweep's self-heal for real sessions stranded in a deleted worktree; v1 has no move endpoint, so the adapter omits it and the sweep degrades to machinery-only deletion |
 | compaction trigger | `client.tui.executeCommand("session_compact")` | `session.compact({sessionID})` | wired behind a runtime guard: upstream [#52385](https://github.com/anomalyco/opencode/pull/52385) exposed `session.compact` on the promise domain (in the installed v2.0.25), newer than the pinned dev types - an older host degrades to a logged no-op (the wrap-up checklist and flush still run, the automatic compaction is skipped) |
 | toasts | `client.tui.showToast` | toast rpc event | wired: every runtime toast call site (alerts, extraction metrics, chat registration, blocked wrap-ups, watcher rearm notices) emits the bridge's `toast` event, which the `./tui` plugin shows via `ui.toast.show`; the pump never translates it (TUI-only by nature). Best-effort by contract: a TUI-less environment or an rpc-less SDK floor shows nothing, silently |
 | wrap-up exit | `client.tui.publish` | exit-tab-closed rpc event | the wrap-up exit records the session's watcher deaths synchronously (the runtime, before the chat unregister - `sessionDied` places the death row by the chat row, so the order is load-bearing) and then emits `rpc.thatch-tabs.exit-tab-closed`, a TUI-ONLY close of the session's OWN tab (the `./tui` plugin's `ui.tabs.close`): the tab-scoped semantic upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984) asks for, since the daemon hosts every tab and `app.exit` would take down unrelated sessions. The pump deliberately never translates this event (a second death pass would erase the durable death row the first one wrote; the session_tab_close tool's `tab-closed` is the only death-translating event). Degrades to a logged no-op without the rpc surface; a TUI with no tab for the session (headless run, tabs off) never acts - the event is ephemeral |
 | session tabs | n/a | rpc event bridge | `thatch_session_tab` (v2Only) spawns a detached subordinate session (create -> move -> chat-register -> emit `rpc.thatch-tabs.tab-opened` -> prompt); the `./tui` CLI plugin consumes the event and calls `ui.tabs.open` (open-without-focus, idempotent). `thatch_session_tab_close` emits `rpc.thatch-tabs.tab-closed {sessionID, chatName}` - the pump translates it into the runtime's confirmed-death path. The registration's third event, `exit-tab-closed` (the wrap-up exit's), is TUI-only - see the wrap-up exit row |
 | tab close | n/a | no session.deleted on v2 tab close | bounded 2026-10-07: watcher death detection cancels a closed tab's watchers once its pending events age past `THATCH_WATCH_DEATH_MINUTES` (default 120) while deliveries throw 404-class errors, and announces the death to live same-project sessions; the roster row itself still lingers until the reaper. NOTE: an earlier version of this row claimed deliveries "fail their idle gate" - wrong: the v2 gate opens (the status stub reads as idle) and the PROMPT fails; same leak, different link |
 | wake gate after reload | `session.status` event map | map rehydrates empty | known gap: v2's fetchStatuses stub is structural (the promise context has no session.status), so in the reload window - until the session's next status event - the proactive-prompt gate is fully open |
-| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; child rows carry a kind marker (extraction vs task-dispatched sub-agent, defaulting to extraction for pre-marker rows) so only extraction children restore the `extracting`/`extractionChildren` sets; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
+| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; child rows carry a kind marker (extraction vs task-dispatched sub-agent, defaulting to extraction for pre-marker rows) so only extraction children restore the `extracting`/`extractionChildren` sets; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process); a dead process's journaled extraction children are also DELETED through the host before the prune (the opencode session row is global and would otherwise outlive the journal as a picker corpse - the restart-window leak). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
 
 ## Live verification and remaining unknowns
 
@@ -160,9 +162,9 @@ self-heal it).
 - `src/capabilities.ts` -- `HostCapabilities`, `capabilitiesFromClient`
 - `src/runtime.ts` -- the shared runtime (all behavioral logic)
 - `src/os-args.ts` -- pure argv helpers
-- `tests/opencode-v2.test.ts` -- v2 adapter contract tests (mocked context)
+- `tests/opencode-v2-*.test.ts` -- v2 adapter contract tests (mocked context; shared fixtures in `tests/mocks/opencode-v2-harness.ts`)
 - `tests/session-tab-shared.test.ts` -- session-tab validators, rpc definition shape, TUI guard logic
-- `tests/plugin.test.ts` -- v1 adapter contract tests (mocked client)
+- `tests/plugin-*.test.ts` -- v1 adapter contract tests (mocked client; shared fixtures in `tests/mocks/plugin-harness.ts`)
 
 ## Interactions with other features
 

package/docs/dev/features/session-lifecycle.md

@@ -13,6 +13,7 @@ opencode emits bus events for session lifecycle changes. Thatch subscribes to th
 - Sub-agent lifecycle: task-dispatched sub-agents complete accepted entries but are not deleted
 - Session error recovery: child errors requeue parent's accepted entries
 - Session deletion recovery: child deletion requeues; parent deletion completes accepted entries
+- Stranded-session self-heal: sessions whose recorded directory is gone (a merged + deleted worktree) are deleted when machinery (`thatch-extraction` corpses) and moved to the project's canonical checkout when real
 - Wrap-up commands: `/thatch/compact` and `/thatch/exit` arm a greenlight check resolved on the next idle
 
 ## How it works
@@ -118,6 +119,40 @@ first-ever install is invisible until the next server start.
 - Clear the `compacting` flag so chat.message nudges resume
 - See [compaction-recovery.md](compaction-recovery.md)
 
+### Stranded-session self-heal sweep
+
+Why it exists: opencode v2 records a directory on every session row, and
+opening a session whose directory is gone (a merged + deleted worktree) boots
+a dead path and shows the "session location unavailable" recovery dialog.
+Sessions get stranded there in two ways: extraction children leaked by hosts
+older than v2.0.22 (whose session domain had no `remove`, so cleanup was a
+silent no-op) and children whose idle event died with a daemon restart. The
+sweep runs at setup and on an interval (`THATCH_STRAND_SWEEP_MS`), and the
+rehydrate pass finalizes journaled extraction children through the host
+before pruning their rows, so both the corpse population and the leak paths
+are covered.
+
+What it does, decided by `planStrandActions` (pure, unit-tested):
+
+- Sessions in a live directory are never touched, whatever the row looks like
+- Machinery (`thatch-extraction` title) in a dead directory: delete via the
+  host's session delete
+- Real top-level sessions in a dead directory: MOVE to the project's
+  canonical checkout (`project.worktree` in opencode.db) -- the same outcome
+  as the manual recovery dialog, minus the picking; history is preserved and
+  user sessions are never deleted
+- Host-created task children (parentId set): always skipped -- they are
+  opencode's own records of subagent work and deleting them would break the
+  parent transcript's subagent rendering
+- Unresolvable canonical or no move endpoint: skipped and logged
+
+The host supplies the enumeration (v1: `client.session.list`; v2: readonly
+read of opencode.db, since the promise domain has no session list and the
+sweep needs machine-wide rows) plus the move/delete endpoints; every leg
+degrades silently. A summary toast fires only when something was healed. Set
+`THATCH_STRAND_SWEEP=off` to disarm the sweep entirely (tests do, so it can
+never act on a developer's real database through mocks).
+
 ### Internal state maps
 
 - **childToParent**: `Map<childID, parentID>` -- maps child sessions to their parents

package/docs/dev/features/session-tabs.md

@@ -147,8 +147,9 @@ dependency for the TUI entry's runtime resolution.
 ## Testing
 
 - Unit: `tests/session-tab-shared.test.ts` (validators, definition shape,
-  guard logic), `tests/opencode-v2.test.ts` (the execute flows' ordering via
-  the `makeContext` double with `session.move` + the `rpc` domain).
+  guard logic), `tests/opencode-v2-adapter-tabs.test.ts` (the execute flows'
+  ordering via the `makeContext` double with `session.move` + the `rpc`
+  domain).
 - QA: uc-059 (tool list + MCP leak check), uc-014/uc-060 (skill counts),
   uc-119 (the live spawn flow through the docker sandbox).
 - Live smoke (recorded 2026-10-08, ALL SCENARIOS PASSED): headless legs -

package/docs/dev/features/watchers.md

@@ -291,9 +291,11 @@ src/watchers.ts, test-enforced).
   session.status tracking, session.deleted cleanup, dispose
 - `src/prompts.ts` - `watcherNotificationNudge()`, system prompt
   Watchers section
-- `tests/watchers.test.ts` - registry, poll, and diff unit tests
+- `tests/watchers-registry.test.ts` - registry, poll, and death-detection unit tests
+- `tests/watchers-git-state.test.ts` - PR/branch diff and check-run description unit tests
+- `tests/watchers-commands.test.ts` - command watcher and poll-resilience unit tests
   (mocked gh and command runners, no network)
-- `tests/tool-defs.test.ts` - watch tool execute-function tests
+- `tests/tool-defs-watch-chat.test.ts` - watch tool execute-function tests
 - `tests/qa/auto/uc-095-watchers.ts` - end-to-end lifecycle against a
   mocked gh runner
 - `tests/qa/auto/uc-101-command-watchers.ts` - command-watch lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/capabilities.ts

@@ -77,6 +77,28 @@ export interface HostCapabilities {
   sessionGet(id: string): Promise<{ title?: string } | null>;
   /** List sessions in this directory. Null when unavailable (v2 degrade). */
   sessionList(): Promise<{ id: string; parentID?: string; time?: { updated?: number } }[] | null>;
+  /**
+   * Enumerate every session the host knows (id, title, directory, parent
+   * link, project link) plus each project's canonical checkout directory,
+   * for the runtime's stranded-session sweep. v1 maps client.session.list();
+   * v2 reads opencode.db readonly (its promise domain has no session list
+   * and the sweep needs machine-wide rows, not per-directory ones). Null
+   * when the host has no enumeration surface or the read fails - the sweep
+   * treats null as "nothing known, do nothing".
+   */
+  enumerateSessions(): Promise<{
+    sessions: { id: string; title: string; directory: string; parentId: string | null; projectId: string | null }[];
+    canonicalByProject: Record<string, string>;
+  } | null>;
+  /**
+   * Move a session to another directory. The strand sweep's self-heal for
+   * real sessions stranded in a deleted worktree (deletion is reserved for
+   * machinery sessions); moving is exactly what opencode's own
+   * "session location unavailable" recovery dialog does, minus the
+   * directory picking. Optional: the v1 SDK has no move endpoint, so the
+   * v1 adapter omits it and the sweep degrades to machinery-only deletion.
+   */
+  sessionMove?(id: string, directory: string): Promise<void>;
   /**
    * Fetch a session's message list (wrap-up greenlight check, alert round
    * classification). Null when unavailable. v2 reads them via
@@ -148,6 +170,20 @@ export function capabilitiesFromClient(client: PluginInput["client"]): HostCapab
       const { data } = await client.session.list();
       return data ?? null;
     },
+    enumerateSessions: async () => {
+      const { data } = await client.session.list();
+      if (!data) return null;
+      return {
+        sessions: data.map((s) => ({
+          id: s.id,
+          title: s.title ?? "",
+          directory: (s as { directory?: string }).directory ?? "",
+          parentId: (s as { parentID?: string }).parentID ?? null,
+          projectId: null,
+        })),
+        canonicalByProject: {},
+      };
+    },
     sessionMessages: async (id) => {
       const { data } = await client.session.messages({ path: { id } });
       // Map the message-level error (if any) to its name - the alert

package/src/opencode/v2.ts

@@ -5,6 +5,7 @@ import type { ToolContext as V2ToolContext } from "@opencode/plugin/promise/tool
 import type { ThatchDB } from "../db";
 import type { HostCapabilities, PromptPart, ToastInput } from "../capabilities";
 import { createRuntime } from "../runtime";
+import { enumerateSweepSessions } from "../session-db";
 import { wrapUpCommandContent, wrapUpCommandDescription } from "../commands";
 import { deriveTitle } from "../extraction";
 import { detectRepo, detectWorktreeKind } from "../git";
@@ -929,6 +930,20 @@ function buildCapabilities(
       return (await session.get({ sessionID: id })) ?? null;
     },
     sessionList: async () => null,
+    enumerateSessions: async () => {
+      // The promise domain has no session list, and the strand sweep needs
+      // machine-wide rows (dead-worktree sessions belong to no live
+      // instance), so this reads opencode.db directly - the same readonly
+      // pattern the -c inheritance resolution already uses. Null on any
+      // schema drift; the sweep treats that as "nothing known".
+      return enumerateSweepSessions();
+    },
+    sessionMove: async (id, directory) => {
+      // The pinned dev types carry move on the SessionDomain pick (the
+      // session_tab spawn flow uses it), so this is a typed call, unlike
+      // remove/compact above.
+      await session.move({ sessionID: id, directory });
+    },
     sessionMessages: async (id) => {
       // The pinned promise domain has no message-list endpoint (no `message`
       // accessor; compact/remove exist on newer SDK builds but not here).

package/src/runtime.ts

@@ -177,6 +177,55 @@ export function guardDelivery(
   };
 }
 
+/** What the strand sweep should do, decided purely from enumerated session rows. */
+export interface StrandPlan {
+  /** Machinery sessions (this plugin's extraction children) to delete via the host. */
+  remove: string[];
+  /** Real sessions to relocate out of a dead directory, to their project's canonical checkout. */
+  move: { id: string; to: string }[];
+  /** Rows the sweep saw but deliberately left alone. */
+  skipped: number;
+}
+
+/**
+ * Decides, per session row, whether a stranded session gets deleted
+ * (machinery), moved (a real session whose directory is gone - the same
+ * outcome as opencode's manual "session location unavailable" recovery, minus
+ * the directory picking), or left alone. Everything hinges on the directory
+ * being dead on disk: a session in a live directory is someone's working
+ * state, however it looks. Host-created task children (parentId set) are
+ * always skipped - they are opencode's own records of subagent work,
+ * invisible in top-level session lists, and deleting them would break the
+ * parent transcript's subagent rendering.
+ */
+export function planStrandActions(input: {
+  sessions: { id: string; title: string; directory: string; parentId: string | null; projectId: string | null }[];
+  canonicalByProject: Record<string, string>;
+  pathExists: (path: string) => boolean;
+  /** When false (host has no move endpoint), real sessions count as skipped. */
+  canMove: boolean;
+}): StrandPlan {
+  const plan: StrandPlan = { remove: [], move: [], skipped: 0 };
+  for (const s of input.sessions) {
+    if (input.pathExists(s.directory)) continue;
+    if (isMachinerySessionTitle(s.title)) {
+      plan.remove.push(s.id);
+      continue;
+    }
+    if (s.parentId) {
+      plan.skipped++;
+      continue;
+    }
+    const canonical = s.projectId ? input.canonicalByProject[s.projectId] : undefined;
+    if (input.canMove && canonical && canonical !== s.directory && input.pathExists(canonical)) {
+      plan.move.push({ id: s.id, to: canonical });
+    } else {
+      plan.skipped++;
+    }
+  }
+  return plan;
+}
+
 export async function createRuntime(input: {
   capabilities: HostCapabilities;
   directory: string;
@@ -760,7 +809,25 @@ export async function createRuntime(input: {
     const ownDirectory = row.directory === directory;
     const isStartup = inheritSession !== undefined && row.sessionID === inheritSession;
     if (samePid && !ownDirectory) continue; // live sibling - untouched
-    if (!samePid && !ownDirectory) continue; // another location's instance owns these rows - its own restart cleans them
+    if (!samePid && !ownDirectory) {
+      // Another location's instance owns these rows - its own restart
+      // cleans them. Exception: a directory that no longer exists (a merged
+      // and deleted worktree) will never boot an instance again, so its
+      // journaled extraction children are stranded forever - the opencode
+      // session row is global and outlives this journal. Finalize the child
+      // through the host and drop the journal row; the strand sweep (below)
+      // is the backstop for corpses this journal never knew about.
+      if (row.kind === "child" && !existsSync(row.directory)) {
+        const rec = row.value as { kind?: "extraction" | "task" };
+        if (rec?.kind === "extraction") {
+          void caps.sessionDelete(row.sessionID).catch((err) =>
+            debug("strand-sweep", `dead-directory finalize failed for ${row.sessionID}: ${err}`),
+          );
+          db.runtimeStateDelete(row.kind, row.sessionID);
+        }
+      }
+      continue;
+    }
     if (!samePid && !isStartup) {
       // Watcher definitions survive a restart as DORMANT rows instead of
       // being pruned: the defining session's harness died with the old
@@ -794,6 +861,20 @@ export async function createRuntime(input: {
         // consumption.
         continue;
       }
+      // Restart-window leak fix (same as the child-row branch below): the
+      // child's opencode session row is global and outlives this journal,
+      // so an extraction child whose idle event died with the old process
+      // must be finalized through the host before the row goes. Task
+      // children and kindless pre-marker rows are left to the strand
+      // sweep's title-based pass.
+      if (row.kind === "child") {
+        const rec = row.value as { kind?: "extraction" | "task" };
+        if (rec?.kind === "extraction") {
+          void caps.sessionDelete(row.sessionID).catch((err) =>
+            debug("strand-sweep", `restart finalize failed for ${row.sessionID}: ${err}`),
+          );
+        }
+      }
       db.runtimeStateDelete(row.kind, row.sessionID);
       continue;
     }
@@ -849,6 +930,18 @@ export async function createRuntime(input: {
         if (inheritSession !== undefined && rec?.parentID === inheritSession && Array.isArray(rec.snapshot)) {
           for (const interaction of rec.snapshot) extraction.push(interaction);
         }
+        // Restart-window leak fix: the child's opencode session row is
+        // global and outlives this journal, so an extraction child whose
+        // idle event died with the old process would sit in the session
+        // picker forever (and `-c` can land in it). Finalize through the
+        // host, best-effort. Kindless pre-marker rows are left to the
+        // strand sweep's title-based pass, which never touches
+        // host-created task children.
+        if (rec?.kind === "extraction") {
+          void caps.sessionDelete(row.sessionID).catch((err) =>
+            debug("strand-sweep", `restart finalize failed for ${row.sessionID}: ${err}`),
+          );
+        }
         db.runtimeStateDelete(row.kind, row.sessionID);
         continue;
       }
@@ -1146,6 +1239,102 @@ export async function createRuntime(input: {
   };
   void reconcileRestoredChildren();
 
+  // Self-heal for sessions stranded in directories that no longer exist
+  // (merged + deleted worktrees): opencode v2 records the directory on
+  // every session, and opening a stranded one boots a dead path and shows
+  // the "session location unavailable" recovery dialog. Machinery corpses
+  // (this plugin's extraction children, leaked by pre-2.0.22 hosts or a
+  // daemon restart mid-extraction) are deleted; REAL sessions are moved to
+  // their project's canonical checkout - never deleted. Runs at setup and
+  // on an interval, because worktrees die while the daemon lives on. The
+  // host supplies the enumeration (v1: client list; v2: readonly
+  // opencode.db read) and the move/delete endpoints; every leg degrades
+  // silently. Concurrent instances each run their own sweep - the actions
+  // are idempotent (a second delete of the same corpse throws NotFound
+  // into the catch, a second move lands on an already-moved session).
+  let sweepInFlight = false;
+  const sweepStrandedSessions = async (trigger: string): Promise<void> => {
+    // Kill switch read at call time: tests set THATCH_STRAND_SWEEP=off so
+    // the boot sweep never acts on the developer's real opencode.db through
+    // test mocks, and an operator can disarm the sweep without a rebuild.
+    const gate = process.env.THATCH_STRAND_SWEEP;
+    if (gate === "0" || gate === "false" || gate === "off") return;
+    if (disposed || sweepInFlight) return;
+    sweepInFlight = true;
+    try {
+      let enumerated: Awaited<ReturnType<typeof caps.enumerateSessions>> = null;
+      try {
+        enumerated = await caps.enumerateSessions();
+      } catch (err) {
+        debug("strand-sweep", `enumerate failed (${trigger}): ${err}`);
+        return;
+      }
+      if (!enumerated || disposed) return;
+      debug(
+        "strand-sweep",
+        `enumerated ${enumerated.sessions.length} session row(s), ${Object.keys(enumerated.canonicalByProject).length} project(s) [${trigger}]`,
+      );
+      const plan = planStrandActions({
+        sessions: enumerated.sessions,
+        canonicalByProject: enumerated.canonicalByProject,
+        pathExists: (p) => existsSync(p),
+        canMove: typeof caps.sessionMove === "function",
+      });
+      let removed = 0;
+      let moved = 0;
+      for (const id of plan.remove) {
+        if (disposed) return;
+        try {
+          await caps.sessionDelete(id);
+          // The journal row may exist for restart-window children; a
+          // historical corpse has none, and a no-op delete is fine.
+          db.runtimeStateDelete("child", id);
+          removed++;
+        } catch (err) {
+          debug("strand-sweep", `remove failed for ${id} (${trigger}): ${err}`);
+        }
+      }
+      for (const m of plan.move) {
+        if (disposed) return;
+        try {
+          await caps.sessionMove?.(m.id, m.to);
+          moved++;
+        } catch (err) {
+          debug("strand-sweep", `move failed for ${m.id} (${trigger}): ${err}`);
+        }
+      }
+      if (removed + moved > 0) {
+        debug(
+          "strand-sweep",
+          `healed ${removed + moved} stranded session(s): ${moved} moved, ${removed} removed, ${plan.skipped} skipped [${trigger}]`,
+        );
+        try {
+          await caps.showToast({
+            message: `[thatch] healed ${removed + moved} stranded session${removed + moved === 1 ? "" : "s"} from dead worktrees (${moved} moved, ${removed} removed)`,
+            variant: "info",
+            duration: 6000,
+          });
+        } catch {
+          // TUI may not be connected (headless mode).
+        }
+      }
+    } finally {
+      sweepInFlight = false;
+    }
+  };
+  const STRAND_SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+  let strandSweepTimer: ReturnType<typeof setInterval> | undefined;
+  const armStrandSweep = () => {
+    // Env override read at call time per house convention (test/ops knob).
+    const ms = Number(process.env.THATCH_STRAND_SWEEP_MS) || STRAND_SWEEP_INTERVAL_MS;
+    strandSweepTimer = setInterval(() => {
+      void sweepStrandedSessions("interval");
+    }, ms);
+    strandSweepTimer.unref?.();
+  };
+  void sweepStrandedSessions("boot");
+  armStrandSweep();
+
   // Skills always install to the global opencode config - installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -2283,6 +2472,7 @@ export async function createRuntime(input: {
     dispose: async () => {
       disposed = true;
       stopVersionChecker();
+      if (strandSweepTimer) clearInterval(strandSweepTimer);
       watchers.dispose();
       chatPoller.dispose();
       try {

package/src/session-db.ts

@@ -60,8 +60,11 @@ export function resolveOpencodeDbPath(): string | null {
  * database - the same pick the TUI makes from client.session.list(), which
  * the v2 plugin context cannot call (its session domain has no list) and
  * which would arrive too late for the runtime's synchronous rehydration
- * partition regardless. Null when the db is unavailable or no top-level
- * session exists in the directory.
+ * partition regardless. Prefers the v2 `session_v2` table when the database
+ * has one: v2-era sessions live there and the legacy `session` table only
+ * holds pre-migration rows, so a v1-table read under a v2 daemon would
+ * resolve -c from years-old sessions. Null when the db is unavailable or no
+ * top-level session exists in the directory.
  */
 export function mostRecentTopLevelSessionId(directory: string): string | null {
   const dbPath = resolveOpencodeDbPath();
@@ -73,11 +76,18 @@ export function mostRecentTopLevelSessionId(directory: string): string | null {
     return null;
   }
   try {
-    const row = db
-      .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 } | null;
+    const v2 = hasV2SessionTables(db);
+    const row = v2
+      ? (db
+          .query(
+            "SELECT id FROM session_v2 WHERE directory = ? AND (parent_id IS NULL OR parent_id = '') ORDER BY time_updated DESC LIMIT 1",
+          )
+          .get(directory) as { id: string } | null)
+      : (db
+          .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 } | null);
     return row?.id ?? null;
   } catch {
     return null;
@@ -86,6 +96,88 @@ export function mostRecentTopLevelSessionId(directory: string): string | null {
   }
 }
 
+/** True when the database carries opencode v2's session tables. */
+function hasV2SessionTables(db: Database): boolean {
+  const row = db
+    .query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'session_v2'")
+    .get() as { name: string } | undefined;
+  return row?.name === "session_v2";
+}
+
+/** One session row as the stranded-session sweep sees it (host-agnostic shape). */
+export interface SweepSessionRow {
+  id: string;
+  title: string;
+  directory: string;
+  /** Host link for subagent children; null for top-level sessions. */
+  parentId: string | null;
+  /** v2 project id (joins to the project table's canonical worktree). Null on v1 rows. */
+  projectId: string | null;
+}
+
+/** Everything the strand sweep needs from one readonly pass over opencode.db. */
+export interface SweepEnumeration {
+  sessions: SweepSessionRow[];
+  /** Project id -> canonical checkout directory. Empty on v1 (no project rows read). */
+  canonicalByProject: Record<string, string>;
+}
+
+/**
+ * Enumerates every session row opencode has, plus each project's canonical
+ * checkout directory, in one readonly pass. Prefers the v2 tables
+ * (session_v2 + project) and falls back to the v1 `session` table when the
+ * database predates them. Returns null when the db is missing, unreadable,
+ * or its schema has drifted past these column names - the strand sweep
+ * treats null as "nothing known, do nothing". The sweep's deletions and
+ * moves go through the host's own session endpoints; this read only ever
+ * NAMES candidates, so a stale or partial read can never corrupt anything.
+ */
+export function enumerateSweepSessions(): SweepEnumeration | null {
+  const dbPath = resolveOpencodeDbPath();
+  if (!dbPath) return null;
+  let db: Database;
+  try {
+    db = new Database(dbPath, { readonly: true });
+  } catch {
+    return null;
+  }
+  try {
+    const v2 = hasV2SessionTables(db);
+    const sessions: SweepSessionRow[] = v2
+      ? (db
+          .query("SELECT id, title, directory, parent_id, project_id FROM session_v2")
+          .all() as { id: string; title: string | null; directory: string; parent_id: string | null; project_id: string | null }[]
+        ).map((r) => ({
+          id: r.id,
+          title: r.title ?? "",
+          directory: r.directory,
+          parentId: r.parent_id ?? null,
+          projectId: r.project_id ?? null,
+        }))
+      : (db
+          .query("SELECT id, title, directory, parent_id FROM session")
+          .all() as { id: string; title: string | null; directory: string; parent_id: string | null }[]).map((r) => ({
+          id: r.id,
+          title: r.title ?? "",
+          directory: r.directory,
+          parentId: r.parent_id ?? null,
+          projectId: null,
+        }));
+    const canonicalByProject: Record<string, string> = {};
+    if (v2) {
+      const projectRows = db
+        .query("SELECT id, worktree FROM project")
+        .all() as { id: string; worktree: string }[];
+      for (const r of projectRows) canonicalByProject[r.id] = r.worktree;
+    }
+    return { sessions, canonicalByProject };
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
 export interface SessionRow {
   id: string;
   title: string;