dsh-chief 1.2.0 → 1.3.0

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/board-store.js ADDED
@@ -0,0 +1,392 @@
1
+ /**
2
+ * board-store.js
3
+ *
4
+ * Board file persistence, in-memory cache, cross-process locking, and session board views.
5
+ */
6
+
7
+ import fs from 'node:fs'
8
+ import path from 'node:path'
9
+ import os from 'node:os'
10
+ import { threadId } from 'node:worker_threads'
11
+ import {
12
+ BOARD_VERSION,
13
+ nowMs,
14
+ emptyBoard,
15
+ str,
16
+ BOUND_FIELDS,
17
+ BOUND_CAP,
18
+ normalizeBounds,
19
+ normalizeBoard,
20
+ } from './board-schema.js'
21
+
22
+ export function createBoardStore(deps) {
23
+
24
+ const resolveRootSessionId = (...args) => deps.resolveRootSessionId(...args)
25
+
26
+ function pendingFile() {
27
+ return path.join(path.dirname(boardFile()), 'pending-transfer.json')
28
+ }
29
+
30
+ function readPending() {
31
+ try {
32
+ const raw = JSON.parse(fs.readFileSync(pendingFile(), 'utf8'))
33
+ return raw && typeof raw.text === 'string' && raw.text ? raw : null
34
+ } catch {
35
+ return null
36
+ }
37
+ }
38
+
39
+ function writePending(value) {
40
+ try {
41
+ fs.mkdirSync(path.dirname(pendingFile()), { recursive: true })
42
+ fs.writeFileSync(pendingFile(), JSON.stringify(value, null, 2), 'utf8')
43
+ return true
44
+ } catch {
45
+ return false
46
+ }
47
+ }
48
+
49
+ function clearPending() {
50
+ try {
51
+ fs.unlinkSync(pendingFile())
52
+ } catch {}
53
+ }
54
+
55
+ function pendingDeployFile() {
56
+ return path.join(path.dirname(boardFile()), 'pending-chief-deploy.json')
57
+ }
58
+
59
+ function readPendingDeploy() {
60
+ try {
61
+ const raw = JSON.parse(fs.readFileSync(pendingDeployFile(), 'utf8'))
62
+ return raw && typeof raw.fromSessionId === 'string' && raw.fromSessionId ? raw : null
63
+ } catch {
64
+ return null
65
+ }
66
+ }
67
+
68
+ function writePendingDeploy(value) {
69
+ try {
70
+ fs.mkdirSync(path.dirname(pendingDeployFile()), { recursive: true })
71
+ fs.writeFileSync(pendingDeployFile(), JSON.stringify(value, null, 2), 'utf8')
72
+ return true
73
+ } catch {
74
+ return false
75
+ }
76
+ }
77
+
78
+ function clearPendingDeploy() {
79
+ try {
80
+ fs.unlinkSync(pendingDeployFile())
81
+ } catch {}
82
+ }
83
+
84
+ function boardFile() {
85
+ const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
86
+ return path.join(home, 'chief', 'board.json')
87
+ }
88
+
89
+ /** One JSON board per Session (or shared across a subagent tree rooted at lead):
90
+ * %DSH_HOME%/chief/boards/<sid>.json. */
91
+ function sessionBoardFile(sessionId) {
92
+ const rootSid = resolveRootSessionId(sessionId)
93
+ const sid = String(rootSid || '').replace(/[^\w-]/g, '')
94
+ const dir = path.join(path.dirname(boardFile()), 'boards')
95
+ return sid ? path.join(dir, sid + '.json') : ''
96
+ }
97
+
98
+ function boardFileFor(sessionId) {
99
+ return sessionBoardFile(sessionId) || boardFile()
100
+ }
101
+
102
+ /* ------------------------------------------------------------------ storage */
103
+
104
+ /* Per-file caches keyed by path — one board per Session, one shared board for
105
+ * the global anchor/settings. */
106
+ const caches = new Map()
107
+
108
+ function loadBoard(file) {
109
+ file = file || boardFile()
110
+ const entry = caches.get(file) || { mtime: -1, board: null }
111
+ try {
112
+ const stat = fs.statSync(file)
113
+ if (entry.board && entry.mtime === stat.mtimeMs) return entry.board
114
+ const board = normalizeBoard(JSON.parse(fs.readFileSync(file, 'utf8')))
115
+ caches.set(file, { mtime: stat.mtimeMs, board })
116
+ return board
117
+ } catch {
118
+ return entry.board && entry.mtime === -1 ? entry.board : emptyBoard()
119
+ }
120
+ }
121
+
122
+ const LOCK_WAIT_MS = 10000
123
+
124
+ const LOCK_STALE_MS = 15000
125
+
126
+ const CONTENDED_LOCK_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY'])
127
+
128
+ const heldLocks = new Set()
129
+
130
+ const lockSleeper = new Int32Array(new SharedArrayBuffer(4))
131
+
132
+ function sleepSync(ms) {
133
+ try {
134
+ Atomics.wait(lockSleeper, 0, 0, ms)
135
+ } catch {}
136
+ }
137
+
138
+ function atomicRenameSync(tmp, file) {
139
+ let lastErr = null
140
+ for (let attempt = 0; attempt < 8; attempt += 1) {
141
+ try {
142
+ fs.renameSync(tmp, file)
143
+ return
144
+ } catch (err) {
145
+ lastErr = err
146
+ const code = err && err.code
147
+ if (code !== 'EPERM' && code !== 'EACCES' && code !== 'EBUSY' && code !== 'ENOENT') {
148
+ break
149
+ }
150
+ if (code === 'ENOENT') {
151
+ try {
152
+ fs.mkdirSync(path.dirname(file), { recursive: true })
153
+ } catch {}
154
+ }
155
+ sleepSync(2 + attempt * 2)
156
+ }
157
+ }
158
+ try {
159
+ if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
160
+ } catch {}
161
+ if (lastErr) throw lastErr
162
+ }
163
+
164
+ function saveBoard(board, file) {
165
+ file = file || boardFile()
166
+ board.version = BOARD_VERSION
167
+ board.updatedAt = nowMs()
168
+ fs.mkdirSync(path.dirname(file), { recursive: true })
169
+ const tmp = `${file}.${process.pid}.${threadId}.${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 8)}.tmp`
170
+ fs.writeFileSync(tmp, JSON.stringify(board, null, 2), 'utf8')
171
+ atomicRenameSync(tmp, file)
172
+ let mtime = -1
173
+ try {
174
+ mtime = fs.statSync(file).mtimeMs
175
+ } catch {}
176
+ caches.set(file, { mtime, board })
177
+ return board
178
+ }
179
+
180
+ /* ----------------------------------------------------------------- write lock */
181
+
182
+ /* Every mutation is a read-modify-write of one JSON file. `rename` makes the
183
+ * write itself atomic, but nothing stops two writers from reading the same
184
+ * board, each appending their own entry, and the second rename silently
185
+ * discarding the first one's task, note or memory line. A turn-stopping
186
+ * listener and a browser route land in the same Session board often enough to
187
+ * lose data that way, so the whole read-modify-write runs under
188
+ * `<file>.lock`, created with O_EXCL (works across processes, worker_threads,
189
+ * and across the host/browser halves). */
190
+
191
+ /** Take the board lock. Returns a release function; always call it in a finally.
192
+ * Nested calls on the same path return a no-op release instead of deadlocking:
193
+ * every holder here is synchronous, so "already held" can only mean "held by
194
+ * my own call stack". */
195
+ function acquireBoardLock(file) {
196
+ file = file || boardFile()
197
+ if (heldLocks.has(file)) return () => {}
198
+ const lock = file + '.lock'
199
+ try {
200
+ fs.mkdirSync(path.dirname(lock), { recursive: true })
201
+ } catch {}
202
+ const deadline = Date.now() + LOCK_WAIT_MS
203
+ for (;;) {
204
+ try {
205
+ const fd = fs.openSync(lock, 'wx')
206
+ try {
207
+ fs.writeSync(fd, `${process.pid}:${threadId}`)
208
+ } catch {}
209
+ fs.closeSync(fd)
210
+ heldLocks.add(file)
211
+ return () => {
212
+ heldLocks.delete(file)
213
+ try {
214
+ fs.unlinkSync(lock)
215
+ } catch {}
216
+ }
217
+ } catch (error) {
218
+ const code = error && error.code
219
+ if (code === 'ENOENT' && Date.now() < deadline) {
220
+ try {
221
+ fs.mkdirSync(path.dirname(lock), { recursive: true })
222
+ } catch {}
223
+ sleepSync(2)
224
+ continue
225
+ }
226
+ if (!error || !CONTENDED_LOCK_CODES.has(code)) {
227
+ // Best effort: an unwritable lock path must not fail every board write.
228
+ // The rename alone is still atomic, so the only loss is serialisation.
229
+ heldLocks.add(file)
230
+ return () => heldLocks.delete(file)
231
+ }
232
+ if (Date.now() >= deadline) {
233
+ // A wedged holder must not freeze the board for the rest of the
234
+ // session: break it once and continue.
235
+ try {
236
+ fs.unlinkSync(lock)
237
+ } catch {}
238
+ heldLocks.add(file)
239
+ return () => heldLocks.delete(file)
240
+ }
241
+ if (code === 'EEXIST') {
242
+ try {
243
+ const stat = fs.statSync(lock)
244
+ if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
245
+ fs.unlinkSync(lock)
246
+ continue
247
+ }
248
+ } catch {}
249
+ }
250
+ sleepSync(2 + Math.floor(Math.random() * 4))
251
+ }
252
+ }
253
+ }
254
+
255
+ /** Run one read-modify-write under the lock, with a cache-invalidated read so
256
+ * the board it mutates is the one currently on disk. */
257
+ function withBoardLock(file, run) {
258
+ const target = file || boardFile()
259
+ const release = acquireBoardLock(target)
260
+ caches.delete(target)
261
+ try {
262
+ return run()
263
+ } finally {
264
+ release()
265
+ }
266
+ }
267
+
268
+ /**
269
+ * The board a Session gets to READ: its own, plus the limited things that are
270
+ * deliberately machine-wide. Writes never go through here — they always hit the
271
+ * raw per-session file, so this view can never leak one conversation's work
272
+ * into another one.
273
+ *
274
+ * What crosses the boundary, and why:
275
+ * - notes: all of them, anchors first. A lesson pinned in one conversation is
276
+ * exactly the thing that must survive into the next one, and title-dedupe
277
+ * keeps the session's own copy when it has one. Every other note on the
278
+ * shared board crosses too, because a write nobody can read back is
279
+ * write-only storage: demoting an anchor past the cap used to erase its
280
+ * lesson from every panel, which is the opposite of what the cap promises.
281
+ * Each inherited note carries shared:true, so the panel can send its edit
282
+ * and its delete to the board the note actually lives on instead of the
283
+ * session board, where the host would answer "no such note".
284
+ * - bounds: always, and only, the shared list. Bounds are standing
285
+ * instructions from the operator ("don't commit", "install_bundle dies with
286
+ * EPERM"); a fresh conversation that cannot see them starts by breaking
287
+ * them. The panel edits that one shared list, so a session's seeded copy is
288
+ * a snapshot, not a decision: handing it back would shadow every later edit.
289
+ * A stale operator instruction is worse than a missing one.
290
+ * - objective: only while the session has none of its own, same reasoning —
291
+ * a new conversation should know what the machine is working on, but as
292
+ * soon as it states its own goal the shared one is gone.
293
+ * - settings: never inherited here; autoInject/guardIdle are machine flags
294
+ * read straight off the shared board at their point of use.
295
+ */
296
+ function boardForSession(file) {
297
+ const board = loadBoard(file)
298
+ try {
299
+ if (file === boardFile()) {
300
+ const pinnedOnly = normalizeBounds(board.bounds)
301
+ return {
302
+ ...board,
303
+ bounds: pinnedOnly,
304
+ pinnedBounds: pinnedOnly,
305
+ localBounds: { allowed: [], forbidden: [], notes: [] },
306
+ inherited: { anchors: 0, notes: 0, bounds: false, objective: false },
307
+ }
308
+ }
309
+ const shared = loadBoard()
310
+ const out = { ...board }
311
+ const inherited = { anchors: 0, notes: 0, bounds: false, objective: false }
312
+
313
+ const sharedNotes = shared.notes || []
314
+ const anchors = sharedNotes.filter(note => (note.tags || []).includes('anchor'))
315
+ const others = sharedNotes.filter(note => !(note.tags || []).includes('anchor'))
316
+ // Anchors first, then the rest: the front of the list is what a reader
317
+ // reaches first, and an anchor outranks a working note for that slot.
318
+ const carry = anchors.concat(others)
319
+ if (carry.length) {
320
+ const seen = new Set((board.notes || []).map(note => note.title))
321
+ const extra = carry.filter(note => !seen.has(note.title))
322
+ if (extra.length) {
323
+ out.notes = (board.notes || []).concat(extra.map(note => ({ ...note, session: note.session || '', shared: true })))
324
+ inherited.anchors = extra.filter(note => (note.tags || []).includes('anchor')).length
325
+ inherited.notes = extra.length
326
+ }
327
+ }
328
+
329
+ // Two-tier boundaries:
330
+ // 1) Pinned Global Shared (`shared.bounds`) — stamped with 📌, inherited across ALL tasks/conversations.
331
+ // 2) Task-Local (`board.bounds`) — applies ONLY to this root session & its subagent tree.
332
+ const pinnedBounds = normalizeBounds(shared.bounds)
333
+ const rawLocal = normalizeBounds(board.bounds)
334
+ const localBounds = { allowed: [], forbidden: [], notes: [] }
335
+ const mergedBounds = { allowed: [], forbidden: [], notes: [] }
336
+ for (const col of BOUND_FIELDS) {
337
+ const pinList = pinnedBounds[col] || []
338
+ const pinSet = new Set(pinList)
339
+ const localOnly = (rawLocal[col] || []).filter(item => !pinSet.has(item))
340
+ localBounds[col] = localOnly
341
+ mergedBounds[col] = pinList.concat(localOnly).slice(0, BOUND_CAP)
342
+ }
343
+ out.bounds = mergedBounds
344
+ out.pinnedBounds = pinnedBounds
345
+ out.localBounds = localBounds
346
+ inherited.bounds = Boolean(
347
+ pinnedBounds.allowed.length || pinnedBounds.forbidden.length || pinnedBounds.notes.length,
348
+ )
349
+
350
+ // "never wrote one" is not the same state as "wrote an empty one". The panel
351
+ // paints the borrowed objective into the very textarea a Session edits, so
352
+ // erasing it and pressing 保存目标 used to write objective:'' — and the next
353
+ // read handed the shared text straight back, leaving the box disobedient with
354
+ // no visible reason. objectiveAt is the record of "this Session stated an
355
+ // objective, even if the statement was 'none'": plan.set/objective.set stamp
356
+ // it, inheritance never does.
357
+ const statedOwn = typeof board.objectiveAt === 'number' && board.objectiveAt > 0
358
+ if (!str(board.objective, '') && !statedOwn) {
359
+ if (str(shared.objective, '')) {
360
+ out.objective = shared.objective
361
+ out.objectiveBy = shared.objectiveBy || ''
362
+ out.objectiveAt = shared.objectiveAt || 0
363
+ inherited.objective = true
364
+ }
365
+ }
366
+
367
+ out.inherited = inherited
368
+ return out
369
+ } catch {
370
+ return board
371
+ }
372
+ }
373
+
374
+ return {
375
+ pendingFile,
376
+ readPending,
377
+ writePending,
378
+ clearPending,
379
+ pendingDeployFile,
380
+ readPendingDeploy,
381
+ writePendingDeploy,
382
+ clearPendingDeploy,
383
+ boardFile,
384
+ sessionBoardFile,
385
+ boardFileFor,
386
+ loadBoard,
387
+ saveBoard,
388
+ acquireBoardLock,
389
+ withBoardLock,
390
+ boardForSession,
391
+ }
392
+ }