@bom0792/herdgate 0.9.37 → 0.9.39

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.
@@ -118,3 +118,68 @@ nó mở menu chọn tương tác và agent sẽ không ràng buộc session. **
118
118
  để khởi chạy/khôi phục agent**: phản hồi của `pane run` chỉ là "input đã xếp", không chờ readiness,
119
119
  không ràng buộc agent — agent sẽ hiện không có session và controller không quản lý được.
120
120
  Muốn đóng agent: `/quit` trong pane đó, đợi shell prompt; đóng pane phải do người dùng quyết định.
121
+
122
+ ## Wake protocol — khi nhận `[herdgate-wake …]`
123
+
124
+ Publisher bắn wake-frame vào pane cha khi receipt của agent con settle. Frame tự mang
125
+ chỉ thị, nhưng ghi nhớ bền ở đây (sống sót qua context compaction):
126
+
127
+ **Nhận `[herdgate-wake child=<tên> id=<uuid> status=…]` → làm TRỌN trong đúng turn đó.**
128
+ **Reply PHẢI mở đầu bằng banner 1 dòng**: `🔔 WAKE — agent <tên> <status>: <kết quả trong 1 câu>`
129
+ (id receipt nằm ở dòng sau). Turn wake nhanh và dễ bị người dùng bỏ qua — mở đầu bằng id
130
+ hoặc văn thường là như không báo (đã xảy ra: user nhìn thẳng pane vẫn nghĩ chưa có gì đến):
131
+ 1. Chạy test mục tiêu của phần việc con vừa làm (`node --test test/<file>.test.ts`).
132
+ 2. Review diff (`git diff` + `git status`) — đúng whitelist file đã giao.
133
+ 3. Commit nếu đạt (thông điệp ghi rõ agent nào, spawn id).
134
+ 4. Báo user ngắn gọn ngay trong reply (agent nào xong, commit gì, test bao nhiêu pass).
135
+ 5. Cần report đầy đủ: `node experiments/pi-receipt/query.mjs --gate <gate> --device <d> --secret <s> --id <uuid> --body`.
136
+
137
+ KHÔNG chỉ ack rồi kết thúc turn — mỗi lần ack suông là một phần việc chết chờ user nhắc
138
+ (đã xảy ra: 3 wake đến, 0 được xử lý trọn). Cây agent: `node experiments/pi-spawn/dag.mjs`.
139
+
140
+ ## Giao việc cho subagent — MỘT lệnh
141
+
142
+ ```bash
143
+ node experiments/pi-spawn/task.mjs start <tên> <taskfile> [--cwd DIR] [--tab] # spawn+arm+prompt, marker tự đúng định dạng
144
+ node experiments/pi-spawn/task.mjs continue <tên> <taskfile|text> # re-prompt con đang sống
145
+ node experiments/pi-spawn/task.mjs status [tên] # recent-first, kèm receipt
146
+ node experiments/pi-spawn/task.mjs close <tên> # delegate spawn.mjs close
147
+ ```
148
+ Lệnh gốc spawn.mjs giữ cho edge case. Không tự ghép spawn+arm+prompt tay nữa —
149
+ marker sai định dạng từng làm cả đợt agent mù observation.
150
+
151
+ ## Vòng đời con — dọn ngay, không tích tụ
152
+
153
+ Parent là chủ vòng đời con mình. Sau khi wake đã xử lý (test/commit xong), nếu KHÔNG còn
154
+ việc kế tiếp đã lên kế hoạch cho con đó → **đóng ngay trong cùng turn**:
155
+
156
+ ```bash
157
+ node experiments/pi-spawn/spawn.mjs close <tên> # đóng tab/pane con; từ chối nếu đang working
158
+ ```
159
+
160
+ Record spawn vẫn còn nên cần lại chỉ là `spawn.mjs restore <tên>` (đúng session one-id).
161
+ Sau reboot/machine restart: node experiments/pi-spawn/spawn.mjs revive (dry-run trước nếu muốn xem kế hoạch).
162
+ Chỉ giữ con sống khi còn job tiếp theo cho nó. Pane/tab của NGƯỜI DÙNG không bao giờ tự đóng.
163
+
164
+ ## Nhánh chính hay worktree? — tránh xung đột trước khi spawn
165
+
166
+ **Làm trực tiếp nhánh chính (checkout đang mở)** khi thỏa CẢ HAI:
167
+ - Chỉ MỘT người viết tại một thời điểm (controller đơn mình, hoặc các agent có
168
+ whitelist file RỜI nhau hoàn toàn — ghi rõ whitelist trong prompt giao việc), VÀ
169
+ - Việc nhỏ/vừa, user đang theo dõi và cần commit ngay.
170
+
171
+ **BẮT BUỘC worktree riêng** khi:
172
+ - ≥2 subagent song song đụng CÙNG module/file (whitelist không tách nổi), HOẶC
173
+ - Việc dài/lớn trong lúc user có thể tự gõ lên repo chính, HOẶC thử nghiệm chưa chắc giữ.
174
+
175
+ ```bash
176
+ herdr worktree create --cwd <repo> --branch hg-<task> # tạo + mở workspace worktree
177
+ node experiments/pi-spawn/spawn.mjs spawn <tên> --cwd <repo>/../<worktree-dir> --tab
178
+ # con làm + test TRONG worktree (receipt scope theo cwd nên tự tách khỏi journal chính)
179
+ # wake về → controller verify trong worktree → về repo chính: git merge, rồi:
180
+ herdr worktree remove # dọn worktree sau khi merge
181
+ ```
182
+
183
+ Nguyên tắc: whitelist file là lớp 1; worktree là lớp 2 khi lớp 1 không đủ. Không bao giờ
184
+ để hai agent cùng ghi một file ở hai nơi rồi tự hòa giải — merge là việc của controller,
185
+ trên repo chính, sau khi từng con đã settle.
package/DESIGN.md CHANGED
@@ -219,3 +219,31 @@ bridge-side. herdgate: the cloud in the middle, own identity, host renders, clou
219
219
  ideas kept: hello-first auth, hashed tokens, scope-aware routing, single-use artifacts, rate limits everywhere.
