advisers 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/sqlite.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { DatabaseSync } from 'node:sqlite'
2
- import { chmodSync, copyFileSync } from 'node:fs'
2
+ import { chmodSync, closeSync, copyFileSync, fsyncSync, mkdirSync, openSync, readFileSync, rmSync, statSync, unlinkSync, utimesSync, writeSync } from 'node:fs'
3
3
  import { createHash, createHmac, randomUUID } from 'node:crypto'
4
+ import { dirname, join } from 'node:path'
4
5
 
5
6
  /**
6
7
  * Open + write hardening (2026-11-17 robustness audit P0-1/P0-3/P1-2):
@@ -42,6 +43,310 @@ function backoffMs(attempt) {
42
43
  return Math.min(2000, 50 * 2 ** attempt)
43
44
  }
44
45
 
46
+ // ---------------------------------------------------------------------------
47
+ // Cross-process single-writer instance lock (0.2.1 robustness audit P0-1).
48
+ //
49
+ // The ledger snapshot save() path (see _saveRows below) writes whole rows, so
50
+ // two ordinary CLI commands that both load() and then save() can overwrite each
51
+ // other's committed updates (and resurrect soft-deleted rows) even while the
52
+ // SQLite page-level writer serialization keeps the file structurally intact.
53
+ // The audit's recommended first fix is one writer per HOME: every process that
54
+ // opens the SQLite store takes ~/.advisers/instance.lock (O_EXCL) first, waits a
55
+ // bounded time for a live holder, reclaims a provably stale lock, and releases
56
+ // on exit/SIGINT/SIGTERM.
57
+ //
58
+ // Rules that keep the takeover safe:
59
+ // - a lock whose pid is alive is never stolen while its heartbeat is fresh;
60
+ // long-lived holders (ui/mcp/bridge) refresh the lock mtime periodically.
61
+ // - a stale lock is removed only under an O_EXCL reclaim guard directory, so
62
+ // two waiters can never both delete and recreate the lock under each other.
63
+ // - release() only unlinks the lock when its pid + startedAt still match ours.
64
+ // ---------------------------------------------------------------------------
65
+ export const INSTANCE_LOCK_FILE = 'instance.lock'
66
+ const DEFAULT_LOCK_TIMEOUT_MS = 10_000
67
+ const DEFAULT_LOCK_STALE_MS = 60 * 60 * 1000
68
+ const MAX_LOCK_TIMEOUT_MS = 24 * 60 * 60 * 1000
69
+ const MAX_LOCK_STALE_MS = 30 * 24 * 60 * 60 * 1000
70
+ const LOCK_POLL_INTERVAL_MS = 50
71
+ const LOCK_RECLAIM_GUARD_MS = 10_000
72
+
73
+ /** The database exists but cannot be trusted (0 bytes / not a SQLite file). */
74
+ export class DatabaseCorruptError extends Error {
75
+ constructor(path, detail) {
76
+ super(
77
+ `E_DB_CORRUPT: ${path}: ${detail}. Refusing to rebuild or overwrite it. ` +
78
+ 'Back up the file first (do not delete it), then run `advisers doctor`; ' +
79
+ 'restore a known-good copy (state.db.before-*) if you have one.',
80
+ )
81
+ this.name = 'DatabaseCorruptError'
82
+ this.code = 'E_DB_CORRUPT'
83
+ this.path = path
84
+ }
85
+ }
86
+
87
+ /** Another live advisers process holds the HOME's single-writer instance lock. */
88
+ export class DatabaseLockedError extends Error {
89
+ constructor({ lockPath, holder, waitedMs, timeoutMs }) {
90
+ const who = holder
91
+ ? ` (pid ${holder.pid}, started ${holder.startedAt || 'unknown'}${holder.command ? `, "${holder.command}"` : ''})`
92
+ : ''
93
+ super(
94
+ `E_DB_LOCKED: another advisers process is using this home via ${lockPath}${who}; ` +
95
+ `waited ${waitedMs}ms (ADVISERS_LOCK_TIMEOUT_MS=${timeoutMs}). No data was written. ` +
96
+ 'Stop the other process (ui/mcp/bridge servers hold the lock while running) and retry, ' +
97
+ 'or raise ADVISERS_LOCK_TIMEOUT_MS to wait longer. If the holder is gone, remove the stale lock file.',
98
+ )
99
+ this.name = 'DatabaseLockedError'
100
+ this.code = 'E_DB_LOCKED'
101
+ this.lockPath = lockPath
102
+ this.holder = holder
103
+ this.waitedMs = waitedMs
104
+ }
105
+ }
106
+
107
+ function readEnvMs(name, fallback, max) {
108
+ const raw = process.env[name]
109
+ if (raw === undefined || raw === null || String(raw).trim() === '') return fallback
110
+ const value = Number(raw)
111
+ if (!Number.isFinite(value) || value < 0) return fallback
112
+ return Math.min(Math.floor(value), max)
113
+ }
114
+
115
+ /** Wait budget for a contended instance lock (`ADVISERS_LOCK_TIMEOUT_MS`, default 10s). */
116
+ export function instanceLockTimeoutMs() {
117
+ return readEnvMs('ADVISERS_LOCK_TIMEOUT_MS', DEFAULT_LOCK_TIMEOUT_MS, MAX_LOCK_TIMEOUT_MS)
118
+ }
119
+
120
+ /** Age after which an unrefreshed lock may be reclaimed (`ADVISERS_LOCK_STALE_MS`, default 1h). */
121
+ export function instanceLockStaleMs() {
122
+ return readEnvMs('ADVISERS_LOCK_STALE_MS', DEFAULT_LOCK_STALE_MS, MAX_LOCK_STALE_MS)
123
+ }
124
+
125
+ /** Absolute path of the per-HOME instance lock. */
126
+ export function instanceLockPath(home) {
127
+ return join(home, INSTANCE_LOCK_FILE)
128
+ }
129
+
130
+ function isPidAlive(pid) {
131
+ if (!Number.isInteger(pid) || pid <= 0) return false
132
+ try {
133
+ process.kill(pid, 0)
134
+ return true
135
+ } catch (error) {
136
+ // EPERM: the pid exists but belongs to another user; never steal from it.
137
+ return error?.code === 'EPERM'
138
+ }
139
+ }
140
+
141
+ /** Read + stat the instance lock without creating anything; null when absent. */
142
+ export function readInstanceLock(home) {
143
+ const file = instanceLockPath(home)
144
+ let stat
145
+ try {
146
+ stat = statSync(file)
147
+ } catch (error) {
148
+ if (error?.code === 'ENOENT') return null
149
+ throw error
150
+ }
151
+ let record = null
152
+ try {
153
+ const parsed = JSON.parse(readFileSync(file, 'utf8'))
154
+ if (parsed && typeof parsed === 'object' && Number.isFinite(Number(parsed.pid)) && Number(parsed.pid) > 0) {
155
+ record = {
156
+ pid: Math.trunc(Number(parsed.pid)),
157
+ startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : '',
158
+ command: typeof parsed.command === 'string' ? parsed.command : '',
159
+ }
160
+ }
161
+ } catch {}
162
+ return { file, record, mtimeMs: stat.mtimeMs, size: stat.size }
163
+ }
164
+
165
+ /**
166
+ * A lock is stale when its owner pid is gone, or when it has not been refreshed
167
+ * (heartbeat / normal short command) for longer than `staleMs`. A live pid with
168
+ * a fresh mtime is never stolen — ui/mcp/bridge holders legitimately keep the
169
+ * lock for hours.
170
+ */
171
+ export function instanceLockIsStale(info, { now = Date.now(), staleMs = instanceLockStaleMs() } = {}) {
172
+ if (!info) return false
173
+ if (info.record && !isPidAlive(info.record.pid)) return true
174
+ return now - info.mtimeMs > staleMs
175
+ }
176
+
177
+ function heartbeatIntervalMs(staleMs) {
178
+ return Math.max(1000, Math.min(5 * 60_000, Math.floor(staleMs / 4)))
179
+ }
180
+
181
+ /** Remove a stale lock while serialising concurrent reclaimers with a tty-less guard dir. */
182
+ function reclaimStaleLock({ path, expected, staleMs, timeoutMs, pollMs }) {
183
+ const guard = path + '.reclaim'
184
+ const guardDeadline = Date.now() + timeoutMs
185
+ for (;;) {
186
+ try {
187
+ mkdirSync(guard, { mode: 0o700 })
188
+ break
189
+ } catch (error) {
190
+ if (error?.code !== 'EEXIST') throw error
191
+ let age = 0
192
+ try { age = Date.now() - statSync(guard).mtimeMs } catch {}
193
+ if (age > LOCK_RECLAIM_GUARD_MS) {
194
+ try { rmSync(guard, { recursive: true, force: true }) } catch {}
195
+ continue
196
+ }
197
+ if (Date.now() >= guardDeadline) return false
198
+ sleepSync(pollMs)
199
+ }
200
+ }
201
+ try {
202
+ const current = readInstanceLock(dirname(path))
203
+ if (!current) return true
204
+ if (!instanceLockIsStale(current, { staleMs })) return false
205
+ // Only delete the exact record we inspected; a new holder may have replaced it.
206
+ const same = expected
207
+ ? current.record && expected.record &&
208
+ current.record.pid === expected.record.pid &&
209
+ current.record.startedAt === expected.record.startedAt
210
+ : !current.record
211
+ if (!same) return false
212
+ try { unlinkSync(path) } catch (error) { if (error?.code !== 'ENOENT') throw error }
213
+ return true
214
+ } finally {
215
+ try { rmSync(guard, { recursive: true, force: true }) } catch {}
216
+ }
217
+ }
218
+
219
+ export class InstanceLock {
220
+ constructor({ home, command = '', timeoutMs = instanceLockTimeoutMs(), staleMs = instanceLockStaleMs(), pollMs = LOCK_POLL_INTERVAL_MS } = {}) {
221
+ this.home = home
222
+ this.path = instanceLockPath(home)
223
+ this.timeoutMs = Math.max(0, Math.floor(Number(timeoutMs) || 0))
224
+ this.staleMs = Math.max(1, Math.floor(Number(staleMs) || DEFAULT_LOCK_STALE_MS))
225
+ this.pollMs = Math.max(5, Math.floor(Number(pollMs) || LOCK_POLL_INTERVAL_MS))
226
+ this.record = { pid: process.pid, startedAt: new Date().toISOString(), command: String(command ?? '').slice(0, 160) }
227
+ this._held = false
228
+ this._heartbeat = null
229
+ }
230
+
231
+ get held() {
232
+ return this._held
233
+ }
234
+
235
+ /** Try once to create the lock file (O_EXCL); returns true on success. */
236
+ _create() {
237
+ mkdirSync(this.home, { recursive: true, mode: 0o700 })
238
+ let fd
239
+ try {
240
+ fd = openSync(this.path, 'wx', 0o600)
241
+ } catch (error) {
242
+ if (error?.code === 'EEXIST') return false
243
+ throw error
244
+ }
245
+ try {
246
+ writeSync(fd, JSON.stringify(this.record) + '\n')
247
+ fsyncSync(fd)
248
+ } catch (error) {
249
+ // Never leave a half-written lock file behind: a reader would see invalid
250
+ // JSON and could only recover by waiting out the (1h) stale threshold.
251
+ try { closeSync(fd) } catch {}
252
+ try { unlinkSync(this.path) } catch {}
253
+ throw error
254
+ }
255
+ closeSync(fd)
256
+ try { chmodSync(this.path, 0o600) } catch {}
257
+ return true
258
+ }
259
+
260
+ acquire() {
261
+ const deadline = Date.now() + this.timeoutMs
262
+ const started = Date.now()
263
+ for (;;) {
264
+ if (this._create()) {
265
+ this._held = true
266
+ this._startHeartbeat()
267
+ return this
268
+ }
269
+ const info = readInstanceLock(this.home)
270
+ if (info && instanceLockIsStale(info, { staleMs: this.staleMs })) {
271
+ if (reclaimStaleLock({ path: this.path, expected: info, staleMs: this.staleMs, timeoutMs: this.timeoutMs, pollMs: this.pollMs })) continue
272
+ }
273
+ const now = Date.now()
274
+ if (now >= deadline) {
275
+ throw new DatabaseLockedError({ lockPath: this.path, holder: info?.record ?? null, waitedMs: now - started, timeoutMs: this.timeoutMs })
276
+ }
277
+ sleepSync(Math.max(1, Math.min(this.pollMs, deadline - now)))
278
+ }
279
+ }
280
+
281
+ /** Refresh the lock mtime so long-lived holders are not age-reclaimed. */
282
+ refresh() {
283
+ if (!this._held) return false
284
+ const info = readInstanceLock(this.home)
285
+ if (!info?.record || info.record.pid !== this.record.pid || info.record.startedAt !== this.record.startedAt) {
286
+ this._stopHeartbeat()
287
+ this._held = false
288
+ return false
289
+ }
290
+ const now = new Date()
291
+ try { utimesSync(this.path, now, now) } catch { this._stopHeartbeat() }
292
+ return true
293
+ }
294
+
295
+ _startHeartbeat() {
296
+ if (this._heartbeat || this.staleMs < 60_000) return
297
+ this._heartbeat = setInterval(() => this.refresh(), heartbeatIntervalMs(this.staleMs))
298
+ if (typeof this._heartbeat.unref === 'function') this._heartbeat.unref()
299
+ }
300
+
301
+ _stopHeartbeat() {
302
+ if (!this._heartbeat) return
303
+ clearInterval(this._heartbeat)
304
+ this._heartbeat = null
305
+ }
306
+
307
+ /** Release the lock; only the exact record this process wrote is removed. */
308
+ release() {
309
+ this._stopHeartbeat()
310
+ if (!this._held) return false
311
+ this._held = false
312
+ let info
313
+ try { info = readInstanceLock(this.home) } catch { return false }
314
+ if (!info?.record) return false
315
+ if (info.record.pid !== this.record.pid || info.record.startedAt !== this.record.startedAt) return false
316
+ try {
317
+ unlinkSync(this.path)
318
+ return true
319
+ } catch (error) {
320
+ return error?.code === 'ENOENT'
321
+ }
322
+ }
323
+ }
324
+
325
+ /** Take the single-writer lock for a HOME; throws E_DB_LOCKED after the wait budget. */
326
+ export function acquireInstanceLock({ home, command = '', timeoutMs, staleMs, pollMs } = {}) {
327
+ if (!home) throw new Error('acquireInstanceLock requires a home directory')
328
+ const lock = new InstanceLock({ home, command, timeoutMs, staleMs, pollMs })
329
+ return lock.acquire()
330
+ }
331
+
332
+ /** Throw E_DB_CORRUPT for an existing 0-byte / non-file database before SQLite touches it. */
333
+ export function assertDatabaseFileUsable(path) {
334
+ if (!path || path === ':memory:') return
335
+ let stat
336
+ try {
337
+ stat = statSync(path)
338
+ } catch (error) {
339
+ if (error?.code === 'ENOENT') return
340
+ throw error
341
+ }
342
+ if (stat.isDirectory()) throw new DatabaseCorruptError(path, 'the path is a directory, not a SQLite database file')
343
+ if (stat.size === 0) throw new DatabaseCorruptError(path, 'the database file is 0 bytes (truncated, or an interrupted first-time initialisation)')
344
+ }
345
+
346
+ function isCorruptSqliteError(error) {
347
+ return /file is not a database|database disk image is malformed|malformed database|not a database/i.test(String(error?.message ?? error))
348
+ }
349
+
45
350
  // Ledger tables are written as a whole snapshot by save(). The id column lets
