Expose audited hardcoded tunables as plugin config

The audit swept every packages/*/* plugin for the new AGENTS.md
convention (no hardcoded tunables in plugins) and exposes each finding
as a defaulted, validated Config field. Defaults are the previously
hardcoded values throughout, so no deployment or golden changes.

- tool-fs (had NO Config): readLimit, readMaxLineLength, readMaxBytes,
  readStreamMinSize. The caps thread through ReadToolCaps/ReadWindow —
  read-render already documented that the consumer applies the caps, so
  they become explicit per-request fields.
- tool-web: searchMaxResults (WEB_SEARCH_MAX_RESULTS stays as the
  schemastery default). Also fixes the stale GREP_LIMIT references in
  search.ts and the web-capability-seam RFC (no such constant exists).
- bash-local: graceMs (SIGTERM->SIGKILL escalation grace). The
  RunInternals.graceMs test seam is gone: graceMs is now a required
  SpawnSpec field filled from config, so tests exercise the real
  config path and the defaults live in exactly one place.
- subagent-acp: disposeEofGraceMs / disposeGraceMs. The AcpRunSpec
  fields become required for the same one-defaulting-layer reason.
- session-persistence-sqlite: journalMode ('wal' default; the
  rollback-journal modes serve filesystems where WAL's shared-memory
  files do not work, e.g. network mounts).
- hooks-claude + hooks-codex: stderrSummaryMaxChars for the persisted
  hook/result stderr summary. The duplicated summarize() helpers merge
  into hook-protocol's summarizeStderr(stderr, maxChars), beside the
  HookResultRecord field it feeds, with the bound parameterized the
  same way runHook's defaultTimeoutMs already is.
- compact-basic: charsPerToken for the token estimator (default 4, the
  English-text heuristic; CJK-heavy deployments need ~1-2 or compaction
  fires far too late). Also corrects the BasicCompactService class doc,
  which claimed defaults the required-field config never had.
- fs-local: deletes the dead STREAM_MIN_SIZE constant and the dead
  FsIoInternals.streamMinSize seam — the read-routing bound lives in
  the consumer (tool-fs), where it is now config. This is item 1 of
  the proposed prune-write-only-fs-surface RFC, annotated accordingly.

Every new field gets range validation (following the existing
assertPositiveFinite pattern), a README row, and tests covering the
configured behavior, the schema default, and load-time rejection.

packages/session-persistence/session-persistence-sqlite/README.md

@@ -8,7 +8,7 @@ A SQLite durable session-persistence backend — a second `SessionPersistence` i
 
 Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../docs/rfc/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`) lives in a `sessions` row. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row), so no separate column is needed.
 
-The repo targets Node ≥ 24 (the root `engines` field), which includes the stable `node:sqlite` module. The database opens with `foreign_keys = ON` (so `ON DELETE CASCADE` drops a session's events with its row) and `journal_mode = WAL`. The table-layout version is stored in `PRAGMA user_version` and checked on open: a fresh database is stamped with the current `SCHEMA_VERSION`; a database written by any other, incompatible build (a non-current `user_version`, older or newer) is rejected rather than opened against an unknown layout — there is no migration (unreleased software).
+The repo targets Node ≥ 24 (the root `engines` field), which includes the stable `node:sqlite` module. The database opens with `foreign_keys = ON` (so `ON DELETE CASCADE` drops a session's events with its row) and the configured `journal_mode` (default `wal`; pick a rollback-journal mode like `delete` on filesystems where WAL's shared-memory files do not work, e.g. network mounts). The table-layout version is stored in `PRAGMA user_version` and checked on open: a fresh database is stamped with the current `SCHEMA_VERSION`; a database written by any other, incompatible build (a non-current `user_version`, older or newer) is rejected rather than opened against an unknown layout — there is no migration (unreleased software).
 
 ## Contract semantics over rows
 
@@ -21,6 +21,7 @@ The repo targets Node ≥ 24 (the root `engines` field), which includes the stab
 ```ts
 interface Config {
   path: string   // SQLite database file path, or ':memory:' for an in-process DB
+  journalMode?: 'wal' | 'delete' | 'truncate' | 'persist'   // journal_mode pragma; default 'wal'
 }
 ```
 

packages/session-persistence/session-persistence-sqlite/src/index.ts

@@ -28,7 +28,7 @@ import {
 } from '@deepseek-ai/dsh-session-persistence'
 import type { Session, SessionEvent, SurfaceEventType, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
-  openDatabase, rowToMeta, scanRows, type EventRow, type SessionRow,
+  type JournalMode, openDatabase, rowToMeta, scanRows, type EventRow, type SessionRow,
 } from './schema.ts'
 
 export { SCHEMA_VERSION } from './schema.ts'
@@ -54,6 +54,13 @@ export interface Config {
    * dirs) on construction.
    */
   path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) is the recorded