220
220
  The parts dropped: mod sandboxing (the host is trusted code on its own machine), tree recording (the host owns
221
221
  its UI), Tailscale (public via cloudflared).
222
+
223
+
224
+ ## Wake by herdr event (2026-11-22)
225
+
226
+ Settles and pane deaths are **herdr's observations**, not the child's. The plugin manifest
227
+ hooks `pane.agent_status_changed`, `pane.exited`, `pane.closed` into
228
+ `plugin/server/wake-event.mjs` — a short-lived process per event:
229
+
230
+ ```
231
+ herdr event ─▶ wake-event.mjs ─▶ registry lookup (spawn children only)
232
+ ├─ settle (idle|done, revision-stable) ─▶ 🔔 frame → parent pane
233
+ └─ death (no final receipt, not closedBy parent) ─▶ DIED frame (once)
234
+ ```
235
+
236
+ Discipline layered from live incidents and the herdr-pings/sidebar/cats deep research:
237
+ flock try_lock per event (burst dedup) · heartbeat liveness (>20s stale revision =
238
+ corpse echo, dropped) · generation tokens on every frame (`gen=<revision>`) ·
239
+ stamp-and-byte-verify sidecar writes · parent quiet-wait before typing (pane run,
240
+ never the RPC channel) · `parentPaneId` recorded at spawn beats session-file lookup.
241
+ The publisher keeps receipts purely as evidence (device push); it no longer wakes.
242
+
243
+ ## State discipline (2026-11-22)
244
+
245
+ Spawn registry and receipt-adjacent state follow herdr-portfwd's rules: a damaged file
246
+ throws WITH ITS NAME (never reads as empty), writes are O_EXCL temp + rename with a
247
+ stable sort (byte-stable files), and a state directory writable by group/other is
248
+ refused outright. `startCloud` resolves only after the sshd has bound (a Cloud whose
249
+ `.ssh.port` is still zero made ssh2 silently dial :22 — a live flake).
package/README.md CHANGED
@@ -38,9 +38,16 @@ src/cloud/ the gateway: stores, pairing, routing, HTTP/WS, CLI (main.ts)
38
38
  src/agent/ HerdGateAgent SDK + AgentAdapter (what a host app implements)
39
39
  src/host/ standalone host CLI (no Herdr needed) + the `herdr api snapshot` adapter