46
351
  // save() merge with rows other processes committed after our load().
47
352
  const LEDGER_TABLES = [
@@ -222,19 +527,32 @@ export class SqliteStore {
222
527
  this.busyTimeoutMs = busyTimeoutMs
223
528
  this._transactionDepth = 0
224
529
  this._baselineIds = null
225
- this.db = readOnly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path)
226
- // P0-1: sqlite only applies busy_timeout to statements that run after the
227
- // pragma is set; concurrent first-opens used to fail on journal_mode=WAL
228
- // because busy_timeout was set afterwards.
229
- this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(Number(busyTimeoutMs) || 0))}`)
230
- if (readOnly) {
231
- if (checkIntegrity) this.assertIntegrity()
232
- return
530
+ // P2-2 (0.2.1): an existing 0-byte file is treated as corrupt instead of a
531
+ // brand-new database. Before this, SQLite turned it into an empty schema and
532
+ // every command reported "no data" while silently rebuilding the ledger.
533
+ assertDatabaseFileUsable(path)
534
+ try {
535
+ this.db = readOnly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path)
536
+ // P0-1: sqlite only applies busy_timeout to statements that run after the
537
+ // pragma is set; concurrent first-opens used to fail on journal_mode=WAL
538
+ // because busy_timeout was set afterwards.
539
+ this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(Number(busyTimeoutMs) || 0))}`)
540
+ if (readOnly) {
541
+ if (checkIntegrity) this.assertIntegrity()
542
+ return
543
+ }
544
+ this.enableWal()
545
+ this.db.exec('PRAGMA secure_delete = ON')
546
+ this.db.exec('PRAGMA synchronous = NORMAL')
547
+ this.initializeSchema()
548
+ } catch (error) {
549
+ try { this.db?.close() } catch {}
550
+ if (error?.code === 'E_DB_CORRUPT') throw error
551
+ if (isCorruptSqliteError(error)) {
552
+ throw new DatabaseCorruptError(path, `SQLite reports that the file is not a valid database (${String(error?.message ?? error).slice(0, 200)})`)
553
+ }
554
+ throw error
233
555
  }
