@bom0792/herdgate 0.9.36 → 0.9.38

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.
@@ -0,0 +1,319 @@
1
+ // Wake-on-settle: when a spawned child's receipt settles, wake the PARENT
2
+ // agent's pane with a one-line frame — the controller never polls, never holds
3
+ // a watch process; the alert arrives as its next input (the same pattern as
4
+ // scheduler wake frames). Spawn registry supplies the parent edge; herdr pane
5
+ // run delivers. The live path is the herdr [[events]] hook (server/wake-event.mjs):
6
+ // herdr observes the child, so wake survives a child that never arms or dies
7
+ // with its pane. Failures (blocked parent, gone pane, herdr down) log and drop
8
+ // — a missed wake is recoverable from the journal, a crash is not.
9
+ import { execFileSync } from 'node:child_process';
10
+ import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
11
+ import { dirname, join } from 'node:path';
12
+ import { readSpawns } from '../../experiments/pi-spawn/registry.mjs';
13
+ import { findReceipt } from './pi-receipts.mjs';
14
+
15
+ const note = (line) => console.error(`herdgate pi-wake: ${line}`);
16
+
17
+ const SCOPE = /^[0-9a-f]{16}$/;
18
+ /** A receipt that proves the child finished speaking — anything else is silence.
19
+ * Final settles (replied/failed/canceled) wake a parent; invalidated/expired
20
+ * intents (unknown) carry no result to act on, and a vanished child belongs
21
+ * to the death watch below. */
22
+ export const SETTLED = new Set(['replied', 'failed', 'canceled']);
23
+
24
+ /** The handling directive that rides IN every settle frame, on purpose: the
25
+ * protocol must survive context compaction in the parent — a bare status line
26
+ * gets a bare ack (observed live); the instruction makes every wake
27
+ * self-describing. Shared by the journal-watch frame and the herdr-event
28
+ * frame (server/wake-event.mjs) so the wording never forks. */
29
+ export const SETTLE_DIRECTIVE = ' → việc con đã settle. LÀM TRỌN TRONG TURN NÀY: chạy test mục tiêu, review diff, commit nếu đạt, rồi báo user ngắn gọn — không chỉ ack.';
30
+
31
+ /** Every spawn record across workspace scopes (spawn + self declarations). */
32
+ export function readAllSpawns(base) {
33
+ const out = [];
34
+ let scopes = [];
35
+ try { scopes = readdirSync(base).filter(n => SCOPE.test(n)); }
36
+ catch { return out; }
37
+ for (const scope of scopes) {
38
+ for (const entry of readSpawns(join(base, scope, 'spawns.jsonl'))) out.push(entry);
39
+ }
40
+ return out;
41
+ }
42
+
43
+ /** The spawn edge for a child session: controller records win over self-declared. */
44
+ export function parentOf(spawns, childSessionId) {
45
+ return spawns.find(s => s.sessionId === childSessionId && s.parentSessionId && !s.self)
46
+ ?? spawns.find(s => s.sessionId === childSessionId && s.parentSessionId)
47
+ ?? null;
48
+ }
49
+
50
+ /** The pane currently showing a session (its agent_session file ends _<id>.jsonl). */
51
+ export function paneForSession(panes, sessionId) {
52
+ const suffix = `_${sessionId}.jsonl`;
53
+ const pane = (panes ?? []).find(p => typeof p?.agent_session?.value === 'string'
54
+ && p.agent_session.value.endsWith(suffix));
55
+ return pane?.pane_id ?? null;
56
+ }
57
+
58
+ /** One terse line: enough for the parent to act, never the reply text. */
59
+ export function wakeFrame(entry, spawn) {
60
+ const bits = [`[herdgate-wake child=${spawn.name ?? 'child'}`, `id=${entry.id}`, `status=${entry.status}`];
61
+ if (entry.reason) bits.push(`reason=${entry.reason}`);
62
+ if (entry.title) bits.push(`title="${String(entry.title).replace(/\s+/g, ' ').slice(0, 60)}"`);
63
+ if (entry.usage && Number.isFinite(entry.usage.totalTokens)) bits.push(`tokens=${entry.usage.totalTokens}`);
64
+ bits.push(`ts=${new Date(entry.ts).toISOString()}]`);
65
+ const line = bits.join(' ') + SETTLE_DIRECTIVE;
66
+ return line.length <= 480 ? line : `${bits.join(' ').slice(0, 300)}…]${SETTLE_DIRECTIVE}`;
67
+ }
68
+
69
+ /** Resolve the parent's pane and deliver one frame once the parent is quietly
70
+ * between turns. Shared by settle wakes, death wakes AND the herdr event hook
71
+ * (server/wake-event.mjs) — the quiet-wait protocol below is the load-bearing
72
+ * part and must never fork the tree.
73
+ *
74
+ * Delivery waits for the parent to be BETWEEN TURNS, stably. Two live
75
+ * incidents (wtest2, wfork1) showed why "idle" alone is not enough: herdr
76
+ * flips the agent idle milliseconds BEFORE the turn's final message lands, so
77
+ * a wake injected at that instant becomes a PENDING message, and Pi's pending
78
+ * queue then forks the session tree from a stale leaf — the handling turn runs
79
+ * in full on an orphan branch that neither the human's view nor the parent's
80
+ * context ever adopts, and everyone swears nothing arrived. Waiting for the
81
+ * agent revision to hold steady across two probes proves the turn truly
82
+ * closed; the injected text then submits against the live leaf. */
83
+ export function deliverToParent({ spawn, line, label, run, listPanes, agentState, agentProbe, onDelivered, generation,
84
+ log = () => {}, retryDelayMs = () => new Promise(r => setTimeout(r, 3000)), settleDelayMs = () => new Promise(r => setTimeout(r, 2000)), maxWaitMs = 15 * 60 * 1000 }) {
85
+ const deliver = (pane, waited, seenRevision) => {
86
+ // Generation drift (herdr-sesh requestID, adapted): the caller captured the
87
+ // parent's revision at fire time; if the parent turned while we waited for
88
+ // a quiet moment the token no longer matches — but a wake is NOT a UI
89
+ // refresh, dropping it is unrecoverable, so the frame still goes and the
90
+ // drift is logged for the trail.
91
+ if (generation != null && seenRevision != null && seenRevision !== generation) {
92
+ log(`wake: parent pane ${pane} revision drifted ${generation}->${seenRevision} while waiting — delivering anyway (child ${spawn.name} ${label})`);
93
+ }
94
+ try {
95
+ // pane run TYPES into the parent's terminal — the same live-branch path
96
+ // as /herdgate-arm markers. herdr agent prompt submits through the
97
+ // agent/RPC handle whose leaf pointer stagnates after one fork: every
98
+ // wake then extends an orphan branch no one ever sees (three live
99
+ // incidents, each parented to the previous orphan's leaf).
100
+ run('pane', 'run', pane, line);
101
+ log(`wake: child ${spawn.name} ${label} -> parent pane ${pane}${waited ? ` (waited ${(waited / 1000) | 0}s for a quiet parent)` : ''}`);
102
+ // Bookkeeping AFTER the frame landed (episode dedupe sidecars etc.) — a
103
+ // failure here must never undo or retry a delivered wake.
104
+ try { onDelivered?.(); } catch { /* never fatal */ }
105
+ } catch (error) {
106
+ log(`wake failed: ${error instanceof Error ? error.message : String(error)}`); // agent_blocked etc: never fatal
107
+ }
108
+ };
109
+ const panes = listPanes();
110
+ // The parent's REAL pane, recorded at spawn time. Session-file lookup alone
111
+ // is ambiguous: a second pi bound to the same session (a restore leftover)
112
+ // makes every wake land in the ghost — observed live, four times.
113
+ let pane = spawn.parentPaneId && panes.some(p => p?.pane_id === spawn.parentPaneId)
114
+ ? spawn.parentPaneId
115
+ : paneForSession(panes, spawn.parentSessionId);
116
+ if (!pane) {
117
+ log(`wake: parent ${String(spawn.parentSessionId).slice(0, 8)} pane gone — child ${spawn.name} ${label}`);
118
+ return;
119
+ }
120
+ if (!agentProbe) {
121
+ // Legacy single-state probe: idle means deliver (kept for callers
122
+ // without a revision; the rich probe above is the safe path).
123
+ if (!agentState) return deliver(pane, 0);
124
+ const started = Date.now();
125
+ const attemptState = () => {
126
+ let state = 'unknown';
127
+ try { state = agentState(pane) ?? 'unknown'; }
128
+ catch { state = 'unknown'; }
129
+ if (state === 'idle') return deliver(pane, Date.now() - started);
130
+ if (Date.now() - started >= maxWaitMs) {
131
+ return log(`wake: parent pane ${pane} stayed ${state} for ${(maxWaitMs / 60000) | 0}min — dropped wake for ${spawn.name} (journal keeps the settle)`);
132
+ }
133
+ void retryDelayMs().then(attemptState);
134
+ };
135
+ return attemptState();
136
+ }
137
+ const started = Date.now();
138
+ const attempt = () => {
139
+ let probe = null;
140
+ try { probe = agentProbe(pane); } catch { probe = null; }
141
+ const state = probe?.status ?? 'unknown';
142
+ if (state === 'working' || state === 'blocked' || !probe) {
143
+ if (Date.now() - started >= maxWaitMs) {
144
+ return log(`wake: parent pane ${pane} stayed ${state} for ${(maxWaitMs / 60000) | 0}min — dropped wake for ${spawn.name} (journal keeps the settle)`);
145
+ }
146
+ return void retryDelayMs().then(attempt);
147
+ }
148
+ // Idle-ish: prove the turn CLOSED — the revision must hold across a settle delay.
149
+ void settleDelayMs().then(() => {
150
+ let again = null;
151
+ try { again = agentProbe(pane); } catch { again = null; }
152
+ if (again && again.status !== 'working' && again.status !== 'blocked' && again.revision === probe.revision) {
153
+ return deliver(pane, Date.now() - started, again.revision);
154
+ }
155
+ if (Date.now() - started >= maxWaitMs) {
156
+ return log(`wake: parent pane ${pane} never quieted (${state}→${again?.status ?? '?'}, rev ${probe.revision}→${again?.revision ?? '?'}) — dropped wake for ${spawn.name}`);
157
+ }
158
+ void retryDelayMs().then(attempt);
159
+ });
160
+ };
161
+ attempt();
162
+ }
163
+
164
+ /** Build the onSettle callback for watchReceipts. */
165
+ export function wakeParentOnSettle({ spawnBase, run, listPanes, agentState, agentProbe, log = () => {}, retryDelayMs, settleDelayMs, maxWaitMs }) {
166
+ return (entry) => {
167
+ try {
168
+ if (!entry?.sessionId || !entry?.id) return;
169
+ if (!SETTLED.has(entry.status)) {
170
+ return log(`wake: ${entry.id} settled ${entry.status} — not a final settle, no parent wake`);
171
+ }
172
+ const spawn = parentOf(readAllSpawns(spawnBase), entry.sessionId);
173
+ if (!spawn) return; // not a spawned child: nothing to wake
174
+ deliverToParent({ spawn, line: wakeFrame(entry, spawn), label: entry.status,
175
+ run, listPanes, agentState, agentProbe, log, retryDelayMs, settleDelayMs, maxWaitMs });
176
+ } catch (error) {
177
+ log(`wake failed: ${error instanceof Error ? error.message : String(error)}`); // agent_blocked etc: never fatal
178
+ }
179
+ };
180
+ }
181
+
182
+ /** The herdr-pings lesson: a child that dies with its pane (bridge crash) never
183
+ * settles, so no journal event can ever fire a wake — the silence IS the
184
+ * failure. The banner follows the wake-skill format so the parent's handling
185
+ * protocol recognizes the frame and acts inside its turn. */
186
+ export function deathFrame(spawn) {
187
+ return `🔔 WAKE — agent ${spawn?.name ?? 'child'} DIED: pane biến mất chưa kịp settle — kiểm tra registry, restore nếu cần`;
188
+ }
189
+
190
+ /** Wake a parent about a lost child (pane vanished before any final settle). */
191
+ export function wakeParentOnDeath({ run, listPanes, agentState, agentProbe, log = () => {}, retryDelayMs, settleDelayMs, maxWaitMs }) {
192
+ return (spawn) => {
193
+ try {
194
+ if (!spawn?.parentSessionId) return;
195
+ deliverToParent({ spawn, line: deathFrame(spawn), label: 'DIED',
196
+ run, listPanes, agentState, agentProbe, log, retryDelayMs, settleDelayMs, maxWaitMs });
197
+ } catch (error) {
198
+ log(`wake failed: ${error instanceof Error ? error.message : String(error)}`);
199
+ }
200
+ };
201
+ }
202
+
203
+ /** Stamp+byte-verified persistence — herdcats follower.rs:483-488 applied to
204
+ * writes instead of tailing: tmp+rename, then read the file BACK and compare
205
+ * every byte, taking a stat stamp before AND after the read so a read racing
206
+ * another rewrite is detected rather than trusted (mtime/size alone lie — a
207
+ * same-length rewrite is invisible to them). A miss rewrites exactly ONCE;
208
+ * a second miss logs and gives up — never throws: bookkeeping must not kill
209
+ * a wake. `readback` is the host-trait seam (herdr-sidebar FakeRefresh
210
+ * style): tests inject lying reads to prove the retry; production always
211
+ * reads the real file. */
212
+ export function writeFileVerified(file, bytes, { log = note, readback = null } = {}) {
213
+ const data = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes), 'utf8');
214
+ const stampOf = (st) => (st ? `${st.dev ?? 0}:${st.ino ?? 0}:${st.size}:${st.mtimeMs}` : null);
215
+ const realReadback = (path) => {
216
+ try {
217
+ const before = stampOf(statSync(path));
218
+ const back = readFileSync(path);
219
+ const after = stampOf(statSync(path));
220
+ return before && after && before === after ? back : null; // moved under us: not trustworthy
221
+ } catch { return null; }
222
+ };
223
+ const verify = (path, attempt) => (readback ? readback(path, attempt) : realReadback(path));
224
+ const attempt = (n) => {
225
+ try {
226
+ mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
227
+ const tmp = `${file}.tmp`;
228
+ writeFileSync(tmp, data, { mode: 0o600 });
229
+ rmSync(file, { force: true });
230
+ renameSync(tmp, file);
231
+ } catch (error) {
232
+ log(`verified write #${n} failed for ${file}: ${error instanceof Error ? error.message : String(error)}`);
233
+ return false;
234
+ }
235
+ const back = verify(file, n);
236
+ return back !== null && back.length === data.length && back.equals(data);
237
+ };
238
+ if (attempt(1)) return true;
239
+ if (attempt(2)) return true; // hụt → ghi lại đúng một lần, rồi đọc lại lần nữa
240
+ log(`verified write still mismatches for ${file} after one retry — giving up (not fatal)`);
241
+ return false;
242
+ }
243
+
244
+ /** Patch one spawn record inside the scope file that actually holds it. The
245
+ * registry's own updateSpawn patches only the caller's cwd scope — the
246
+ * publisher daemon sits elsewhere, so deaths are marked wherever the record
247
+ * lives. Returns the updated record, or null when no scope holds the id. */
248
+ export function patchSpawn(base, id, patch) {
249
+ let scopes = [];
250
+ try { scopes = readdirSync(base).filter(name => SCOPE.test(name)); }
251
+ catch { return null; }
252
+ for (const scope of scopes) {
253
+ const file = join(base, scope, 'spawns.jsonl');
254
+ const entries = readSpawns(file);
255
+ if (!entries.some(entry => entry.id === id)) continue;
256
+ let updated = null;
257
+ const next = entries.map(entry => entry.id === id ? (updated = { ...entry, ...patch }) : entry);
258
+ // Stamp+byte-verified: the mark (died/closedBy) is what keeps ONE frame per
259
+ // child — a write that silently misses would re-fire wakes forever.
260
+ if (!writeFileVerified(file, `${next.map(entry => JSON.stringify(entry)).join('\n')}\n`)) return null;
261
+ return updated;
262
+ }
263
+ return null;
264
+ }
265
+
266
+ /** Children whose pane vanished before any final settle — the death-watch
267
+ * candidates. ONLY records with a parent-pane edge qualify: human panes and
268
+ * self-declared worker sessions are never watched. An empty pane list means
269
+ * herdr itself is unreachable/restarting — that is not six deaths, it is zero
270
+ * answers; fail silent instead of spamming DIED frames. */
271
+ export function scanSpawnDeaths({ spawnBase, listPanes }) {
272
+ let panes = [];
273
+ try { panes = listPanes() ?? []; }
274
+ catch { return []; }
275
+ if (!panes.length) return [];
276
+ const alive = new Set(panes.map(p => p?.pane_id).filter(Boolean));
277
+ const dead = [];
278
+ for (const spawn of readAllSpawns(spawnBase)) {
279
+ if (!spawn.parentPaneId || !spawn.paneId) continue; // no parent edge: not ours to watch
280
+ if (spawn.died === true || spawn.closedBy === 'parent') continue; // already reported / closed on purpose
281
+ if (alive.has(spawn.paneId)) continue; // pane still there
282
+ const receipt = findReceipt(spawnBase, spawn.id);
283
+ if (receipt && SETTLED.has(receipt.status)) continue; // settled in time; the close was earned
284
+ dead.push(spawn);
285
+ }
286
+ return dead;
287
+ }
288
+
289
+ /** The publisher's 30s death watch (a script poll, never the journal watcher):
290
+ * scan → mark died:true in the registry FIRST (one DIED per child, never a
291
+ * spam loop) → wake the parent through the same quiet-delivery path. */
292
+ export function watchSpawnDeaths({ spawnBase, run, listPanes, agentState, agentProbe, log = () => {}, intervalMs = 30_000, retryDelayMs, settleDelayMs, maxWatchMs }) {
293
+ const wakeOne = wakeParentOnDeath({ run, listPanes, agentState, agentProbe, log, retryDelayMs, settleDelayMs, maxWaitMs: maxWatchMs });
294
+ const tick = () => {
295
+ let dead = [];
296
+ try { dead = scanSpawnDeaths({ spawnBase, listPanes }); }
297
+ catch (error) {
298
+ return log(`death scan failed: ${error instanceof Error ? error.message : String(error)}`);
299
+ }
300
+ for (const spawn of dead) {
301
+ const marked = patchSpawn(spawnBase, spawn.id, { died: true, diedAt: Date.now() });
302
+ if (!marked) continue; // record vanished mid-scan: nothing to wake about
303
+ log(`death: child ${spawn.name} pane ${spawn.paneId} vanished before settling — waking the parent`);
304
+ wakeOne(marked);
305
+ }
306
+ };
307
+ const timer = setInterval(tick, intervalMs);
308
+ timer.unref?.();
309
+ return () => clearInterval(timer);
310
+ }
311
+
312
+ /** Default herdr runner for the publisher process (tolerates plain-text output). */
313
+ export function herdrRunner() {
314
+ const bin = process.env.HERDR_BIN_PATH ?? 'herdr';
315
+ return (...args) => {
316
+ const out = execFileSync(bin, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
317
+ try { return JSON.parse(out); } catch { return { raw: out }; }
318
+ };
319
+ }
@@ -6,6 +6,8 @@ export interface JobRecord {
6
6
  prompt: string;
7
7
  ts: number;
8
8
  state: JobState;
9
+ /** Routing key resolved against the host's workspaces.json allowlist. */
10
+ workspace?: string;
9
11
  sessionId?: string;
10
12
  reason?: string;
11
13
  requestEntryId?: string;
@@ -30,6 +32,11 @@ export const MIN_PI_VERSION: string;
30
32
  export function versionAtLeast(version: string, min?: string): boolean;
31
33
  export function workerBase(env?: Record<string, string | undefined>): string;
32
34
  export function jobsFile(base: string): string;
35
+ /** Routing key a device may reference; paths never cross the wire. */
36
+ export const WORKSPACE_NAME: RegExp;
37
+ export function workspacesFile(base: string): string;
38
+ /** Owner-curated name -> absolute workspace path. Missing/corrupt -> empty map. */
39
+ export function readWorkspaces(base: string): Map<string, string>;
33
40
  export function validJob(job: unknown): JobRecord | null;
34
41
  export function readJobs(file: string): Map<string, JobRecord>;
35
42
  export function appendJob(file: string, job: JobRecord): void;
@@ -5,13 +5,20 @@
5
5
  import { createHash } from 'node:crypto';
6
6
  import { homedir } from 'node:os';
7
7
  import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
8
- import { dirname, join } from 'node:path';
8
+ import { dirname, isAbsolute, join } from 'node:path';
9
+ // Same contract as receipts: the actor that caused this job (schedule:<id>,
10
+ // device:<id>…) rides along to the journal when the worker settles it.
11
+ import { PRINCIPAL } from './pi-receipts.mjs';
9
12
 
10
13
  export const JOB_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
11
14
  export const MAX_PROMPT = 16 * 1024; // admission bound for one prompt
15
+ export const MAX_RUN = 2048; // admission bound for one shell command (run jobs)
12
16
  export const MAX_PENDING = 100; // queued + running jobs admitted at once
13
17
  export const JOB_STATES = new Set(['queued', 'running', 'replied', 'failed', 'canceled', 'unknown']);
18
+ /** Routing key a device may reference — resolved against the host's allowlist. */
19
+ export const WORKSPACE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
14
20
  const JOBS = 'jobs.jsonl';
21
+ const WORKSPACES = 'workspaces.json';
15
22
 
16
23
  /** Oldest Pi release the experiments are verified against. Newer Pi releases run
17
24
  * without code changes; only a Pi older than this is refused. */
@@ -43,15 +50,49 @@ export function jobsFile(base) {
43
50
  return join(base, JOBS);
44
51
  }
45
52
 
53
+ export function workspacesFile(base) {
54
+ return join(base, WORKSPACES);
55
+ }
56
+
57
+ /** Owner-curated routing table: name -> absolute workspace path, 0600, optional.
58
+ * A device references a name; the worker resolves it here. No raw paths cross
59
+ * the wire, and a name missing from this file fails closed (never runs). */
60
+ export function readWorkspaces(base) {
61
+ let raw;
62
+ try { raw = readFileSync(workspacesFile(base), 'utf8'); }
63
+ catch (error) { if (error.code === 'ENOENT') return new Map(); throw error; }
64
+ let parsed;
65
+ try { parsed = JSON.parse(raw); }
66
+ catch { return new Map(); } // corrupt allowlist routes nothing new
67
+ const table = parsed?.v === 1 && parsed.workspaces && typeof parsed.workspaces === 'object'
68
+ ? parsed.workspaces : null;
69
+ if (!table) return new Map();
70
+ const out = new Map();
71
+ for (const [name, path] of Object.entries(table)) {
72
+ if (WORKSPACE_NAME.test(name) && typeof path === 'string' && isAbsolute(path)) out.set(name, path);
73
+ }
74
+ return out;
75
+ }
76
+
46
77
  export function validJob(job) {
47
78
  return validJobShape(job) ? job : null;
48
79
  }
49
80
 
81
+ const validPrompt = value => typeof value === 'string' && value.length <= MAX_PROMPT;
82
+ const validRun = value => typeof value === 'string' && value.length >= 1
83
+ && value.length <= MAX_RUN && !value.includes('\0');
84
+
50
85
  function validJobShape(job) {
51
86
  return Boolean(job && job.v === 1 && JOB_ID.test(job.id ?? '')
52
87
  && JOB_STATES.has(job.state)
53
- && typeof job.prompt === 'string' && job.prompt.length <= MAX_PROMPT
88
+ // Payload: a model prompt, a shell command (run job), or both (the worker
89
+ // takes run). Whichever fields are present must each be well-formed.
90
+ && (validPrompt(job.prompt) || validRun(job.run))
91
+ && (job.prompt === undefined || validPrompt(job.prompt))
92
+ && (job.run === undefined || validRun(job.run))
54
93
  && typeof job.ts === 'number'
94
+ && (job.workspace === undefined || WORKSPACE_NAME.test(job.workspace))
95
+ && (job.principal === undefined || PRINCIPAL.test(job.principal))
55
96
  && ['sessionId', 'reason', 'requestEntryId', 'responseEntryId'].every(key =>
56
97
  job[key] === undefined || typeof job[key] === 'string'));
57
98
  }
@@ -79,10 +120,10 @@ export function appendJob(file, job) {
79
120
  appendFileSync(file, `${JSON.stringify(job)}\n`, { mode: 0o600 });
80
121
  }
81
122
 
82
- /** The public answer for a device: the prompt never leaves the host. */
123
+ /** The public answer for a device: neither the prompt nor the command leaves the host. */
83
124
  export function publicJob(job) {
84
125
  if (!job) return { state: 'unknown', reason: 'not_admitted' };
85
- const { v, prompt, ...rest } = job;
126
+ const { v, prompt, run, ...rest } = job;
86
127
  return rest;
87
128
  }
88
129
 
@@ -0,0 +1,172 @@
1
+ // Listening-port attribution via process ancestry (see docs/research/
2
+ // 2026-11-21-marketplace/deep/portfwd.md — mechanism from herdr-portfwd
3
+ // src/discover.rs `ProcessTree::ancestry` + `attribute`, MIT). No lsof/ss/ps
4
+ // subprocesses: /proc/net/tcp + /proc/net/tcp6 supply LISTEN sockets with
5
+ // their inodes, /proc/<pid>/fd readlinks match inode → owning pid, and a ppid
6
+ // walk (cycle-guarded, depth-capped, pid 0 filtered — the kernel is never a
7
+ // shell) attributes the port to the session shell it descends from.
8
+ // A listener no shell owns lands in `unattributed` — an owner is never
9
+ // invented. Torn-safe: pids and fds that vanish or are unreadable mid-scan
10
+ // are skipped, never fail the batch.
11
+
12
+ import { readdirSync, readFileSync, readlinkSync } from 'node:fs';
13
+ import { join } from 'node:path';
14
+
15
+ const MAX_ANCESTRY_DEPTH = 32;
16
+ const SOCKET_INODE = /^socket:\[(\d+)\]$/;
17
+
18
+ /** {pid → key} from a mixed list of pids and {pid, key} entries; first wins. */
19
+ function shellIndex(shellPids) {
20
+ const shells = new Map();
21
+ for (const entry of Array.isArray(shellPids) ? shellPids : []) {
22
+ const pid = typeof entry === 'number' ? entry : entry?.pid;
23
+ const key = typeof entry === 'number' ? String(entry) : entry?.key ?? String(entry?.pid);
24
+ if (Number.isInteger(pid) && pid > 0 && !shells.has(pid)) shells.set(pid, key);
25
+ }
26
+ return shells;
27
+ }
28
+
29
+ /**
30
+ * /proc/net/tcp(6) LISTEN rows → [{port, proto, inode}]. st "0A" is
31
+ * TCP_LISTEN; the inode is field 10 (parts[9]); the port is the hex half of
32
+ * the local address. Unreadable tables are skipped, not fatal.
33
+ */
34
+ function listeningSockets(procDir, file, proto) {
35
+ const rows = [];
36
+ let text;
37
+ try {
38
+ text = readFileSync(join(procDir, file), 'utf8');
39
+ } catch {
40
+ return rows;
41
+ }
42
+ for (const line of text.split('\n').slice(1)) { // header row: " sl local_address …"
43
+ const parts = line.trim().split(/\s+/);
44
+ if (parts.length < 10 || parts[3] !== '0A') continue;
45
+ const port = Number.parseInt(parts[1].split(':')[1] ?? '', 16);
46
+ const inode = Number(parts[9]);
47
+ if (Number.isInteger(port) && port > 0 && Number.isInteger(inode) && inode > 0) {
48
+ rows.push({ port, proto, inode });
49
+ }
50
+ }
51
+ return rows;
52
+ }
53
+
54
+ /**
55
+ * One pass over numeric /proc entries: stat (ppid + comm) and fd readlinks.
56
+ * Returns {ppid: Map, comm: Map, byInode: Map inode → pid} — torn-safe.
57
+ */
58
+ function scanProcesses(procDir, wantedInodes) {
59
+ const ppid = new Map();
60
+ const comm = new Map();
61
+ const byInode = new Map();
62
+ let names;
63
+ try {
64
+ names = readdirSync(procDir);
65
+ } catch {
66
+ return { ppid, comm, byInode };
67
+ }
68
+ for (const name of names) {
69
+ if (!/^\d+$/.test(name)) continue;
70
+ const pid = Number(name);
71
+ let stat;
72
+ try {
73
+ stat = readFileSync(join(procDir, name, 'stat'), 'utf8');
74
+ } catch {
75
+ continue; // pid vanished mid-scan — skipped, batch keeps going
76
+ }
77
+ const close = stat.lastIndexOf(')');
78
+ const rest = stat.slice(close + 1).trim().split(/\s+/);
79
+ const parent = Number(rest[1]);
80
+ if (Number.isFinite(parent) && parent > 0) ppid.set(pid, parent); // pid 0 filtered
81
+ if (close > 0) comm.set(pid, stat.slice(stat.indexOf('(') + 1, close));
82
+ let fds;
83
+ try {
84
+ fds = readdirSync(join(procDir, name, 'fd'));
85
+ } catch {
86
+ continue; // no permission / raced away — ppid still counted
87
+ }
88
+ for (const fd of fds) {
89
+ let target;
90
+ try {
91
+ target = readlinkSync(join(procDir, name, 'fd', fd));
92
+ } catch {
93
+ continue;
94
+ }
95
+ const match = SOCKET_INODE.exec(target);
96
+ if (!match) continue;
97
+ const inode = Number(match[1]);
98
+ if (wantedInodes.has(inode) && !byInode.has(inode)) byInode.set(inode, pid);
99
+ }
100
+ }
101
+ return { ppid, comm, byInode };
102
+ }
103
+
104
+ function commandOf(procDir, pid, comm) {
105
+ try {
106
+ const cmdline = readFileSync(join(procDir, String(pid), 'cmdline'), 'utf8');
107
+ const text = cmdline.split('\0').filter(Boolean).join(' ');
108
+ if (text) return text;
109
+ } catch {
110
+ /* fall through to comm */
111
+ }
112
+ return comm.get(pid) ?? '';
113
+ }
114
+
115
+ /**
116
+ * Attribute listening ports to session shells. shellPids: pids or {pid, key}
117
+ * entries — the key of the matched shell comes back as ownerKey. Returns
118
+ * {attributed: [{port, proto, pid, cmd, ownerKey}], unattributed: [{port,
119
+ * proto, pid?, cmd?}]} — sorted by (port, proto), deduped. The owning pid is
120
+ * the process holding the socket; the owner is the shell it descends from.
121
+ * Never invents an owner: unattributed listeners stay unattributed. Missing
122
+ * /proc → empty lists; never throws.
123
+ */
124
+ export function attributePorts(shellPids, procDir = '/proc') {
125
+ const shells = shellIndex(shellPids);
126
+ const sockets = [
127
+ ...listeningSockets(procDir, 'net/tcp', 'tcp'),
128
+ ...listeningSockets(procDir, 'net/tcp6', 'tcp6'),
129
+ ];
130
+ const { ppid, comm, byInode } = scanProcesses(procDir, new Set(sockets.map(s => s.inode)));
131
+
132
+ const attributed = [];
133
+ const unattributed = [];
134
+ const seenAttributed = new Set();
135
+ const seenUnattributed = new Set();
136
+ for (const { port, proto, inode } of sockets.sort((a, b) => a.port - b.port || a.proto.localeCompare(b.proto))) {
137
+ const pid = byInode.get(inode);
138
+ if (!Number.isInteger(pid)) {
139
+ const id = `${port}/${proto}`;
140
+ if (!seenUnattributed.has(id)) {
141
+ seenUnattributed.add(id);
142
+ unattributed.push({ port, proto }); // socket owner not observable (no fd access)
143
+ }
144
+ continue;
145
+ }
146
+ // ppid walk back to a shell: cycle-guarded, depth-capped, pid 0 filtered.
147
+ let ownerKey;
148
+ let cur = pid;
149
+ const walked = new Set();
150
+ for (let depth = 0; depth < MAX_ANCESTRY_DEPTH; depth++) {
151
+ if (shells.has(cur)) { ownerKey = shells.get(cur); break; }
152
+ if (walked.has(cur)) break;
153
+ walked.add(cur);
154
+ cur = ppid.get(cur);
155
+ if (!Number.isInteger(cur) || cur <= 0) break;
156
+ }
157
+ if (ownerKey !== undefined) {
158
+ const id = `${port}/${proto}/${pid}`;
159
+ if (!seenAttributed.has(id)) {
160
+ seenAttributed.add(id);
161
+ attributed.push({ port, proto, pid, cmd: commandOf(procDir, pid, comm), ownerKey });
162
+ }
163
+ } else {
164
+ const id = `${port}/${proto}/${pid}`;
165
+ if (!seenUnattributed.has(id)) {
166
+ seenUnattributed.add(id);
167
+ unattributed.push({ port, proto, pid, cmd: commandOf(procDir, pid, comm) });
168
+ }
169
+ }
170
+ }
171
+ return { attributed, unattributed };
172
+ }