@bom0792/herdgate 0.9.39 → 0.9.41

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.41",
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": {
@@ -58,10 +58,15 @@ export function scrubEnv() {
58
58
 
59
59
  /** Args must be short printable words: refs, hashes, paths, allowed flags. */
60
60
  const ARG_RE = /^[A-Za-z0-9._/::~^-]{1,128}$/;
61
- /** Flags a read may carry. Anything else option-looking is refused. */
62
- const ALLOWED_FLAGS = new Set(["-C", "--no-color", "--stat", "--patch", "--no-ext-diff", "--no-textconv"]);
61
+ /** Flags a read may carry. Anything else option-looking is refused.
62
+ * `--porcelain` is `status`'s machine-readable mode — read-only output shaping,
63
+ * the same trust class as `--stat`; `--` is the path separator (`ls-files -- <path>`). */
64
+ const ALLOWED_FLAGS = new Set(["-C", "--no-color", "--stat", "--patch", "--numstat", "--no-ext-diff", "--no-textconv", "--porcelain", "--verify", "--"]);
63
65
  /** Subcommands that produce diffs — the only ones that take --no-ext-diff/--no-textconv. */
64
66
  const DIFF_COMMANDS = new Set(["diff", "show", "log", "whatchanged", "format-patch", "range-diff"]);
67
+ /** Read-only subcommands gitRead will run at all. Anything else is refused before
68
+ * argv is even built — the allowlist is the whole attack surface for this seam. */
69
+ const ALLOWED_COMMANDS = new Set(["show", "log", "diff", "ls-files", "status", "rev-parse", "config"]);
65
70
 
66
71
  function refuse(code, message) {
67
72
  const err = new Error(message);
@@ -113,6 +118,20 @@ function buildArgv(args) {
113
118
  */
114
119
  export async function gitRead(args, cwd = diffRepoDir(), timeoutMs = 10_000, maxBuffer = 8 * 1024 * 1024) {
115
120
  validateArgs(args);
121
+ // The subcommand itself must be on the read allowlist — flags alone were never
122
+ // the whole surface (`config`, `clone`, … are all flagless). The command is the
123
+ // first arg that is not an option, skipping any leading `-C <dir>` pair.
124
+ let i = 0;
125
+ while (i < args.length && args[i].startsWith("-")) i += args[i] === "-C" ? 2 : 1;
126
+ const command = args[i] ?? "";
127
+ if (!ALLOWED_COMMANDS.has(command)) {
128
+ throw refuse("GIT_SAFE_ARG", `gitRead refuses command ${JSON.stringify(command)}: not a read command`);
129
+ }
130
+ // `config` is readable but writable too (`git config key value` has no flag!) —
131
+ // admit ONLY the two-arg read form, never a value or --add/--global.
132
+ if (command === "config" && args.length !== i + 2) {
133
+ throw refuse("GIT_SAFE_ARG", "gitRead refuses config: only the two-arg read form `config <name>`");
134
+ }
116
135
  const allowed = new Set([PLUGIN_DIR]);
117
136
  if (process.env.HERDGATE_DIFF_REPO_DIR) allowed.add(resolve(process.env.HERDGATE_DIFF_REPO_DIR));
118
137
  const startDir = resolve(cwd);
@@ -9,7 +9,7 @@
9
9
  import { execFile as execFileCb, spawn } from "node:child_process";
10
10
  import { randomUUID } from "node:crypto";
11
11
  import { promisify } from "node:util";
12
- import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
12
+ import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
13
13
  import { join, dirname } from "node:path";
14
14
  import { hostname, homedir } from "node:os";
15
15
  import { fileURLToPath } from "node:url";
@@ -33,6 +33,10 @@ const D = dirs();
33
33
  const execFile = promisify(execFileCb);
34
34
  /** diff.get ships at most 128 KiB of `git show` output, marked truncated beyond. */
35
35
  const MAX_DIFF_BYTES = 128 * 1024;
36
+ const MAX_FILE_ENTRIES = 5000; // file.tree cap — the fuzzy finder ranks within this
37
+ const MAX_FILE_BYTES = 128 * 1024; // file.read cap — same class as diffs, and well under the gate's 256KiB frame limit
38
+ const MAX_REVIEW_FILES = 5000; // review.files entries cap (one screen's worth of scrolling)
39
+ const MAX_REVIEW_COMMENTS = 50; // review.send comments per batch — a review, not a prompt
36
40
  const NAME = process.env.HERDGATE_HOST_NAME || hostname();
37
41
  const log = (line) => console.error(`herdgate: ${line}`);
38
42
  /** The panel's settings file (app home herdgate dir) — the owner's switches live
@@ -439,7 +443,29 @@ async function publisherLoop() {
439
443
  }
440
444
  if (replayed) log(`receipts: replayed ${replayed} unacknowledged push(es) to ${device}`);
441
445
  };
446
+ /** Settle-anchored git heads — the `turn` review scope without a ref write
447
+ * (reviewr keeps its baseline in refs/reviewr/*; herdgate journals settle
448
+ * heads BESIDE the repo instead). Receipts carry no hashes, so this journal
449
+ * is the honest baseline: every settle records HEAD; `turn` diffs the two
450
+ * newest anchors = exactly the last settled agent turn. */
451
+ const gitAnchorsFile = () => (D.statePath ? join(D.statePath, "..", "git-anchors.json") : "");
452
+ const recordGitAnchor = async (reason) => {
453
+ const file = gitAnchorsFile();
454
+ if (!file) return;
455
+ try {
456
+ const { stdout } = await gitRead(["rev-parse", "HEAD"], diffRepoDir(), 5_000);
457
+ const head = String(stdout).trim();
458
+ if (!/^[0-9a-f]{7,40}$/.test(head)) return;
459
+ const prior = readState(file);
460
+ const anchors = Array.isArray(prior.anchors) ? prior.anchors : [];
461
+ if (anchors[anchors.length - 1]?.head === head) return; // no new commits since
462
+ anchors.push({ head, at: Date.now(), reason });
463
+ writeState(file, { v: 1, anchors: anchors.slice(-8) });
464
+ log(`review: anchor ${head.slice(0, 8)} (${reason})`);
465
+ } catch { /* not a repo — `turn` will say so honestly */ }
466
+ };
442
467
  const pushReceipt = (entry) => {
468
+ void recordGitAnchor("settle"); // journal the turn boundary first — subscriber fan-out is separate
443
469
  const store = watches();
444
470
  if (!store) return;
445
471
  store.sweep();
@@ -453,21 +479,22 @@ async function publisherLoop() {
453
479
  const known = devices.find(d => d.id === sub.device);
454
480
  if (known && known.connected !== false) continue;
455
481
  log(`receipts: wake ${sub.device} (settle while offline)`);
456
- wakeAway(true);
482
+ wakeAway(true, { kind: "settle", agent: entry.title ?? undefined });
457
483
  }
458
484
  };
459
485
 
460
486
  /** Wake phones that are away when something actually changed (throttled per device). */
461
487
  const lastWake = new Map(); // deviceId → epoch ms
462
- const wakeAway = (changed) => {
488
+ const wakeAway = (changed, note = { kind: "activity" }) => {
463
489
  if (!changed) return;
490
+ if (note?.kind === "settle") void recordGitAnchor("settle"); // event-hook settles journal too
464
491
  const now = Date.now();
465
492
  for (const d of devices) {
466
493
  if (d.connected !== false) continue;
467
494
  const at = lastWake.get(d.id) ?? 0;
468
495
  if (now - at < 5 * 60_000) continue;
469
496
  lastWake.set(d.id, now);
470
- if (wsRef && wsRef.readyState === 1) wsRef.send(JSON.stringify({ v: 1, t: "wake", device: d.id }));
497
+ if (wsRef && wsRef.readyState === 1) wsRef.send(JSON.stringify({ v: 1, t: "wake", device: d.id, note }));
471
498
  }
472
499
  };
473
500
 
@@ -523,6 +550,7 @@ async function publisherLoop() {
523
550
  if (timer) clearInterval(timer);
524
551
  timer = setInterval(() => void publish(ws), PUBLISH_MS);
525
552
  timer.unref?.();
553
+ void recordGitAnchor("boot"); // seed the first boundary so turn 1 is diffable
526
554
  return;
527
555
  }
528
556
  if (m.t === "room.update") {
@@ -905,6 +933,217 @@ async function publisherLoop() {
905
933
  : stderr.split("\n")[0] || err.message });
906
934
  }
907
935
  }
936
+ if (op === "file.tree") {
937
+ // READ-ONLY file index (filev pattern): tracked files from `git ls-files`
938
+ // (already .gitignore-aware) with `git status --porcelain` markers overlaid.
939
+ // Same hardened gitRead as diff.get — no payload-chosen cwd, scrubbed env.
940
+ // Untracked files are invisible by design: only what git tracks can be read.
941
+ const repoDir = diffRepoDir();
942
+ try {
943
+ const [files, status] = await Promise.all([
944
+ gitRead(["ls-files"], repoDir, 10_000),
945
+ gitRead(["status", "--porcelain"], repoDir, 10_000),
946
+ ]);
947
+ // XY status + path; rename lines take the "-> " target. Quoted paths
948
+ // (git quotes specials) are unquoted minimally — markers are advisory.
949
+ const markers = new Map();
950
+ for (const line of String(status.stdout).split("\n")) {
951
+ const m = /^([ MARDRCU?!]{1,2})\s+(.+)$/.exec(line);
952
+ if (!m || !m[1].trim()) continue; // "??" and blank lead chars alike
953
+ let target = m[2].split(" -> ").pop() ?? m[2];
954
+ if (target.startsWith('"') && target.endsWith('"')) target = target.slice(1, -1);
955
+ markers.set(target, m[1].trim());
956
+ }
957
+ const all = String(files.stdout).split("\n").filter(Boolean);
958
+ const capped = all.length > MAX_FILE_ENTRIES;
959
+ const entries = (capped ? all.slice(0, MAX_FILE_ENTRIES) : all)
960
+ .map((path) => ({ path, status: markers.get(path) ?? null }))
961
+ .sort((a, b) => a.path.localeCompare(b.path));
962
+ return void replyTo({ op: "file.tree.result", files: entries, capped, total: all.length });
963
+ } catch (e) {
964
+ const err = e instanceof Error ? e : new Error(String(e));
965
+ const stderr = String(e?.stderr ?? "");
966
+ const noRepo = /not a git repository/i.test(`${err.message}\n${stderr}`);
967
+ log(`files: ${m.device} tree refused: ${err.message}`);
968
+ return void replyTo({ op: "error", code: noRepo ? "diff.repo" : "files.tree",
969
+ message: noRepo ? "the plugin directory is not a git repository"
970
+ : stderr.split("\n")[0] || err.message });
971
+ }
972
+ }
973
+ if (op === "file.read") {
974
+ // READ-ONE-FILE with filev's hardening rules: git-tracked paths only (the
975
+ // tree above is the whitelist), no leading /, no .., no NUL, ≤ 255 chars,
976
+ // realpath must stay under the repo (a symlink planted inside must not
977
+ // read outside), size capped — and the bytes go back as text, nothing else.
978
+ const path = typeof payload.path === "string" ? payload.path : "";
979
+ if (!/^[^/\0][^\0]{0,254}$/.test(path) || path.split("/").includes("..")) {
980
+ return void replyTo({ op: "error", code: "bad-path", message: "file.read needs a root-relative path without .." });
981
+ }
982
+ const repoDir = diffRepoDir();
983
+ try {
984
+ const repoReal = realpathSync(repoDir);
985
+ const full = join(repoDir, path);
986
+ let st;
987
+ try { st = statSync(full); } catch { st = null; }
988
+ if (!st || !st.isFile()) {
989
+ return void replyTo({ op: "error", code: "no-file", message: "no such file in the repo" });
990
+ }
991
+ if (!realpathSync(full).startsWith(repoReal + "/")) {
992
+ return void replyTo({ op: "error", code: "bad-path", message: "path escapes the repo" });
993
+ }
994
+ const tracked = await gitRead(["ls-files", "--", path], repoDir, 10_000);
995
+ if (!String(tracked.stdout).trim()) {
996
+ return void replyTo({ op: "error", code: "no-file", message: "not a tracked file" });
997
+ }
998
+ const truncated = st.size > MAX_FILE_BYTES;
999
+ const buf = readFileSync(full);
1000
+ let text = truncated ? buf.subarray(0, MAX_FILE_BYTES).toString("utf8") : buf.toString("utf8");
1001
+ // JSON escaping can inflate a hostile file several-fold (\u0000 = 6x);
1002
+ // shrink until the ENVELOPE fits the gate's 256KiB frame cap — a reply
1003
+ // that kills the publisher's own socket is worse than a shorter view.
1004
+ while (Buffer.byteLength(JSON.stringify({ t: "frame", payload: { op: "file.read.result", path, text } })) > 240 * 1024 && text.length > 0) {
1005
+ text = text.slice(0, Math.floor(text.length * 0.8));
1006
+ }
1007
+ const lines = text.length ? text.split("\n").length : 0;
1008
+ return void replyTo({ op: "file.read.result", path, text, lines, bytes: st.size, truncated: truncated || Buffer.byteLength(text) < Math.min(st.size, MAX_FILE_BYTES) });
1009
+ } catch (e) {
1010
+ const err = e instanceof Error ? e : new Error(String(e));
1011
+ log(`files: ${m.device} read ${path} refused: ${err.message}`);
1012
+ return void replyTo({ op: "error", code: "files.read", message: err.message });
1013
+ }
1014
+ }
1015
+ if (op === "review.files" || op === "review.diff") {
1016
+ // READ-ONLY review scopes — the reviewr pattern, mobile: `uncommitted`,
1017
+ // `branch` (three-dot vs upstream/main — merge-base for free), `turn`
1018
+ // (diff of the last settled agent turn, anchored by the git-anchors
1019
+ // journal — no ref writes). All git flows through the hardened gitRead.
1020
+ const scope = typeof payload.scope === "string" ? payload.scope : "";
1021
+ if (!["uncommitted", "branch", "turn"].includes(scope)) {
1022
+ return void replyTo({ op: "error", code: "bad-scope", message: "review.* needs scope uncommitted | branch | turn" });
1023
+ }
1024
+ const repoDir = diffRepoDir();
1025
+ try {
1026
+ let range;
1027
+ let base = null;
1028
+ if (scope === "uncommitted") {
1029
+ range = ["HEAD"];
1030
+ } else if (scope === "branch") {
1031
+ // Candidates avoid ref-expression braces (@{upstream}, ^{commit}) —
1032
+ // gitRead's arg grammar keeps them out, so plain names only.
1033
+ for (const cand of ["origin/main", "origin/master", "main", "master"]) {
1034
+ try {
1035
+ const { stdout } = await gitRead(["rev-parse", "--verify", cand], repoDir, 5_000);
1036
+ const sha = String(stdout).trim();
1037
+ if (/^[0-9a-f]{7,40}$/.test(sha)) { base = sha; break; }
1038
+ } catch { /* try the next candidate */ }
1039
+ }
1040
+ if (!base) {
1041
+ return void replyTo({ op: "error", code: "no-base", message: "không thấy upstream/main — không định vị được scope branch" });
1042
+ }
1043
+ range = [`${base}...HEAD`];
1044
+ } else {
1045
+ const anchors = readState(gitAnchorsFile()).anchors;
1046
+ if (!Array.isArray(anchors) || anchors.length < 2) {
1047
+ return void replyTo({ op: "error", code: "no-anchor", message: "chưa đủ 2 mốc settle — chờ agent settle thêm một lượt để có diff lượt cuối" });
1048
+ }
1049
+ const from = anchors[anchors.length - 2].head;
1050
+ const to = anchors[anchors.length - 1].head;
1051
+ range = [`${from}..${to}`];
1052
+ base = from;
1053
+ }
1054
+ if (op === "review.files") {
1055
+ const numstat = await gitRead(["diff", "--no-color", "--numstat", ...range], repoDir, 10_000);
1056
+ const files = [];
1057
+ for (const line of String(numstat.stdout).split("\n")) {
1058
+ const nm = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
1059
+ if (!nm) continue;
1060
+ let path = nm[3].split(" -> ").pop() ?? nm[3];
1061
+ if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
1062
+ files.push({ path, plus: nm[1] === "-" ? null : Number(nm[1]), minus: nm[2] === "-" ? null : Number(nm[2]) });
1063
+ }
1064
+ let untracked = 0;
1065
+ if (scope === "uncommitted") {
1066
+ // `git diff` never sees untracked files; the porcelain overlay adds
1067
+ // them as zero-stat rows so the review list matches reality.
1068
+ const status = await gitRead(["status", "--porcelain"], repoDir, 10_000);
1069
+ for (const line of String(status.stdout).split("\n")) {
1070
+ const sm = /^\?\?\s+(.+)$/.exec(line);
1071
+ if (!sm) continue;
1072
+ let path = sm[1].split(" -> ").pop() ?? sm[1];
1073
+ if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
1074
+ if (files.some((f) => f.path === path)) continue;
1075
+ files.push({ path, plus: null, minus: null, status: "??" });
1076
+ untracked++;
1077
+ }
1078
+ }
1079
+ files.sort((a, b) => a.path.localeCompare(b.path));
1080
+ const capped = files.length > MAX_REVIEW_FILES;
1081
+ log(`review: ${m.device} files ${scope}${base ? ` @${String(base).slice(0, 8)}` : ""} -> ${files.length} file${untracked ? ` (${untracked} chưa track)` : ""}`);
1082
+ return void replyTo({ op: "review.files.result", scope, base, files: capped ? files.slice(0, MAX_REVIEW_FILES) : files, capped });
1083
+ }
1084
+ const path = typeof payload.path === "string" ? payload.path : "";
1085
+ if (!/^[^/\0][^\0]{0,254}$/.test(path) || path.split("/").includes("..")) {
1086
+ return void replyTo({ op: "error", code: "bad-path", message: "review.diff needs a root-relative path without .." });
1087
+ }
1088
+ const { stdout } = await gitRead(["diff", "--no-color", "--patch", ...range, "--", path], repoDir, 10_000);
1089
+ const bytes = Buffer.byteLength(stdout, "utf8");
1090
+ const truncated = bytes > MAX_DIFF_BYTES;
1091
+ const text = truncated ? Buffer.from(stdout, "utf8").subarray(0, MAX_DIFF_BYTES).toString("utf8") : stdout;
1092
+ log(`review: ${m.device} diff ${scope} ${path} -> ${bytes}B${truncated ? " (capped at 128KiB)" : ""}`);
1093
+ return void replyTo({ op: "review.diff.result", scope, path, base, text, bytes, truncated });
1094
+ } catch (e) {
1095
+ const err = e instanceof Error ? e : new Error(String(e));
1096
+ const stderr = String(e?.stderr ?? "");
1097
+ const noRepo = /not a git repository/i.test(`${err.message}\n${stderr}`);
1098
+ log(`review: ${m.device} ${op} ${scope} refused: ${err.message}`);
1099
+ return void replyTo({ op: "error", code: noRepo ? "diff.repo" : "review",
1100
+ message: noRepo ? "the plugin directory is not a git repository" : stderr.split("\n")[0] || err.message });
1101
+ }
1102
+ }
1103
+ if (op === "review.send") {
1104
+ // ACT — ship the phone's line comments to the agent. The Pi worker queue
1105
+ // is the one delivery leg that already exists (receipts, wake-on-settle);
1106
+ // the comments ride as a <file-comments> block the agent reads structurally.
1107
+ if (process.env.HERDGATE_PI_WORKER !== "1") {
1108
+ return void replyTo({ op: "error", code: "pi_worker_disabled", message: "host chưa bật Pi worker — review.send cần HERDGATE_PI_WORKER=1" });
1109
+ }
1110
+ if (devices.find((d) => d.id === m.device)?.scope !== "act") {
1111
+ return void replyTo({ op: "error", code: "requires-act", message: "review.send needs an act device" });
1112
+ }
1113
+ const comments = Array.isArray(payload.comments) ? payload.comments : [];
1114
+ if (!comments.length || comments.length > MAX_REVIEW_COMMENTS) {
1115
+ return void replyTo({ op: "error", code: "bad-comments", message: `review.send needs 1..${MAX_REVIEW_COMMENTS} comments` });
1116
+ }
1117
+ for (const c of comments) {
1118
+ const okPath = typeof c?.path === "string" && /^[^/\0][^\0]{0,254}$/.test(c.path) && !c.path.split("/").includes("..");
1119
+ const okLine = Number.isInteger(c?.line) && c.line >= 1 && c.line <= 1e6;
1120
+ const okEnd = c?.endLine === undefined || (Number.isInteger(c.endLine) && c.endLine >= c.line && c.endLine <= 1e6);
1121
+ const okText = typeof c?.text === "string" && c.text.trim().length > 0 && c.text.length <= 500;
1122
+ if (!okPath || !okLine || !okEnd || !okText) {
1123
+ return void replyTo({ op: "error", code: "bad-comment", message: "comment needs { path, line 1..1e6, endLine?, text 1..500 }" });
1124
+ }
1125
+ }
1126
+ const body = comments.map((c) => `${c.path}:${c.line}${c.endLine ? `-${c.endLine}` : ""} — ${c.text}`).join("\n");
1127
+ const prompt = `Xử lý review comments trên diff từ mobile:\n\n<file-comments>\n${body}\n</file-comments>\n\nTừng comment: xem chỗ chỉ dẫn, sửa nếu đúng, chạy test liên quan, commit nếu đạt. Báo lại ngắn gọn từng dòng đã xử lý thế nào.`;
1128
+ const file = jobsFile(workerBase());
1129
+ let jobs;
1130
+ try { jobs = readJobs(file); }
1131
+ catch (e) {
1132
+ return void replyTo({ op: "error", code: "worker-queue", message: `queue unreadable: ${e instanceof Error ? e.message : String(e)}` });
1133
+ }
1134
+ const pending = [...jobs.values()].filter((j) => j.state === "queued" || j.state === "running").length;
1135
+ if (pending >= MAX_PENDING) {
1136
+ return void replyTo({ op: "error", code: "queue-full", message: `worker queue is full (${MAX_PENDING} pending)` });
1137
+ }
1138
+ const jobId = randomUUID();
1139
+ try {
1140
+ appendJob(file, { v: 1, id: jobId, prompt, ts: Date.now(), state: "queued", principal: `device:${m.device}`, kind: "review" });
1141
+ } catch (e) {
1142
+ return void replyTo({ op: "error", code: "worker-queue", message: `queue append failed: ${e instanceof Error ? e.message : String(e)}` });
1143
+ }
1144
+ log(`review: ${m.device} sent ${comments.length} comment(s) as job ${jobId}`);
1145
+ return void replyTo({ op: "review.sent", id: jobId, state: "queued", count: comments.length });
1146
+ }
908
1147
  if (op === "pane.focus") {
909
1148
  // Focus a pane on the host's Herdr. Fire-and-forget spawn, never awaited:
910
1149
  // a phone must not hang on a TUI command. argv comes from the --help probe.
@@ -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
+ }
@@ -21,7 +21,7 @@ CLOUD="$STAGE/$NAME"
21
21
  mkdir -p "$CLOUD/runtime/web/icons" "$CLOUD/scripts"
22
22
 
23
23
  npm run build:cloud -- --outDir "$CLOUD/runtime"
24
- cp src/web/{index.html,app.js,app.css,app.webmanifest,sw.js,e2e.js} "$CLOUD/runtime/web/"
24
+ cp src/web/{index.html,app.js,app.css,app.webmanifest,sw.js,e2e.js,push-decision.js} "$CLOUD/runtime/web/"
25
25
  cp src/web/icons/{icon.svg,icon-192.png,icon-512.png} "$CLOUD/runtime/web/icons/"
26
26
  cp templates/cloud/{Dockerfile,compose.yml,compose.env.example,.dockerignore,herdgate-cloud.service,herdgate-cloud-edge.service,Caddyfile.example,README.md} "$CLOUD/"
27
27
  cp templates/cloud/gitignore.example "$CLOUD/.gitignore"