+   * durability model; pick a rollback-journal mode (`delete`/`truncate`/
+   * `persist`) on filesystems where WAL's shared-memory files do not work
+   * (network mounts). See {@link JournalMode}.
+   */
+  journalMode?: JournalMode
 }
 
 /**
@@ -66,6 +73,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
 
   static Config: z<Config> = z.object({
     path: z.string().required(),
+    journalMode: z.union(['wal', 'delete', 'truncate', 'persist'] as const).default('wal'),
   })
 
   /**
@@ -83,18 +91,19 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     super(ctx)
     // Open the database asynchronously (the parent directory may need creating);
     // every hook awaits `ready` first. Opening synchronously would force a sync
-    // mkdir and block plugin apply.
-    this.ready = this.openDb(config.path)
+    // mkdir and block plugin apply. schemastery (static Config) has already
+    // filled `journalMode`; the cast records that runtime fact.
+    this.ready = this.openDb(config.path, (config as Required<Config>).journalMode)
     this.coordinator = new PersistenceCoordinator<number>(this.ctx, this)
   }
 
-  private async openDb(path: string): Promise<void> {
+  private async openDb(path: string, journalMode: JournalMode): Promise<void> {
     if (path !== ':memory:') {
       const abs = resolve(path)
       await mkdir(dirname(abs), { recursive: true, mode: 0o700 })
-      this.db = openDatabase(abs)
+      this.db = openDatabase(abs, journalMode)
     } else {
-      this.db = openDatabase(path)
+      this.db = openDatabase(path, journalMode)
     }
   }
 

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -45,10 +45,21 @@ export interface EventRow {
   surface_op: string | null
 }
 
+/**
+ * Journal modes the backend will run under. `wal` is the default and the
+ * durability model the persistence ADR records; the rollback-journal modes
+ * (`delete`/`truncate`/`persist`) exist for filesystems where WAL's
+ * shared-memory files do not work (network mounts). `memory`/`off` are
+ * excluded: dropping journal durability silently contradicts what this
+ * backend promises.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+
 /**
  * Open the database at `path` and apply the schema + pragmas. `foreign_keys`
- * makes `ON DELETE CASCADE` drop a session's events with its row; `journal_mode
- * = WAL` matches the durability model the ADR records (the row shape maps 1:1
+ * makes `ON DELETE CASCADE` drop a session's events with its row; the
+ * `journal_mode` pragma is set from the plugin's `journalMode` config (`wal`
+ * default — the durability model the ADR records; the row shape maps 1:1
  * onto `SessionEvent`; opencode runs this exact shape on SQLite/WAL).
  *
  * The table-layout version is persisted in SQLite's `PRAGMA user_version` and
@@ -66,10 +77,12 @@ export interface EventRow {
  * makes the version check reject both sibling v3 databases instead of opening
  * one against columns it does not have.
  */