234
- this.enableWal()
235
- this.db.exec('PRAGMA secure_delete = ON')
236
- this.db.exec('PRAGMA synchronous = NORMAL')
237
- this.initializeSchema()
238
556
  }
239
557
 
240
558
  /** Full-database integrity check; explicit because it is O(database size). */
@@ -546,16 +864,34 @@ CREATE TABLE IF NOT EXISTS task_runs (
546
864
  }
547
865
 
548
866
  /**
549
- * P0-2 (tick N+1 removal): the newest `limit` outcomes per commitment in one
550
- * query (window function over idx_nudges_commitment_at). Replaces one
551
- * listCommitmentNudges() round-trip per commitment.
867
+ * P0-2 (tick N+1 removal): the newest `limit` outcomes per commitment.
868
+ *
869
+ * P2-2 (0.2.1): the original form windowed over the WHOLE nudges table
870
+ * (scan + temp b-tree sort), so every tick paid for the entire nudge history:
871
+ * 271ms at 200k rows and growing linearly. Tick only needs outcomes for the
872
+ * commitments it is about to nudge, so callers that know that set pass
873
+ * `commitmentIds`; the read then becomes `limit` index seeks per commitment on
874
+ * idx_nudges_commitment_at, bounded by the candidate set instead of the
875
+ * history size. Passing no ids keeps the historical whole-table map for
876
+ * callers/tests that need it.
552
877
  */
