Skip to content

Commit 4a2a834

Browse files
committed
Round-4 review: instance-scoped journal, crash-safe child recovery, awaited model release
- runtime_state rows carry the writing instance's directory; rehydration is instance-scoped: a second location instance on the same db in one v2 serve no longer hydrates (and N-fold polls/re-delivers) a sibling's watchers; sibling rows are never pruned either - foreign-pid child rows now mean 'child died with the process': the snapshot requeues as plain pending entries and the row drops - never restoring 'extracting', which permanently suppressed both extraction paths on the resumed session - foreign-pid wrap-up rows drop instead of inheriting (an inherited arm could auto-fire compact/exit on the resumed session's first idle) - SharedModelPool.release awaits the model dispose at zero refs - the dropped promise could let the process exit while ONNX sessions were still releasing (NAPI finalizer panic) - the v2 adapter seeds its event-forwarding child set from the rehydrated child map (ThatchRuntime.childSessionIds), so a below-root reload keeps receiving child events - restored sessions get a synthetic noReply re-attach notice - test env save/restore for THATCH_DB_PATH
1 parent 8408b96 commit 4a2a834

8 files changed

Lines changed: 249 additions & 89 deletions

File tree

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
7373
| compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (no `session.compact` on the promise domain's Pick, and the built-in `/compact` is a TUI palette action calling the server endpoint directly - the server command registry only knows config/plugin-registered names; the wrap-up checklist and flush still run, the automatic compaction is skipped) |
7474
| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context) |
7575
| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the process exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984)) |
76-
| 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 and rehydrated on the next `setup()`: rows written by the same process (a reload) all restore; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume (crash recovery). The embedding model is refcounted per db path, so N location instances share one resident model |
76+
| 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; 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). Restored sessions get a synthetic re-attach notice. The embedding model is refcounted per db path, so N location instances share one resident model |
7777

7878
## Live verification and remaining unknowns
7979

‎docs/plans/plugin-state-persistence.md‎

Lines changed: 35 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -25,41 +25,54 @@ memory is therefore lost across both events:
2525

2626
## Design
2727

28-
### 1. Runtime state journal (SQLite)
28+
### 1. Runtime state journal (SQLite, instance-scoped)
2929

3030
New table in ThatchDB:
3131

3232
```sql
3333
CREATE TABLE IF NOT EXISTS runtime_state (
34-
kind TEXT NOT NULL, -- 'buffer' | 'child' | 'wrapup' | ...
34+
kind TEXT NOT NULL, -- 'buffer' | 'accepted' | 'child' | 'wrapup' | 'watchers'
3535
session_id TEXT NOT NULL,
36-
seq INTEGER NOT NULL, -- ordering within kind+session
37-
value TEXT NOT NULL, -- JSON
38-
pid INTEGER NOT NULL, -- writer's process id
36+
directory TEXT NOT NULL, -- the writing instance's location - the scoping key
37+
value TEXT NOT NULL, -- JSON
38+
pid INTEGER NOT NULL,-- writer's process id
3939
created_at TEXT NOT NULL DEFAULT (strftime('%s','now'))
4040
);
4141
```
4242

43-
Write-through at the mutation points (buffer push/consume/completeAccepted,
44-
child create/adopt/clear, wrap-up arm/resolve). The `pid` column is the
45-
restart discriminator: v2 reload re-runs `setup()` in the same process, so a
46-
matching pid means "reload - keep and rehydrate"; a different pid means
47-
"restart - the old sessions died with their harness".
43+
Write-through at the mutation points (buffer push/consume/accept/complete/
44+
requeue, child create/adopt/clear, wrap-up arm/resolve, watcher membership).
45+
The pid AND directory columns together are the partition key: one v2 serve
46+
hosts one plugin instance PER LOCATION in one process, so pid alone cannot
47+
scope rehydration (instance B would hydrate instance A's watchers and poll
48+
them N-fold).
4849

4950
### 2. Rehydrate-and-prune on setup
5051

51-
`createRuntime` loads persisted state, then partitions by pid:
52-
53-
- **Same pid (reload)**: restore everything - buffers, child maps,
54-
pendingWrapUp - and re-arm the watchers (recreate their pollers from the
55-
persisted definitions).
56-
- **Different pid (restart)**: keep only state whose session is the startup
57-
session (`-s`/`-c` resolved id; the resumed conversation continues and
58-
inherits its buffer and watches - this also makes crash recovery work on
59-
v1). Everything else is pruned.
60-
61-
This replaces "silent loss" with "reload = resume, restart = intentional
62-
handoff to the resumed session".
52+
`createRuntime` partitions the journal by (pid, directory):
53+
54+
- **Same pid + same directory (reload)**: restore everything - buffers,
55+
child bookkeeping, pendingWrapUp - and re-arm the watchers (the registry
56+
rebuilds its pollers from the persisted definitions). The v2 adapter also
57+
re-seeds its event-forwarding child set from the runtime's rehydrated
58+
child map, so below-root launches keep receiving child events.
59+
- **Same pid + other directory**: a live sibling instance's rows - untouched
60+
(never hydrated, never pruned).
61+
- **Foreign pid (restart)**: sessions die with their harness. Only a
62+
startup-resumed session (`-s`/`-c`) in this directory inherits
63+
recovery-safe state: the buffer rehydrates, and a dead extraction child's
64+
snapshot is requeued as plain pending entries (extraction stays available;
65+
`extracting` is NOT restored - the child's events died with the process
66+
and a live `extracting` entry would suppress both extraction paths
67+
forever). Armed wrap-ups and child bookkeeping are dropped across a
68+
restart: an inherited wrap-up could auto-fire compact/exit on the resumed
69+
session's first idle.
70+
71+
Restored sessions get a synthetic, noReply re-attach notice so they know
72+
the plugin is back (the reload happened outside their event stream).
73+
74+
This replaces "silent loss" with "reload = resume, restart = crash recovery
75+
for the resumed session".
6376

