@bom0792/herdgate 0.9.39 → 0.9.40

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom0792/herdgate",
3
- "version": "0.9.39",
3
+ "version": "0.9.40",
4
4
  "description": "Cloud relay hub for herdr-core: every machine dials out, phones and browsers follow (PWA + SSH leg, E2E payloads).",
5
5
  "type": "module",
6
6
  "engines": {
@@ -9,7 +9,7 @@
9
9
  import { execFileSync } from 'node:child_process';
10
10
  import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
11
11
  import { dirname, join } from 'node:path';
12
- import { readSpawns } from '../../experiments/pi-spawn/registry.mjs';
12
+ import { readSpawns } from './spawn-registry.mjs';
13
13
  import { findReceipt } from './pi-receipts.mjs';
14
14
 
15
15
  const note = (line) => console.error(`herdgate pi-wake: ${line}`);
@@ -0,0 +1,23 @@
1
+ export const MAX_SPAWNS: number;
2
+ export const COMPACT_AT: number;
3
+ export const SPAWN_NAME: RegExp;
4
+
5
+ export interface SpawnRecord {
6
+ id: string;
7
+ sessionId: string;
8
+ paneId: string;
9
+ name: string;
10
+ parentSessionId?: string;
11
+ cwd?: string;
12
+ ts: number;
13
+ status?: string;
14
+ restoredAt?: number;
15
+ [key: string]: unknown;
16
+ }
17
+
18
+ export function spawnsFile(base: string): string;
19
+ export function readSpawns(file: string): SpawnRecord[];
20
+ export function recordSpawn(base: string, spawn: SpawnRecord): SpawnRecord & { status: string };
21
+ export function updateSpawn(base: string, id: string, patch: Partial<SpawnRecord>): SpawnRecord | null;
22
+ export function findSpawn(base: string, ref: string): SpawnRecord | null;
23
+ export function spawnBase(): string;
@@ -0,0 +1,216 @@
1
+ // Parent→child spawn registry for Herdgate-controlled Pi agents (experiment).
2
+ // One id serves the whole chain: receipt request id == Pi --session-id, so a
3
+ // controller knows the child's session identity the moment it spawns and can
4
+ // reopen it later with the same flag. Stores only ids/panes/status — no briefs.
5
+ //
6
+ // State hardening (miko-misa/herdr-portfwd state.rs lessons, deep/portfwd.md):
7
+ // - a damaged file never reads as empty: the reader throws with the FILE NAMED
8
+ // (the StateError::Damaged refuse); callers warn and continue on the lines
9
+ // that did parse instead of silently inventing a smaller registry;
10
+ // - writes are atomic through an O_EXCL temp with an unguessable name + rename
11
+ // (a symlink planted at a guessable temp path must not be written through);
12
+ // - records sort by a stable key before every write, so the same set of records
13
+ // serializes to byte-identical files across processes (diffable by a human);
14
+ // - spawnBase() refuses a base dir owned by another uid or writable by
15
+ // group/others, naming the dir: registry records decide which panes get
16
+ // closed, and a dir some other uid can write into is a takeover.
17
+ import { randomBytes } from 'node:crypto';
18
+ import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
19
+ import { dirname, join } from 'node:path';
20
+ import { journalBase, scopeFor } from './pi-receipts.mjs';
21
+
22
+ export const MAX_SPAWNS = 200;
23
+ export const COMPACT_AT = 300;
24
+ export const SPAWN_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
25
+ const PANE = /^[\w:.-]{1,32}$/;
26
+ // Pi session ids are v7 (SDK-generated); receipt request ids are v4. Both are one-id
27
+ // chain material, so the registry accepts either shape.
28
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
29
+
30
+ export function spawnsFileFor(base, cwd) {
31
+ return join(base, scopeFor(cwd), 'spawns.jsonl');
32
+ }
33
+
34
+ export function spawnsFile(base) {
35
+ return spawnsFileFor(base, process.cwd());
36
+ }
37
+
38
+ function valid(entry) {
39
+ // Controller entries carry the pane they run in; self-registered ones (an agent
40
+ // declaring its own parent, e.g. a worker job session) have no pane until restored.
41
+ const paneOk = entry?.self === true
42
+ ? (entry.paneId === undefined || PANE.test(entry.paneId))
43
+ : PANE.test(entry?.paneId ?? '');
44
+ return Boolean(entry && UUID.test(entry.id ?? '') && typeof entry.sessionId === 'string' && entry.sessionId
45
+ && paneOk && SPAWN_NAME.test(entry.name ?? '')
46
+ && (entry.parentSessionId === undefined || typeof entry.parentSessionId === 'string')
47
+ && (entry.cwd === undefined || typeof entry.cwd === 'string')
48
+ && (entry.sessionFile === undefined || typeof entry.sessionFile === 'string')
49
+ && Number.isFinite(entry.ts));
50
+ }
51
+
52
+ /** A damaged registry file. The message names the file — a corrupt line must
53
+ * never read as "no children" — and `.entries` carries the lines that DID
54
+ * parse, so a caller can warn and keep going on the valid portion. */
55
+ export class DamagedSpawnsError extends Error {
56
+ constructor(file, bad, entries) {
57
+ super(`spawns file ${file} is damaged: ${bad} unreadable line(s) — refusing to read it as if it were fine`);
58
+ this.name = 'DamagedSpawnsError';
59
+ this.file = file;
60
+ this.bad = bad;
61
+ this.entries = entries;
62
+ }
63
+ }
64
+
65
+ /** Read one registry file. Missing file → [] (a fresh workspace is not damage).
66
+ * Any line that fails to parse or pass the schema → DamagedSpawnsError naming
67
+ * the file (the entwurf crash-don't-warn rule for malformed records). */
68
+ export function readSpawns(file) {
69
+ let raw;
70
+ try { raw = readFileSync(file, 'utf8'); }
71
+ catch (error) {
72
+ if (error?.code === 'ENOENT') return [];
73
+ throw error;
74
+ }
75
+ const entries = [];
76
+ let bad = 0;
77
+ for (const line of raw.split('\n')) {
78
+ if (!line) continue;
79
+ let parsed = null;
80
+ try { parsed = JSON.parse(line); } catch { parsed = null; }
81
+ if (valid(parsed)) entries.push(parsed); else bad++;
82
+ }
83
+ if (bad > 0) throw new DamagedSpawnsError(file, bad, entries);
84
+ return entries;
85
+ }
86
+
87
+ /** Warn-and-continue read for callers that must survive a damaged scope: prints
88
+ * the named error once, returns the valid records. Writers use this so one
89
+ * corrupt line compacts away on the next rewrite instead of blocking work. */
90
+ export function readSpawnsTolerant(file, warn = console.error) {
91
+ try {
92
+ return readSpawns(file);
93
+ } catch (error) {
94
+ if (error instanceof DamagedSpawnsError) {
95
+ warn(`[spawn-registry] ${error.message}; continuing with ${error.entries.length} valid record(s)`);
96
+ return error.entries;
97
+ }
98
+ throw error;
99
+ }
100
+ }
101
+
102
+ // Byte-stable output (state.rs:471): dedupe by id happens at the call sites,
103
+ // the write sorts by (ts, id) so the same records always produce the same
104
+ // bytes regardless of which process or insertion order produced them.
105
+ const byStableKey = (a, b) =>
106
+ a.ts !== b.ts ? (a.ts < b.ts ? -1 : 1) : (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
107
+
108
+ let tempSeq = 0;
109
+ function write(file, entries) {
110
+ mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
111
+ const body = [...entries].sort(byStableKey).map(entry => JSON.stringify(entry)).join('\n') + '\n';
112
+ // O_EXCL ('wx') + an unguessable name: a symlink somebody planted at a
113
+ // guessable temp path cannot be written through (state.rs:700-718). The
114
+ // rename then replaces the registry atomically — no window where it is gone.
115
+ const tmp = `${file}.tmp-${process.pid}-${tempSeq++}-${randomBytes(8).toString('hex')}`;
116
+ const fd = openSync(tmp, 'wx', 0o600);
117
+ try {
118
+ writeFileSync(fd, body);
119
+ } catch (error) {
120
+ try { unlinkSync(tmp); } catch { /* best effort cleanup */ }
121
+ throw error;
122
+ } finally {
123
+ try { closeSync(fd); } catch { /* already closed on the error path */ }
124
+ }
125
+ try {
126
+ renameSync(tmp, file);
127
+ } catch (error) {
128
+ try { unlinkSync(tmp); } catch { /* best effort cleanup */ }
129
+ throw error;
130
+ }
131
+ }
132
+
133
+ /** Record (or supersede) one spawn. The same id updates in place. */
134
+ export function recordSpawn(base, spawn) {
135
+ if (!valid(spawn)) throw new Error('invalid_spawn');
136
+ const file = spawnsFile(base);
137
+ let entries = readSpawnsTolerant(file).filter(entry => entry.id !== spawn.id);
138
+ entries.push({ status: 'running', ...spawn });
139
+ if (entries.length > COMPACT_AT) entries = entries.slice(-MAX_SPAWNS);
140
+ write(file, entries);
141
+ return { status: 'running', ...spawn };
142
+ }
143
+
144
+ /** Patch one record by id (restore/retire); returns the updated record or null. */
145
+ export function updateSpawn(base, id, patch) {
146
+ const file = spawnsFile(base);
147
+ const entries = readSpawnsTolerant(file);
148
+ let updated = null;
149
+ for (let i = 0; i < entries.length; i++) {
150
+ if (entries[i].id !== id) continue;
151
+ entries[i] = { ...entries[i], ...patch };
152
+ updated = entries[i];
153
+ }
154
+ if (!updated) return null;
155
+ write(file, entries);
156
+ return updated;
157
+ }
158
+
159
+ /** Find one record by id or name. A name can be shadowed by an orphan record
160
+ * (the 22/11 bug: a dead pane's newer record hid the live one), so when the
161
+ * caller passes the pane ids herdr still lists, a LIVE record wins over a
162
+ * newer orphan; ties and the no-liveness case resolve to the newest ts. An
163
+ * exact id is unique and never tie-broken. */
164
+ export function findSpawn(base, ref, livePaneIds = null) {
165
+ const entries = readSpawnsTolerant(spawnsFile(base));
166
+ const byId = entries.find(entry => entry.id === ref);
167
+ if (byId) return byId;
168
+ const named = entries.filter(entry => entry.name === ref);
169
+ if (!named.length) return null;
170
+ const live = livePaneIds ? new Set(livePaneIds) : null;
171
+ const liveNamed = live ? named.filter(entry => entry.paneId && live.has(entry.paneId)) : [];
172
+ const pool = liveNamed.length ? liveNamed : named;
173
+ return pool.reduce((best, entry) => (best && best.ts >= entry.ts ? best : entry), null);
174
+ }
175
+
176
+ /** Record an agent declaring its OWN parent (no controller pane involved). */
177
+ export function recordSelf(base, self) {
178
+ if (!self?.sessionId || !UUID.test(self.sessionId) || typeof self.parentSessionId !== 'string'
179
+ || !self.parentSessionId || !SPAWN_NAME.test(self.name ?? '')) throw new Error('invalid_self');
180
+ // One-id chain: a self-registered child serves as its own receipt request id.
181
+ // Scoped to the workspace the child runs in, so a controller sitting there sees it.
182
+ const spawn = { status: 'self', ...self, id: self.id ?? self.sessionId, self: true };
183
+ if (!valid(spawn)) throw new Error('invalid_self');
184
+ const file = spawnsFileFor(base, self.cwd ?? process.cwd());
185
+ let entries = readSpawnsTolerant(file).filter(entry => entry.id !== spawn.id);
186
+ entries.push(spawn);
187
+ if (entries.length > COMPACT_AT) entries = entries.slice(-MAX_SPAWNS);
188
+ write(file, entries);
189
+ return spawn;
190
+ }
191
+
192
+ export function spawnBase() {
193
+ const base = journalBase(); // same override + scope rules as the receipt journal
194
+ // state.rs:613-650: refuse a state dir another uid owns or that OTHERS can
195
+ // write into — the dir is NAMED in the error, never hidden behind a generic
196
+ // failure. Group-writable is the lenient direction the original teaches
197
+ // (state.rs:655): a dir we own gets tightened in place; one that cannot be
198
+ // tightened is refused exactly like a foreign dir. Without a POSIX uid/mode
199
+ // model (non-POSIX platforms) there is nothing equivalent to check.
200
+ if (typeof process.geteuid !== 'function') return base;
201
+ mkdirSync(base, { recursive: true, mode: 0o700 });
202
+ const meta = statSync(base);
203
+ const me = process.geteuid();
204
+ if (meta.uid !== me)
205
+ throw new Error(`spawn dir ${base} belongs to uid ${meta.uid}, not uid ${me} — refusing to use it`);
206
+ const mode = meta.mode & 0o777;
207
+ if (mode & 0o002)
208
+ throw new Error(`spawn dir ${base} has mode ${mode.toString(8).padStart(4, '0')} — others can write in it; refusing to use it`);
209
+ if (mode & 0o020) {
210
+ chmodSync(base, mode & ~0o020); // auto-tighten our own dir (state.rs:655)
211
+ const after = statSync(base).mode & 0o777;
212
+ if (after & 0o022)
213
+ throw new Error(`spawn dir ${base} has mode ${after.toString(8).padStart(4, '0')} — group/others can write in it and it cannot be tightened; refusing to use it`);
214
+ }
215
+ return base;
216
+ }