553
- recentNudgeOutcomes(limit = 3) {
878
+ recentNudgeOutcomes(limit = 3, commitmentIds = null) {
879
+ const newest = Math.max(1, Math.floor(Number(limit) || 3))
880
+ const byCommitment = new Map()
881
+ if (commitmentIds) {
882
+ const ids = [...new Set(commitmentIds)]
883
+ if (!ids.length) return byCommitment
884
+ const statement = this.db.prepare('SELECT outcome FROM nudges WHERE commitment_id = ? ORDER BY at DESC LIMIT ?')
885
+ for (const id of ids) {
886
+ const rows = statement.all(id, newest)
887
+ if (rows.length) byCommitment.set(id, rows.map((row) => row.outcome))
888
+ }
889
+ return byCommitment
890
+ }
554
891
  const rows = this.db.prepare(`SELECT commitment_id, outcome, at FROM (
555
892
  SELECT commitment_id, outcome, at, ROW_NUMBER() OVER (PARTITION BY commitment_id ORDER BY at DESC) AS rn
556
893
  FROM nudges
557
- ) WHERE rn <= ?`).all(limit)
558
- const byCommitment = new Map()
894
+ ) WHERE rn <= ?`).all(newest)
559
895
  for (const row of rows) {
560
896
  const list = byCommitment.get(row.commitment_id)
561
897
  if (list) list.push(row.outcome)
package/lib/sync.js CHANGED
@@ -11,7 +11,8 @@
11
11
  */
12
12
  import { chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
13
13
  import { createHash } from 'node:crypto'
14
- import { basename, join } from 'node:path'
14
+ import { basename, dirname, join } from 'node:path'
15
+ import { DatabaseSync } from 'node:sqlite'
15
16
  import { decryptJson, encryptJson, isVaultEnvelope } from './vault.js'
16
17
 
17
18
  /** fsync a directory entry so a rename survives a crash. */
@@ -37,6 +38,45 @@ function writeAtomic(file, data, { mode = 0o600 } = {}) {
37
38
  fsyncDir(join(file, '..'))
38
39
  }
39
40
 
41
+ const PULL_TMP_PREFIX = '.advisers-pull-verify-'
42
+
43
+ /**
44
+ * Verify that a database file is a structurally valid SQLite database before it
45
+ * is allowed to replace the main database (robustness audit P1-4, 2026-11-17).
46
+ *
47
+ * The snapshot SHA-256 only proves the envelope payload is self-consistent; a
48
+ * byte-corrupted payload is still "consistent" after re-encryption and used to
49
+ * be installed as the live library. PRAGMA quick_check is O(file) and catches
50
+ * corrupt b-trees/pages. The original file is only opened read-only.
51
+ */
52
+ function assertDatabaseIntegrity(file) {
53
+ let db
54
+ try {
55
+ // A 0-byte file is a valid "empty database" to SQLite (quick_check says ok),
56
+ // so a truncated snapshot used to replace the live library silently. Treat it
57
+ // as corrupt (robustness audit P2-2 / P1-4) and keep the local database.
58
+ if (statSync(file).size === 0) throw new Error('E_DB_CORRUPT: the snapshot database is 0 bytes (truncated)')
59
+ db = new DatabaseSync(file, { readOnly: true })
60
+ const row = db.prepare('PRAGMA quick_check').get()
61
+ const verdict = String(row?.quick_check ?? 'unknown').slice(0, 120)
62
+ if (verdict !== 'ok') throw new Error(`quick_check reported ${verdict}`)
63
+ } catch (error) {
64
+ throw new Error(`snapshot database failed the integrity check: ${String(error?.message ?? error).slice(0, 200)}`)
65
+ } finally {
66
+ try { db?.close() } catch {}
67
+ }
68
+ }
69
+
70
+ /** Put the pre-pull database (and its WAL/SHM siblings) back after a failed replace. */
71
+ function restoreBackup(backup, dbPath) {
72
+ copyFileSync(backup, dbPath)
73
+ for (const suffix of ['-wal', '-shm']) {
74
+ if (existsSync(backup + suffix)) copyFileSync(backup + suffix, dbPath + suffix)
75
+ else { try { rmSync(dbPath + suffix) } catch {} }
76
+ }
77
+ try { chmodSync(dbPath, 0o600) } catch {}
78
+ }
79
+
40
80
  export const SYNC_PREFIX = 'advisers-'
41
81
  export const SYNC_SUFFIX = '.enc.json'
42
82
 
@@ -113,17 +153,53 @@ export function pullSnapshot({ dir, dbPath, passphrase, file, force = false, loc
113
153
  if (localAt > snapshotAt) throw new Error(`local database was written after snapshot ${chosen.name} (local ${new Date(localAt).toISOString()} > snapshot ${new Date(snapshotAt).toISOString()}); refusing to overwrite. If those local writes matter, back them up/export them first; re-run with --force to overwrite anyway (a backup is kept).`)
114
154
  }
115
155
  }
156
+ const parent = dirname(dbPath)
157
+ mkdirSync(parent, { recursive: true, mode: 0o700 })
158
+ // Stage the snapshot bytes next to the live database and verify them BEFORE
159
+ // anything replaces the library (robustness audit P1-4). The backup copy is
160
+ // taken first and kept on every failure path; the live WAL/SHM are only
161
+ // removed once the staged database has passed the integrity check.
162
+ const tmp = join(parent, `${PULL_TMP_PREFIX}${process.pid}-${Math.random().toString(36).slice(2, 8)}`)
116
163
  let backup = null
117
- if (existsSync(dbPath)) {
118
- backup = `${dbPath}.before-sync-${Date.now()}`
119
- copyFileSync(dbPath, backup)
120
- for (const suffix of ['-wal', '-shm']) {
121
- try { if (existsSync(dbPath + suffix)) copyFileSync(dbPath + suffix, backup + suffix) } catch {}
164
+ try {
165
+ writeFileSync(tmp, bytes, { mode: 0o600, flush: true })
166
+ const hadLocal = existsSync(dbPath)
167
+ if (hadLocal) {
168
+ backup = `${dbPath}.before-sync-${Date.now()}`
169
+ copyFileSync(dbPath, backup)
170
+ for (const suffix of ['-wal', '-shm']) {
171
+ try { if (existsSync(dbPath + suffix)) copyFileSync(dbPath + suffix, backup + suffix) } catch {}
172
+ }
173
+ }
174
+ try {
175
+ assertDatabaseIntegrity(tmp)
176
+ } catch (error) {
177
+ throw new Error(`refusing to replace the local database: ${error.message}`)
122
178
  }
123
179
  for (const suffix of ['-wal', '-shm']) { try { rmSync(dbPath + suffix) } catch {} }
124
- } else {
125
- mkdirSync(join(dbPath, '..'), { recursive: true, mode: 0o700 })
180
+ try {
181
+ // Rename the verified bytes into place (same directory: atomic).
182
+ renameSync(tmp, dbPath)
183
+ try { chmodSync(dbPath, 0o600) } catch {}
184
+ fsyncDir(parent)
185
+ } catch (error) {
186
+ // A failure after the rename must never leave a half-installed library:
187
+ // restore the pre-pull database and keep the backup for inspection.
188
+ let restored = false
189
+ try {
190
+ if (hadLocal && backup) {
191
+ restoreBackup(backup, dbPath)
192
+ restored = true
193
+ } else {
194
+ rmSync(dbPath, { force: true })
195
+ restored = true
196
+ }
197
+ } catch {}
198
+ const hint = restored ? 'the previous local database was restored' : 'restore the backup manually from ' + String(backup)
199
+ throw new Error(`failed to install the verified snapshot; ${hint}: ${error.message}`)
200
+ }
201
+ return { file: chosen.name, sha256, changed: true, backup, device: payload.device, createdAt: payload.createdAt }
202
+ } finally {
203
+ try { if (existsSync(tmp)) rmSync(tmp) } catch {}
126
204
  }
127
- writeAtomic(dbPath, bytes, { mode: 0o600 })
128
- return { file: chosen.name, sha256, changed: true, backup, device: payload.device, createdAt: payload.createdAt }
129
205
  }
package/lib/timestamp.js CHANGED
@@ -10,6 +10,31 @@ import { spawn } from 'node:child_process'
10
10
  import { statSync } from 'node:fs'
11
11
  import { isAbsolute, relative, resolve } from 'node:path'
12
12
 
13
+ /**
14
+ * Environment for the adapter subprocess: an explicit allowlist.
15
+ *
16
+ * The adapter is a local third-party program (RFC3161 client / signer).
17
+ * Inheriting process.env would hand it every Advisers secret — ADVISERS_API_KEY,
18
+ * ADVISERS_AUDIT_KEY (the audit HMAC key), vault/sync/export passphrases and
19
+ * provider URLs (security audit SEC2-03, 2026-11-17). Only OS/runtime basics
20
+ * needed to start a program are passed through; credentials never are.
21
+ */
22
+ const ADAPTER_ENV_KEYS = Object.freeze([
23
+ 'PATH', 'Path', 'PATHEXT', 'COMSPEC', 'SYSTEMROOT', 'SystemRoot', 'windir',
24
+ 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA',
25
+ 'TEMP', 'TMP', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', 'TZ',
26
+ 'PSModulePath',
27
+ ])
28
+
29
+ function adapterEnv(source = process.env) {
30
+ const env = {}
31
+ for (const key of ADAPTER_ENV_KEYS) {
32
+ const value = source?.[key]
33
+ if (typeof value === 'string' && value) env[key] = value
34
+ }
35
+ return env
36
+ }
37
+
13
38
  export const MAX_PROOF_BYTES = 200_000
14
39
 
15
40
  export function timestampConfigured() {
@@ -30,7 +55,7 @@ export async function runLocalTimestamp(file, { cmd = process.env.ADVISERS_TIMES
30
55
  if (!cmd) throw new Error('timestamp is not configured; set ADVISERS_TIMESTAMP_CMD to a local timestamp/signing executable')
31
56
  const abs = assertProofFile(file, cwd)
32
57
  return await new Promise((resolvePromise, reject) => {
33
- const child = spawn(cmd, [abs], { stdio: ['ignore', 'pipe', 'pipe'], timeout: timeoutMs, windowsHide: true })
58
+ const child = spawn(cmd, [abs], { stdio: ['ignore', 'pipe', 'pipe'], timeout: timeoutMs, windowsHide: true, env: adapterEnv() })
34
59
  let out = '', err = ''
35
60
  child.stdout.on('data', (b) => { out += b.toString('utf8'); if (out.length > MAX_PROOF_BYTES) { child.kill(); reject(new Error(`timestamp proof exceeds ${MAX_PROOF_BYTES} bytes`)) } })
36
61
  child.stderr.on('data', (b) => { err += b.toString('utf8') })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "advisers",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "A staff of AI advisers: a cordis-native personal secretary runtime with scoped memory, commitments, and reviewable routines.",
5
5
  "keywords": [
6
6
  "cordis",
@@ -20,7 +20,8 @@
20
20
  },
21
21
  "exports": {
22
22
  ".": "./index.js",
23
- "./package.json": "./package.json"
23
+ "./package.json": "./package.json",
24
+ "./lib/safety/index.js": "./lib/safety/index.js"
24
25
  },
25
26
  "files": [
26
27
  "index.js",
@@ -34,8 +35,8 @@
34
35
  ],
35
36
  "dependencies": {
36
37
  "@pdf-lib/fontkit": "^1.1.1",
37
- "advisers-core": "0.2.0",
38
- "advisers-policy-strict": "0.2.0",
38
+ "advisers-core": "0.2.1",
39
+ "advisers-policy-strict": "0.2.1",
39
40
  "jszip": "^3.10.2",
40
41
  "pdf-lib": "^1.17.1",
41
42
  "pdfjs-dist": "^6.5.438"
@@ -53,13 +54,13 @@
53
54
  "access": "public"
54
55
  },
55
56
  "engines": {
56
- "node": ">=22.13"
57
+ "node": ">=22.16"
57
58
  },
58
59
  "scripts": {
59
60
  "test": "node --experimental-strip-types --test test/*.test.js"
60
61
  },
61
62
  "peerDependencies": {
62
- "advisers-office": "0.2.0"
63
+ "advisers-office": "0.2.1"
63
64
  },
64
65
  "peerDependenciesMeta": {
65
66
  "advisers-office": {