40
40
  plugin/ the Herdr TUI plugin: herdr-plugin.toml + server/ (what `herdr plugin link` loads)
41
+ — op table, wake-event hooks, receipts/observers/attachments modules
42
+ experiments/ host-local CLIs + SDK pieces the controller drives by hand:
43
+ pi-spawn (task.mjs lifecycle, registry, pipeline, dag),
44
+ pi-receipt (observer that runs INSIDE children, query/search/usage/gc),
45
+ pi-worker (run-jobs, scheduler, MCP, durable probes)
46
+ docs/research/ two-tier deep research on 12 herdr plugins (2,426 lines, file:line-sourced)
41
47
  app-mod/ the Herdr app mod: mods/herdgate/ (what `herdr-app check` validates)
42
48
  src/web/ the PWA a device opens — served by the cloud, same origin as the WS legs
43
- test/ e2e relay, the adapter, and the plugin's own commands
49
+ test/ 57 files / 275 tests: relay e2e, plugin ops over the device channel,
50
+ wake-event semantics, spawn lifecycle, sysmon/port fixtures, web assets
44
51
  ```
45
52
 
46
53
  ## Self-hosted release
@@ -112,6 +119,68 @@ HERDGATE_URL=https://herd.example.com HERDGATE_ROOM_TOKEN=… npm run host
112
119
 
113
120
  Devices pair into the room and ask for `{op:"view"}`; the host answers with the current Herdr metadata.
114
121
 
122
+ ## The subagent fleet (receipts · wake · observers)
123
+
124
+ Beyond relaying, the Herdr plugin runs a full **subagent observability and lifecycle stack**.
125
+ Everything below is local-first (append-only JSONL + registry under XDG state dirs), fail-closed,
126
+ and testable — 275 tests cover it.
127
+
128
+ ### Identity and evidence — receipts
129
+ Every spawned child gets a **one-id** (`spawn:<uuid>`) recorded in a bounded registry; panes and
130
+ session files are carriers, never the address. The arm→prompt handshake acknowledges via an ack
131
+ file (no sleep-and-hope). Each marked request becomes a **receipt**: status/reason, usage tokens/$,
132
+ `turns`/`lastActivityAt`, a leak-safe title, delivery state (`delivered|stalled|unverified`), a
133
+ failure **phase** (`failed_before_dispatch` vs post-dispatch), and an optional gated body archive.
134
+ Search is BM25 (diacritic-folded) over bodies+transcripts; devices see publicReceipt shapes only.
135
+ A journal GC (dry-run default) never deletes `unknown` — unresolved evidence stays.
136
+
137
+ ### Wake — herdr is the observer
138
+ Settles no longer depend on child cooperation: the plugin manifest hooks herdr's own events
139
+ (`pane.agent_status_changed`, `pane.exited`, `pane.closed`) into `server/wake-event.mjs`, a
140
+ short-lived process per event. A child's closed turn (or death without a settle) becomes a
141
+ `🔔 WAKE` frame typed into the parent pane — after revision-stability quiet-wait, deduped by
142
+ generation, guarded against event bursts (flock) and corpse echoes (heartbeats), with title/tokens
143
+ enriched from the receipt journal when present. Receipts are evidence; **herdr is the trigger**.
144
+
145
+ ### Lifecycle — one command per verb
146
+ ```sh
147
+ node experiments/pi-spawn/task.mjs start <name> <taskfile> --tab # spawn+arm+prompt, marker-safe
148
+ node experiments/pi-spawn/task.mjs continue <name> <text|file> # self-describing re-prompt
149
+ node experiments/pi-spawn/task.mjs status [name] # recent-first, receipt-aware
150
+ node experiments/pi-spawn/spawn.mjs close <id> # 3-layer retire + generation check
151
+ node experiments/pi-spawn/spawn.mjs revive [--dry-run] # after a reboot: exact sessions back
152
+ node experiments/pi-spawn/pipeline.mjs run <task.md> --fake # worktree→agent→test→retry→reviewer
153
+ ```
154
+ See `.agents/skills/herdr/SKILL.md` for the operating protocol (in-turn wake handling, the
155
+ no-accumulation close rule, worktree-vs-main-branch whitelists).
156
+
157
+ ### Device-channel ops (the PWA's vocabulary)
158
+ `view` · `receipt.query/search/body/ack` · `receipt.enrich` (model/context/usage from the transcript)
159
+ · `usage.rollup` · `diff.get` (hardened git: hooks off, env scrubbed, `~ ^` refs)
160
+ · `sysmon.snapshot` (per-agent CPU/RAM from /proc, cutime-aware) · `ports.list` (listeners attributed
161
+ by process ancestry; unattributed stay honest) · `attachment.upload/list` (magic-byte photos from
162
+ the phone to the agent's own disk, 0700/0600, uuid names) — plus the SSH/mobile leg below.
163
+
164
+ ### Mobile transport
165
+ One persistent shell with marker framing replaces exec-per-command; phone keystrokes enter a
166
+ bounded, coalescing, in-order-acked queue that resyncs instead of replaying; file polls are
167
+ checksum-stamped (`unchanged` costs one word).
168
+
169
+ ### Latency budget (measured 22/11)
170
+
171
+ Interactive typing (mobile TUI, remote herdr attach) rides the SSH bridge **direct**
172
+ to the host — no CDN hop, feels local. The control/PWA leg goes through the tunnel
173
+ edge (~130ms RTT hairpin from the same LAN; a phone on 4G sees similar). To keep
174
+ that leg smooth the publisher now:
175
+
176
+ - pushes view snapshots every `HERDGATE_PUBLISH_MS` (default 30s; the home unit sets
177
+ 5s — a settle is visible on the phone within seconds, not half a minute);
178
+ - replays the last snapshot for a `view` op inside `HERDGATE_SNAPSHOT_FRESH_MS`
179
+ (default 2s) instead of spawning `herdr api snapshot` again — a view op costs ~0
180
+ server-side work when the cache is warm;
181
+ - coalesces concurrent snapshot demands into one spawn (single-flight), and a cached
182
+ view no longer resets the change-sig (so it cannot re-wake away phones for nothing).
183
+
115
184
  ## The SSH leg (the Herdr phone app)
116
185
 
117
186
  The phone app adds machines over SSH. Herdgate terminates SSH at the Gate; use the Gate's reachable SSH
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom0792/herdgate",
3
- "version": "0.9.37",
3
+ "version": "0.9.39",
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": {
@@ -20,6 +20,7 @@
20
20
  "postinstall": "node scripts/patch-ssh2.mjs && node scripts/install-pi-skills.mjs"
21
21
  },
22
22
  "dependencies": {
23
+ "qrcode-terminal": "^0.12.0",
23
24
  "ssh2": "^1.17.0",
24
25
  "ws": "^8.18.0"
25
26
  },
@@ -1,6 +1,6 @@
1
1
  id = "dev.herdgate.host"
2
2
  name = "herdgate"
3
- version = "0.1.0"
3
+ version = "0.9.38"
4
4
  min_herdr_version = "0.9.0"
5
5
  description = "Publish this Herdr session to your own devices through a herdgate cloud relay (read-only by default)."
6
6
  platforms = ["linux", "macos"]
@@ -12,6 +12,23 @@ platforms = ["linux", "macos"]
12
12
  [[startup]]
13
13
  command = ["node", "server/index.mjs", "serve"]
14
14
 
15
+ # Wake-by-event: herdr itself reports pane lifecycle and agent settles. Each
16
+ # hook is a short-lived process (server/wake-event.mjs) that resolves the spawn
17
+ # registry's parent edge and delivers one wake frame — no daemon, no polling,
18
+ # and no cooperation (arm/marker/observer) needed from the child. User panes
19
+ # are not in the registry, so their events exit silently.
20
+ [[events]]
21
+ on = "pane.agent_status_changed"
22
+ command = ["node", "server/wake-event.mjs"]
23
+
24
+ [[events]]
25
+ on = "pane.exited"
26
+ command = ["node", "server/wake-event.mjs"]
27
+
28
+ [[events]]
29
+ on = "pane.closed"
30
+ command = ["node", "server/wake-event.mjs"]
31
+
15
32
  [[actions]]
16
33
  id = "status"
17
34
  title = "herdgate: show pairing status"
@@ -0,0 +1,184 @@
1
+ // Photo/file attachments uploaded from the PWA composer (Wave C3).
2
+ //
3
+ // The herdcats lesson (docs/research/2026-11-21-marketplace/deep/cats.md,
4
+ // resolver.rs / runtime.mjs endpoint hygiene): files arriving from a device
5
+ // land ON THE AGENT MACHINE under a private directory the plugin owns —
6
+ // * every directory level is mkdir'd then chmod'd 0700 one by one, and a
7
+ // level that already exists as a symlink is refused ('symlink'),
8
+ // * the client-supplied name is NEVER trusted for the stored filename —
9
+ // names are <uuid>.<ext>, and <ext> comes from sniffing magic bytes,
10
+ // not from the name or the declared mime type,
11
+ // * the file itself is written O_CREAT|O_EXCL mode 0600.
12
+ // The reply then carries a path hint so the Pi agent opens the file with its
13
+ // own read tool — image bytes never ride the prompt text.
14
+ //
15
+ // Pure exports, no sockets: the device ops in index.mjs call these.
16
+
17
+ import { randomUUID } from 'node:crypto';
18
+ import {
19
+ chmodSync, closeSync, constants, lstatSync, mkdirSync, openSync, readdirSync, rmSync, statSync, writeSync,
20
+ } from 'node:fs';
21
+ import { dirname, join, resolve, sep } from 'node:path';
22
+
23
+ export const MAX_ATTACHMENT_BYTES = 4 * 1024 * 1024; // 4 MiB hard cap, device and host agree
24
+ export const ATTACHMENTS_DIR = 'attachments';
25
+ const MONTH_DIR = /^\d{4}-(0[1-9]|1[0-2])$/;
26
+ /** Stored filenames only: <uuid>.<ext> with ext from the magic-byte whitelist. */
27
+ const STORED = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(png|jpe?g|webp|gif)$/;
28
+ const DAY_MS = 86400e3;
29
+
30
+ /** Sniff the image type from magic bytes — the name and mime are never trusted.
31
+ * PNG \x89PNG\r\n\x1a\n · JPEG \xFF\xD8\xFF · GIF "GIF8" · WEBP "RIFF"…."WEBP". */
32
+ export function sniffType(bytes) {
33
+ if (!Buffer.isBuffer(bytes)) return null;
34
+ const has = (offset, hex) => {
35
+ if (bytes.length < offset + hex.length) return false;
36
+ return hex.every((byte, i) => bytes[offset + i] === byte);
37
+ };
38
+ if (has(0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'png';
39
+ if (has(0, [0xff, 0xd8, 0xff])) return 'jpg';
40
+ if (has(0, [0x47, 0x49, 0x46, 0x38])) return 'gif'; // "GIF8" (GIF87a/GIF89a)
41
+ if (has(0, [0x52, 0x49, 0x46, 0x46]) && has(8, [0x57, 0x45, 0x42, 0x50])) return 'webp'; // RIFF<u32>WEBP
42
+ return null;
43
+ }
44
+
45
+ /** Create base/attachments/<yyyy-mm> one level at a time. Ancestors above base
46
+ * are only created when missing (never chmod'd — /tmp and friends are not
47
+ * ours; on macOS /tmp is even a system symlink). From base down — the
48
+ * plugin's own territory — every level is mkdir'd (0700) then chmod'd 0700,
49
+ * created or not, and a level that exists as a symlink is refused. Returns
50
+ * the month directory path. */
51
+ function ensureMonthDir(base, now = new Date()) {
52
+ const month = `${now.getUTCFullYear()}-` + String(now.getUTCMonth() + 1).padStart(2, '0');
53
+ const dir = join(base, ATTACHMENTS_DIR, month);
54
+ const abs = resolve(base);
55
+ const segments = abs.split(sep).filter(Boolean);
56
+ const prefix = abs.startsWith(sep) ? sep : '';
57
+ // 1. bring base into existence (each missing ancestor mkdir'd 0700, no chmod)
58
+ let walk = prefix;
59
+ for (const part of segments) {
60
+ walk = walk === prefix ? join(prefix, part) : join(walk, part);
61
+ try { lstatSync(walk); continue; }
62
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
63
+ mkdirSync(walk, { mode: 0o700 });
64
+ chmodSync(walk, 0o700);
65
+ }
66
+ // 2. base/attachments/<month>: 0700 each level, refuse planted symlinks
67
+ let level = abs;
68
+ for (const part of [ATTACHMENTS_DIR, month]) {
69
+ level = join(level, part);
70
+ let st = null;
71
+ try { st = lstatSync(level); }
72
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
73
+ if (st) {
74
+ if (st.isSymbolicLink()) throw new Error('symlink'); // planted path — refuse, never write through it
75
+ if (!st.isDirectory()) throw new Error('not_a_directory');
76
+ } else {
77
+ mkdirSync(level, { mode: 0o700 });
78
+ }
79
+ chmodSync(level, 0o700); // every traversed level ends 0700, created or pre-existing
80
+ st = lstatSync(level); // post-create check: what we made must be a real dir
81
+ if (!st || st.isSymbolicLink() || !st.isDirectory()) throw new Error('symlink');
82
+ }
83
+ return dir;
84
+ }
85
+
86
+ /**
87
+ * Save one uploaded image: validate, sniff the type, store under
88
+ * base/attachments/<yyyy-mm>/<uuid>.<ext> (O_EXCL|O_CREAT, mode 0600).
89
+ * `name` is client metadata only — it never reaches the stored path.
90
+ * Returns { id, path }. Throws 'bad_bytes' | 'empty' | 'too_large' |
91
+ * 'bad_type' | 'symlink' — callers translate to a clear error op.
92
+ */
93
+ export function saveAttachment(base, { name, bytes }) {
94
+ if (!Buffer.isBuffer(bytes)) throw new Error('bad_bytes');
95
+ if (bytes.length === 0) throw new Error('empty');
96
+ if (bytes.length > MAX_ATTACHMENT_BYTES) throw new Error('too_large');
97
+ const type = sniffType(bytes);
98
+ if (!type) throw new Error('bad_type');
99
+ if (name !== undefined && (typeof name !== 'string' || name.length < 1 || name.length > 255)) {
100
+ throw new Error('bad_name');
101
+ }
102
+ const dir = ensureMonthDir(base);
103
+ const id = randomUUID(); // stored names are uuids — a client name is never trusted
104
+ const path = join(dir, `${id}.${type}`);
105
+ const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
106
+ try {
107
+ writeSync(fd, bytes);
108
+ } finally {
109
+ closeSync(fd);
110
+ }
111
+ chmodSync(path, 0o600); // explicit: survive any umask
112
+ return { id, path };
113
+ }
114
+
115
+ /**
116
+ * Metadata for every stored attachment (id, path, size, at) newest first.
117
+ * Never reads file contents; a missing base answers [].
118
+ */
119
+ export function listAttachments(base) {
120
+ const out = [];
121
+ const root = join(base, ATTACHMENTS_DIR);
122
+ let months = [];
123
+ try { months = readdirSync(root); }
124
+ catch { return out; }
125
+ for (const month of months.sort()) {
126
+ if (!MONTH_DIR.test(month)) continue;
127
+ let names = [];
128
+ try { names = readdirSync(join(root, month)); }
129
+ catch { continue; }
130
+ for (const name of names) {
131
+ const match = STORED.test(name);
132
+ if (!match) continue;
133
+ const path = join(root, month, name);
134
+ try {
135
+ const st = statSync(path);
136
+ if (!st.isFile()) continue;
137
+ out.push({ id: name.slice(0, 36), path, size: st.size, at: st.mtimeMs });
138
+ } catch { /* vanished mid-list: skip, never throw */ }
139
+ }
140
+ }
141
+ return out.sort((a, b) => b.at - a.at);
142
+ }
143
+
144
+ /**
145
+ * TTL sweep for stored attachments, dry-run by default (the gcJournal
146
+ * philosophy): report what `days` would reclaim, touch nothing unless
147
+ * apply: true. `at` (mtime) is the age clock; unreadable entries land in
148
+ * errors and are never deleted.
149
+ */
150
+ export function gcAttachments(base, { days = 14, apply = false, now = Date.now() } = {}) {
151
+ const at = Number.isFinite(now) ? now : Date.now();
152
+ const span = Number.isFinite(days) ? Math.max(0, Math.floor(days)) : 14;
153
+ const cutoff = at - span * DAY_MS;
154
+ const report = { attachments: 0, candidates: [], bytesReclaimable: 0, errors: [], applied: false, deleted: 0, bytesFreed: 0 };
155
+ const keep = [];
156
+ const months = new Set();
157
+ for (const entry of listAttachments(base)) {
158
+ report.attachments++;
159
+ months.add(dirname(entry.path));
160
+ if (entry.at < cutoff) {
161
+ report.candidates.push({ id: entry.id, path: entry.path, bytes: entry.size, at: entry.at });
162
+ report.bytesReclaimable += entry.size;
163
+ } else {
164
+ keep.push(entry.path);
165
+ }
166
+ }
167
+ if (!apply) return report;
168
+ report.applied = true;
169
+ for (const candidate of report.candidates) {
170
+ try {
171
+ rmSync(candidate.path, { force: false });
172
+ report.deleted++;
173
+ report.bytesFreed += candidate.bytes;
174
+ } catch (error) {
175
+ report.errors.push({ path: candidate.path, code: error.code ?? 'unlink_failed' });
176
+ }
177
+ }
178
+ // A month dir left empty by the sweep goes away too (best effort, never recursive).
179
+ for (const dir of months) {
180
+ try { rmSync(dir, { recursive: false }); }
181
+ catch { /* not empty or vanished — fine */ }
182
+ }
183
+ return report;
184
+ }
@@ -0,0 +1,126 @@
1
+ /**
2
+ * Hardened read-only git for the plugin — every `git` invocation that answers a
3
+ * device payload funnels through gitRead (the herdr-file-viewer git.rs lesson).
4
+ *
5
+ * Fail-closed by construction:
6
+ * - argv: each arg must match [A-Za-z0-9._/:-] (no space, `;`, `$()`, newline,
7
+ * unicode …), and any arg that looks like a flag must be on a tiny read-flag
8
+ * allowlist — `--upload-pack`-style option injection is refused before git
9
+ * is ever spawned (execFile never shells out, this is defense in depth).
10
+ * - cwd: never payload-chosen. Only the plugin dir itself, or the
11
+ * HERDGATE_DIFF_REPO_DIR test override. Anything else refuses.
12
+ * - env: scrubbed to PATH/HOME/LANG + GIT_OPTIONAL_LOCKS=0 (the herdr-sidebar
13
+ * lesson: a read must not take the index lock). GIT_DIR, GIT_WORK_TREE and
14
+ * every other GIT_* from the publisher's environment never cross the
15
+ * boundary, so no env can redirect which repository is read.
16
+ * - hardening flags on every run: `-c core.fsmonitor=false` and
17
+ * `-c core.hooksPath=` go before the subcommand (real global options), and
18
+ * `--no-ext-diff --no-textconv` right after a diff-family subcommand — the
19
+ * only positions git accepts them — so hostile repo config (an evil
20
+ * textconv/diff.external driver, an fsmonitor daemon, a hooks dir) can never
21
+ * execute through a read.
22
+ *
23
+ * Reads only: callers that need writes keep their own spawn, but reuse
24
+ * scrubEnv() so the write path is equally deaf to GIT_* injection.
25
+ */
26
+
27
+ import { execFile as execFileCb } from "node:child_process";
28
+ import { dirname, resolve } from "node:path";
29
+ import { fileURLToPath } from "node:url";
30
+ import { promisify } from "node:util";
31
+
32
+ const execFile = promisify(execFileCb);
33
+
34
+ /** The plugin's own directory — one of the two cwds git may ever run in. */
35
+ export const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
36
+
37
+ /** The only cwd a git read may target: the plugin dir, or the test override. */
38
+ export function diffRepoDir() {
39
+ const override = process.env.HERDGATE_DIFF_REPO_DIR;
40
+ return override ? resolve(override) : PLUGIN_DIR;
41
+ }
42
+
43
+ /**
44
+ * Child env for every git run. PATH/HOME/LANG survive (git needs them to be
45
+ * findable and to read ~/.gitconfig); GIT_OPTIONAL_LOCKS=0 is added so a read
46
+ * never touches index.lock. Everything else — GIT_DIR, GIT_WORK_TREE,
47
+ * GIT_CONFIG_COUNT, GIT_* of any kind — is dropped.
48
+ */
49
+ export function scrubEnv() {
50
+ const env = {
51
+ PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
52
+ GIT_OPTIONAL_LOCKS: "0",
53
+ };
54
+ if (process.env.HOME !== undefined) env.HOME = process.env.HOME;
55
+ if (process.env.LANG !== undefined) env.LANG = process.env.LANG;
56
+ return env;
57
+ }
58
+
59
+ /** Args must be short printable words: refs, hashes, paths, allowed flags. */
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"]);
63
+ /** Subcommands that produce diffs — the only ones that take --no-ext-diff/--no-textconv. */
64
+ const DIFF_COMMANDS = new Set(["diff", "show", "log", "whatchanged", "format-patch", "range-diff"]);
65
+
66
+ function refuse(code, message) {
67
+ const err = new Error(message);
68
+ err.code = code;
69
+ return err;
70
+ }
71
+
72
+ function validateArgs(args) {
73
+ if (!Array.isArray(args) || args.length === 0) {
74
+ throw refuse("GIT_SAFE_ARG", "gitRead refuses: args must be a non-empty array");
75
+ }
76
+ for (const arg of args) {
77
+ if (typeof arg !== "string" || !ARG_RE.test(arg)) {
78
+ throw refuse("GIT_SAFE_ARG", `gitRead refuses arg ${JSON.stringify(arg)}: only [A-Za-z0-9._/:-], 1..128 chars`);
79
+ }
80
+ if (arg.startsWith("-") && !ALLOWED_FLAGS.has(arg)) {
81
+ throw refuse("GIT_SAFE_ARG", `gitRead refuses flag ${arg}: not on the read allowlist`);
82
+ }
83
+ }
84
+ }
85
+
86
+ /** The full argv handed to git: config overrides first (they are global), the
87
+ * diff hardening flags immediately after the diff subcommand (git rejects them
88
+ * in any other position). */
89
+ function buildArgv(args) {
90
+ let i = 0;
91
+ while (i < args.length && args[i].startsWith("-")) i += args[i] === "-C" ? 2 : 1;
92
+ const argv = ["-c", "core.fsmonitor=false", "-c", "core.hooksPath="];
93
+ if (DIFF_COMMANDS.has(args[i])) {
94
+ argv.push(...args.slice(0, i + 1), "--no-ext-diff", "--no-textconv", ...args.slice(i + 1));
95
+ } else {
96
+ argv.push(...args);
97
+ }
98
+ return argv;
99
+ }
100
+
101
+ /**
102
+ * Run one hardened read-only git command.
103
+ *
104
+ * @param {string[]} args git argv tail, e.g. ["show", "--no-color", "--stat", "--patch", ref]
105
+ * or ["-C", worktree, "diff", "--stat"] (git is pinned to a safe start cwd and
106
+ * re-pointed with -C — the filev pattern: git除外 vì dùng -C).
107
+ * @param {string} [cwd] where git starts; must be the plugin dir or the
108
+ * HERDGATE_DIFF_REPO_DIR override, otherwise the call refuses.
109
+ * @param {number} [timeoutMs] kill git after this long (default 10s).
110
+ * @param {number} [maxBuffer] output cap (default 8 MiB).
111
+ * @returns {Promise<{stdout: string, stderr: string}>} execFile's result, so
112
+ * callers keep their existing error mapping (e.stderr, exit codes).
113
+ */
114
+ export async function gitRead(args, cwd = diffRepoDir(), timeoutMs = 10_000, maxBuffer = 8 * 1024 * 1024) {
115
+ validateArgs(args);
116
+ const allowed = new Set([PLUGIN_DIR]);
117
+ if (process.env.HERDGATE_DIFF_REPO_DIR) allowed.add(resolve(process.env.HERDGATE_DIFF_REPO_DIR));
118
+ const startDir = resolve(cwd);
119
+ if (!allowed.has(startDir)) {
120
+ throw refuse(
121
+ "GIT_SAFE_CWD",
122
+ `gitRead refuses cwd ${cwd}: git reads run only in the plugin dir or HERDGATE_DIFF_REPO_DIR`,
123
+ );
124
+ }
125
+ return execFile("git", buildArgv(args), { cwd: startDir, timeout: timeoutMs, maxBuffer, env: scrubEnv() });
126
+ }