6477
### 3. resumedSession scalar -> Set
6578

‎src/db.ts‎

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,7 @@ export class ThatchDB {
332332
CREATE TABLE IF NOT EXISTS runtime_state (
333333
kind TEXT NOT NULL,
334334
session_id TEXT NOT NULL,
335+
directory TEXT NOT NULL DEFAULT '',
335336
value TEXT NOT NULL,
336337
pid INTEGER NOT NULL,
337338
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
@@ -347,6 +348,14 @@ export class ThatchDB {
347348
this.#migrateChatAuto();
348349
this.#migrateChatWorktree();
349350
this.#migrateChatHostPid();
351+
this.#migrateRuntimeStateDirectory();
352+
}
353+
354+
#migrateRuntimeStateDirectory(): void {
355+
const cols = (this.#db.query("PRAGMA table_info(runtime_state)").all() as any[]).map((r) => r.name);
356+
if (cols.length > 0 && !cols.includes("directory")) {
357+
this.#db.run("ALTER TABLE runtime_state ADD COLUMN directory TEXT NOT NULL DEFAULT ''");
358+
}
350359
}
351360

352361
// chat_sessions tables created before the auto column lack it; the ALTER
@@ -978,14 +987,19 @@ export class ThatchDB {
978987
return this.#chat.unregister(sessionID);
979988
}
980989

981-
/** Persist one runtime-state record (upsert by kind+session). */
982-
runtimeStatePut(kind: string, sessionId: string, value: unknown, pid: number = process.pid) {
990+
/**
991+
* Persist one runtime-state record (upsert by kind+session). `directory`
992+
* is the writing instance's location: one v2 serve hosts one plugin
993+
* instance per directory sharing this db, and rehydration must be
994+
* instance-scoped, not process-scoped.
995+
*/
996+
runtimeStatePut(kind: string, sessionId: string, value: unknown, directory: string, pid: number = process.pid) {
983997
this.#db
984998
.query(
985-
`INSERT INTO runtime_state (kind, session_id, value, pid) VALUES (?, ?, ?, ?)
986-
ON CONFLICT (kind, session_id) DO UPDATE SET value = excluded.value, pid = excluded.pid, created_at = excluded.created_at`,
999+
`INSERT INTO runtime_state (kind, session_id, directory, value, pid) VALUES (?, ?, ?, ?, ?)
1000+
ON CONFLICT (kind, session_id) DO UPDATE SET directory = excluded.directory, value = excluded.value, pid = excluded.pid, created_at = excluded.created_at`,
9871001
)
988-
.run(kind, sessionId, JSON.stringify(value), pid);
1002+
.run(kind, sessionId, directory ?? "", JSON.stringify(value), pid);
9891003
}
9901004

9911005
/** Drop one runtime-state record. */
@@ -994,9 +1008,9 @@ export class ThatchDB {
9941008
}
9951009

9961010
/** Every runtime-state record, oldest first (rehydration source). */
997-
runtimeStateAll(): { kind: string; sessionID: string; value: unknown; pid: number }[] {
1011+
runtimeStateAll(): { kind: string; sessionID: string; directory: string; value: unknown; pid: number }[] {
9981012
return this.#db
999-
.query(`SELECT kind, session_id, value, pid FROM runtime_state ORDER BY created_at, session_id`)
1013+
.query(`SELECT kind, session_id, directory, value, pid FROM runtime_state ORDER BY created_at, session_id`)
10001014
.all()
10011015
.map((row: any) => {
10021016
let value: unknown;
@@ -1005,7 +1019,13 @@ export class ThatchDB {
10051019
} catch {
10061020
value = null;
10071021
}
1008-
return { kind: row.kind as string, sessionID: row.session_id as string, value, pid: row.pid as number };
1022+
return {
1023+
kind: row.kind as string,
1024+
sessionID: row.session_id as string,
1025+
directory: (row.directory ?? "") as string,
1026+
value,
1027+
pid: row.pid as number,
1028+
};
10091029
});
10101030
}
10111031

‎src/embeddings.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -181,13 +181,18 @@ export class SharedModelPool {
181181
return created.model;
182182
}
183183

184-
release(dbPath: string): void {
184+
/**
185+
* Release one reference. Resolves when the model's ONNX sessions are
186+
* released (at zero refs) - the caller MUST await it before its process
187+
* can exit, or Bun's NAPI finalizers panic on teardown.
188+
*/
189+
async release(dbPath: string): Promise<void> {
185190
const entry = this.#entries.get(dbPath);
186191
if (!entry) return;
187192
entry.refs -= 1;
188193
if (entry.refs <= 0) {
189-
void entry.model.dispose();
190194
this.#entries.delete(dbPath);
195+
await entry.model.dispose();
191196
}
192197
}
193198

‎src/opencode/v2.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,12 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
7272

7373
const capabilities = buildCapabilities(context, worktree, childSessions);
7474
const runtime = await createRuntime({ capabilities, directory, worktree });
75+
// Seed the forwarding set from rehydrated child bookkeeping: after a
76+
// reload, an in-flight extraction child's maps come back from the journal,
77+
// but this NEW adapter instance's childSessions set starts empty - without
78+
// the seed, the pump's directory filter drops the child's events again
79+
// (the below-root launch case).
80+
for (const id of runtime.childSessionIds()) childSessions.add(id);
7581

7682
// Tool registration: the same CoreContext the v1 adapter feeds to
7783
// createTools, registered through the v2 ToolEditor instead.

0 commit comments

Comments
 (0)