-export function openDatabase(path: string): DatabaseSync {
+export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
   const db = new DatabaseSync(path)
   db.exec('PRAGMA foreign_keys = ON')
-  db.exec('PRAGMA journal_mode = WAL')
+  // journalMode is a closed in-code union (validated by the plugin Config), not
+  // user-controlled SQL — safe to interpolate (PRAGMA takes no bound params).
+  db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
   // `PRAGMA user_version` always returns exactly one row { user_version }.
   const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
   if (onDisk !== 0 && onDisk !== SCHEMA_VERSION) {

packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
+import { existsSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -53,7 +54,7 @@ runCoordinatorContract('sqlite', async (): Promise<CoordinatorFixture> => {
       // A row past the committed region whose `data` does not parse: scanRows
       // bounds the preserved prefix at it and returns its seq as tornFrom, which
       // the backend surfaces to the coordinator as the tornMarker to delete from.
-      const db = openDatabase(path)
+      const db = openDatabase(path, 'wal')
       const next = (db.prepare('SELECT COALESCE(MAX(seq), -1) + 1 AS n FROM events WHERE session_id = ?')
         .get(id) as { n: number }).n
       db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
@@ -192,7 +193,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     await b1.ctx.sessionPersistence.append(m.id, oneTurnLog()) // seqs 0..5
     await b1.dispose()
     // Hand-write an interrupted turn (turn/start seq 6, no turn/end).
-    const db = openDatabase(path)
+    const db = openDatabase(path, 'wal')
     db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, 6, ?, 7, ?)')
       .run(m.id, 'turn/start', JSON.stringify({ turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
     db.close()
@@ -204,7 +205,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     expect(loaded.events.at(-1)!.type).toBe('turn/end')
     // load() is mutating: the synthetic turn/end MUST be on disk so the stored log
     // is balanced and the cursor is truthful (contract: load closes, not defers).
-    const probe = openDatabase(path)
+    const probe = openDatabase(path, 'wal')
     const stored = probe.prepare('SELECT seq, type FROM events WHERE session_id = ? ORDER BY seq').all(m.id) as { seq: number; type: string }[]
     probe.close()
     expect(stored.map(r => r.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
@@ -237,21 +238,21 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
 
   it('rejects opening a database whose schema version is not the current build (newer OR older)', async () => {
     const path = await freshDbPath()
-    openDatabase(path).close() // stamp user_version = SCHEMA_VERSION
+    openDatabase(path, 'wal').close() // stamp user_version = SCHEMA_VERSION
     // Bump user_version past what this build supports.
-    const dbNewer = openDatabase(path)
+    const dbNewer = openDatabase(path, 'wal')
     dbNewer.exec(`PRAGMA user_version = ${SCHEMA_VERSION + 1}`)
     dbNewer.close()
-    expect(() => openDatabase(path)).toThrow(/incompatible with this build/)
+    expect(() => openDatabase(path, 'wal')).toThrow(/incompatible with this build/)
 
     // A stale OLDER version (e.g. a pre-summary-drop v1 DB) is also rejected —
     // we do not migrate (unreleased software, no backward-compat).
     const olderPath = await freshDbPath()
-    openDatabase(olderPath).close()
-    const dbOlder = openDatabase(olderPath)
+    openDatabase(olderPath, 'wal').close()
+    const dbOlder = openDatabase(olderPath, 'wal')
     dbOlder.exec('PRAGMA user_version = 1')
     dbOlder.close()
-    expect(() => openDatabase(olderPath)).toThrow(/incompatible with this build/)
+    expect(() => openDatabase(olderPath, 'wal')).toThrow(/incompatible with this build/)
   })
 
   it('rejects a sibling v3 database (the merge-collided version) rather than opening it against missing columns', async () => {
@@ -261,11 +262,11 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     // of this build's columns, so it MUST be rejected, not opened. Stamp a v3
     // database and confirm the version check refuses it.
     const path = await freshDbPath()
-    openDatabase(path).close() // creates + stamps user_version = SCHEMA_VERSION (4)
-    const db = openDatabase(path)
+    openDatabase(path, 'wal').close() // creates + stamps user_version = SCHEMA_VERSION (4)
+    const db = openDatabase(path, 'wal')
     db.exec('PRAGMA user_version = 3')
     db.close()
-    expect(() => openDatabase(path)).toThrow(/schema version 3, incompatible with this build/)
+    expect(() => openDatabase(path, 'wal')).toThrow(/schema version 3, incompatible with this build/)
   })
 
   it('a corrupt-JSON row in the uncommitted tail is discarded on load, not unloadable', async () => {
@@ -281,7 +282,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     // unloadable; a torn tail must be discarded. scanRows finds the last
     // turn/end on the seq+type columns (never parsing tail `data`), so the
     // unparsable row after it bounds the preserved prefix and is deleted by load.
-    const db = openDatabase(path)
+    const db = openDatabase(path, 'wal')
     db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, 6, ?, 7, ?)')
       .run(m.id, 'turn/start', '{not valid json')
     db.close()
@@ -370,6 +371,29 @@ describe('SessionPersistenceSqlite: edge cases', () => {
     await b2.dispose()
   })
 
+  it('journalMode config reaches the database (default wal, rollback modes selectable)', async () => {
+    // :memory: databases always report journal_mode=memory, so probe file DBs.
+    const walPath = await freshDbPath()
+    const bWal = await backend(walPath)
+    await bWal.ctx.sessionPersistence.create(meta('jm-wal'))
+    expect((openDatabase(walPath, 'wal').prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal')
+    await bWal.dispose()
+
+    const deletePath = await freshDbPath()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(SessionPersistenceSqlite, { path: deletePath, journalMode: 'delete' })
+    await ctx.sessionPersistence.create(meta('jm-delete'))
+    // Probe through a second connection: journal_mode=delete is a per-database
+    // property only insofar as no WAL files exist — assert the world, not the
+    // backend's self-report (no -wal sidecar after writes in delete mode).
+    const db = openDatabase(deletePath, 'delete')
+    expect((db.prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('delete')
+    db.close()
+    expect(existsSync(`${deletePath}-wal`)).toBe(false)
+    await fiber.dispose()
+  })
+
   it('HMR: a DIFFERENT session colliding with a materialized on-disk id is rejected', async () => {
     const path = await freshDbPath()
     // Instance 1 materializes a session and disposes.