@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.
@@ -1,15 +1,13 @@
1
1
  #!/usr/bin/env node
2
2
  // Subset of the Core API for TUI panes. Input requires explicit local opt-in.
3
- import { execFile } from "node:child_process";
4
3
  import { createHash } from "node:crypto";
5
4
  import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
6
5
  import { open as openFile } from "node:fs/promises";
7
6
  import { hostname, homedir } from "node:os";
8
7
  import { dirname, join } from "node:path";
9
- import { promisify, stripVTControlCharacters } from "node:util";
10
- import { openTerminal, validDimension } from "./mobile-tui-stream.mjs";
8
+ import { stripVTControlCharacters } from "node:util";
9
+ import { cksum, openShellManager, openTerminal, PaneLiveInputQueue, validDimension } from "./mobile-tui-stream.mjs";
11
10
 
12
- const invoke = promisify(execFile);
13
11
  const herdr = process.env.HERDR_BIN_PATH || join(homedir(), ".local/bin/herdr");
14
12
  const name = process.env.HERDGATE_HOST_NAME || "home-tui-mobile";
15
13
  const digest = (text) => createHash("sha256").update(text).digest("hex");
@@ -51,7 +49,17 @@ const pollMs = Math.max(250, Number.parseInt(process.env.HERDGATE_TUI_POLL_MS ??
51
49
  const startedAt = Date.now();
52
50
  let cache;
53
51
  let cacheUntil = 0;
54
- const run = async (args) => (await invoke(herdr, args, { timeout: 4_000, maxBuffer: 512 * 1024, windowsHide: true, shell: false })).stdout;
52
+ // One persistent /bin/sh speaks for every Herdr call: each request is framed by a unique
53
+ // marker, the shell is probed (`true`) before it counts as alive, and one channel failure
54
+ // kills the whole generation — the written request is never retried, later requests fall
55
+ // back to one exec per command, and only an explicit reinit() opens the next generation.
56
+ const shells = openShellManager();
57
+ const shellQuote = (word) => `'${String(word).replace(/'/g, "'\\''")}'`;
58
+ const run = async (args) => {
59
+ const { stdout, code } = await shells.execute([herdr, ...args].map(shellQuote).join(" "));
60
+ if (code !== 0) throw Object.assign(new Error(`herdr ${args[0]} exited ${code}`), { definitive: true });
61
+ return stdout.toString("utf8");
62
+ };
55
63
 
56
64
  async function panes() {
57
65
  if (cache && Date.now() < cacheUntil) return cache;
@@ -60,9 +68,9 @@ async function panes() {
60
68
  cache = parsed.result.panes.filter((p) => typeof p?.pane_id === "string" && /^[a-zA-Z0-9_:.-]{1,128}$/.test(p.pane_id) && !p.pane_id.startsWith("-"))
61
69
  .slice(0, 180).map((p) => {
62
70
  let title = clip(p.terminal_title_stripped || p.terminal_title || p.pane_id, 120);
63
- // Herdr's per-pane agent state feeds the core's own status and foreground fields.
64
- const status = p.agent_status === "working" ? "working" : null;
65
- const foreground = typeof p.foreground_cwd === "string" && p.foreground_cwd ? { pid: null, name: null, argv: null, cwd: clip(p.foreground_cwd, 512) } : null;
71
+ // Herdr's per-pane agent state feeds the core's own status word (a 7501 record
72
+ // shape: an object with a state, never a bare string).
73
+ const status = p.agent_status === "working" ? { state: "working" } : null;
66
74
  const ws = typeof p.workspace_id === "string" && /^[a-zA-Z0-9_:.-]{1,128}$/.test(p.workspace_id) ? p.workspace_id : null;
67
75
  const tab = typeof p.tab_id === "string" && /^[a-zA-Z0-9_:.-]{1,128}$/.test(p.tab_id) ? p.tab_id : null;
68
76
  // The desktop app seats terminals by these labels; ids stay stable per workspace/tab.
@@ -70,7 +78,7 @@ async function panes() {
70
78
  return { id: p.pane_id, workspace: ws, tab, target: typeof p.terminal_id === "string" && /^term_[a-zA-Z0-9]{1,96}$/.test(p.terminal_id) ? p.terminal_id : null, terminal: {
71
79
  address: "t" + digest(p.pane_id).slice(0, 12), title, name: null, argv: [], cwd: clip(p.cwd, 512),
72
80
  state: "live", created_ms: 0, screen: "inexact", cols: 80, rows: 24,
73
- labels, turn: 0, status, foreground,
81
+ labels, turn: 0, status,
74
82
  } };
75
83
  });
76
84
  cacheUntil = Date.now() + 1_000;
@@ -139,13 +147,20 @@ function layoutTree(items, nodeId) {
139
147
 
140
148
  const blockOf = (it) => ({ id: "p" + digest("pane:" + it.pane.id).slice(0, 30), type: "block", content: { terminal: it.pane.terminal.address } });
141
149
 
142
- /** Terminal records as the viewers list them: panes with their on-screen geometry. */
150
+ /** Terminal records as the viewers list them: panes with their on-screen geometry.
151
+ * Agent panes also carry their program (π) in name/argv — the app's programs table
152
+ * matches argv, so its agents mod and icons light up for them. */
143
153
  async function terminalRecords() {
144
154
  const rects = await paneRects();
145
- return (await panes()).map(({ id, terminal }) => {
155
+ const out = [];
156
+ for (const { id, terminal } of await panes()) {
146
157
  const rect = rects.get(id);
147
- return rect ? { ...terminal, cols: Math.max(2, Math.min(1000, rect.width)), rows: Math.max(2, Math.min(1000, rect.height)) } : terminal;
148
- });
158
+ let record = rect ? { ...terminal, cols: Math.max(2, Math.min(1000, rect.width)), rows: Math.max(2, Math.min(1000, rect.height)) } : { ...terminal };
159
+ const info = await agentInfo(id);
160
+ if (info.agent) record = { ...record, name: info.agent, argv: [info.agent] };
161
+ out.push(record);
162
+ }
163
+ return out;
149
164
  }
150
165
 
151
166
  /** Seating changes (workspace/tab/pane set) are what change the layout doc. */
@@ -155,7 +170,7 @@ function docFingerprint(records) {
155
170
 
156
171
  /** What a viewer must hear about between polls: titles, folders, seating, life. */
157
172
  function seenFingerprint(records) {
158
- return new Map(records.map((t) => [t.address, [t.title, t.cwd, t.labels["herdr.space"] ?? null, t.labels["herdr.tab"] ?? null, t.status ?? null, t.foreground?.cwd ?? null]]));
173
+ return new Map(records.map((t) => [t.address, [t.title, t.cwd, t.labels["herdr.space"] ?? null, t.labels["herdr.tab"] ?? null, t.status?.state ?? null]]));
159
174
  }
160
175
 
161
176
  function clip(x, n) { return typeof x === "string" ? x.slice(0, n) : ""; }
@@ -257,18 +272,26 @@ function wrapFor(width, text) {
257
272
  return out.join("\r\n");
258
273
  }
259
274
 
260
- const sessionCache = new Map(); // pane_id → { session, until } — pane get is a per-read cost otherwise
261
- async function agentSession(hit) {
262
- const cached = sessionCache.get(hit.id);
263
- if (cached && Date.now() < cached.until) return cached.session;
275
+ const sessionCache = new Map(); // pane_id → { session, agent, until } — pane get is a per-read cost otherwise
276
+ async function agentInfo(paneId) {
277
+ const cached = sessionCache.get(paneId);
278
+ if (cached && Date.now() < cached.until) return cached;
264
279
  let session = null;
280
+ let agent = null;
265
281
  try {
266
- const parsed = JSON.parse(await run(["pane", "get", hit.id]));
267
- const value = parsed?.result?.pane?.agent_session?.value;
282
+ const parsed = JSON.parse(await run(["pane", "get", paneId]));
283
+ const pane = parsed?.result?.pane;
284
+ const value = pane?.agent_session?.value;
268
285
  if (typeof value === "string" && value.endsWith(".jsonl") && value.startsWith(homedir() + "/")) session = value;
286
+ if (typeof pane?.agent === "string" && pane.agent) agent = clip(pane.agent, 32);
269
287
  } catch { /* a pane without an agent session simply has no transcript */ }
270
- sessionCache.set(hit.id, { session, until: Date.now() + 30_000 });
271
- return session;
288
+ const info = { session, agent, until: Date.now() + 30_000 };
289
+ sessionCache.set(paneId, info);
290
+ return info;
291
+ }
292
+
293
+ async function agentSession(hit) {
294
+ return (await agentInfo(hit.id)).session;
272
295
  }
273
296
 
274
297
  /** The pane's recent chat as structured blocks — the history that lives inside the agent
@@ -311,11 +334,61 @@ async function transcriptBlocks(hit) {
311
334
  }
312
335
  }
313
336
 
314
- /** Transcript blocks as the plain lines a text reader (the phone's history view) shows. */
315
- async function transcriptText(hit) {
337
+ /** Transcript blocks as the plain lines a text reader (the phone's history view) shows.
338
+ * With `joinScreen`, the current screen follows: the in-flight turn is not in the
339
+ * session file yet (π writes it when the turn ends), so the visible screen is the
340
+ * only bridge — history then flows straight into what the viewer renders below. */
341
+ async function transcriptText(hit, { joinScreen = false } = {}) {
316
342
  const blocks = await transcriptBlocks(hit);
317
- if (!blocks) return null;
318
- return blocks.map((b) => (b.role === "user" ? "❯ " : "● ") + b.text).join("\n");
343
+ const parts = [];
344
+ if (blocks) parts.push(blocks.map((b) => (b.role === "user" ? "❯ " : "● ") + b.text).join("\n"));
345
+ if (joinScreen) {
346
+ try {
347
+ // A text view wants words, not terminal paint: drop OSC replies and every CSI
348
+ // (colors included) — the seed path keeps its paint, this one reads clean.
349
+ const screen = (await run(["pane", "read", hit.id, "--source", "visible", "--format", "text", "--raw"]))
350
+ .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "").replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "").replace(/\s+$/, "");
351
+ if (screen) {
352
+ if (parts.length) parts.push("──── trở lại hiện tại ────");
353
+ parts.push(screen);
354
+ }
355
+ } catch { /* best-effort seam */ }
356
+ }
357
+ return parts.length ? parts.join("\n") : null;
358
+ }
359
+
360
+ // Input from the phone rides a bounded, coalescing FIFO with in-order acks: adjacent
361
+ // keystroke batches for one pane leave as a single send-keys, every input is acked in
362
+ // submission order, and any ambiguous delivery flips the queue to needsResync — the
363
+ // viewer must re-read the pane, and queued input is never replayed at it.
364
+ let inputQueue = null;
365
+ let inputStamp = 0; // advanced once a write has landed: snapshots older than it are stale
366
+ async function applyInput(event) {
367
+ if (event.kind === "text") await run(["pane", "run", event.paneId, event.text]);
368
+ else await run(["pane", "send-keys", event.paneId, ...event.keys]);
369
+ inputStamp++;
370
+ }
371
+ async function queuedInput(paneId, kind, payload) {
372
+ if (!inputQueue) { // a queue-less path (never in this adapter today) still writes in order
373
+ await applyInput({ paneId, kind, ...payload });
374
+ return null;
375
+ }
376
+ try {
377
+ return await inputQueue.enqueue(paneId, kind, payload);
378
+ } catch (err) {
379
+ if (err?.kind === "needs_resync") throw new RpcError(-32000, "Pane input needs a resync; re-read the pane, never replay", "needs_resync");
380
+ throw err;
381
+ }
382
+ }
383
+ // In-flight snapshot sharing: concurrent readers of one pane share a single read, and a
384
+ // read that began before a write is never served to a caller after it (the `fresh` rule).
385
+ const stitchedInFlight = new Map(); // pane_id → { after, promise }
386
+ async function stitchedRead(hit) {
387
+ const current = stitchedInFlight.get(hit.id);
388
+ if (current && current.after === inputStamp) return current.promise;
389
+ const promise = transcriptText(hit, { joinScreen: true });
390
+ stitchedInFlight.set(hit.id, { after: inputStamp, promise });
391
+ try { return await promise; } finally { if (stitchedInFlight.get(hit.id)?.promise === promise) stitchedInFlight.delete(hit.id); }
319
392
  }
320
393
 
321
394
  /** The terminal addresses a doc tree shows. */
@@ -425,7 +498,7 @@ async function findPane(terminal) {
425
498
  async function call(method, p, framed, attach, startEvents) {
426
499
  switch (method) {
427
500
  case "hello":
428
- return { core, version, generation: 1, framed, features: framed ? ["framed", "attach", "status", ...(interactive ? ["resize_notifications"] : [])] : ["status"], methods: [...methods, ...(framed ? ["terminal.attach"] : []), ...(interactive ? inputMethods : [])], keeps_running_after_logout: true };
501
+ return { core, version, generation: 1, framed, features: framed ? ["framed", "attach", "status", "checksum_reads", ...(interactive ? ["resize_notifications", "input_ack"] : [])] : ["status", "checksum_reads"], methods: [...methods, ...(framed ? ["terminal.attach"] : []), ...(interactive ? inputMethods : [])], keeps_running_after_logout: true };
429
502
  case "server.status": return status();
430
503
  case "terminal.list": {
431
504
  const filters = p.labels ?? {};
@@ -450,14 +523,18 @@ async function call(method, p, framed, attach, startEvents) {
450
523
  const { turn } = terminal;
451
524
  if (method === "terminal.send") {
452
525
  if (!inputText(p.text) || p.wait === true || p.if != null) throw invalid();
453
- // Herdr's pane run takes positional text and submits it with Enter in one API request.
454
- await run(["pane", "run", id, p.text]);
455
- return { turn, status: null, started: null, wait: null };
526
+ const ack = await queuedInput(id, "text", { text: p.text });
527
+ return { turn, status: null, started: null, wait: null, ...(ack === null ? {} : { ack }) };
528
+ }
529
+ if (method === "terminal.interrupt") {
530
+ // An interrupt must never sit behind typing already in the queue.
531
+ await run(["pane", "send-keys", id, "ctrl+c"]);
532
+ return { key: "ctrl+c", outcome: "unknown" };
456
533
  }
457
- const keys = method === "terminal.interrupt" ? ["ctrl+c"] : p.keys;
534
+ const keys = p.keys;
458
535
  if (!Array.isArray(keys) || !keys.length || keys.length > 32 || keys.some((key) => typeof key !== "string" || !/^(?:(?:ctrl|alt|shift|super)\+)*[a-z0-9][a-z0-9_-]{0,15}$/i.test(key) || key.length > 32)) throw invalid();
459
- await run(["pane", "send-keys", id, ...keys]);
460
- return method === "terminal.interrupt" ? { key: keys[0], outcome: "unknown" } : { turn, status: null };
536
+ const ack = await queuedInput(id, "keys", { keys });
537
+ return { turn, status: null, ...(ack === null ? {} : { ack }) };
461
538
  }
462
539
  case "terminal.run": {
463
540
  if (!interactive) throw new RpcError(-32601, "This pairing is read-only", "forbidden");
@@ -504,14 +581,21 @@ async function call(method, p, framed, attach, startEvents) {
504
581
  }
505
582
  const lines = p.lines ?? 0;
506
583
  if (!Number.isSafeInteger(lines) || lines < 0) throw invalid();
584
+ // A checksum-stamped read: the viewer that already holds this text sends its stamp
585
+ // back and gets `unchanged` with no body when nothing moved (readChangedCommand
586
+ // semantics — POSIX cksum, no stat). Viewers without a stamp get the full body.
587
+ const prior = typeof p.checksum === "string" && /^[0-9]{1,10} [0-9]{1,20}$/.test(p.checksum) ? p.checksum : null;
507
588
  // An agent pane keeps its chat inside itself: serve the transcript as "stitched"
508
- // history (the core's term for a full-screen app read by scrolling it).
509
- const transcript = await transcriptText(hit);
589
+ // history (the core's term for a full-screen app read by scrolling it), joined to
590
+ // the live screen so the seam never shows a gap mid-turn.
591
+ const transcript = await stitchedRead(hit);
510
592
  if (transcript) {
511
593
  const all = transcript.split("\n");
512
594
  const take = lines > 0 ? all.slice(-Math.min(2000, lines)) : all.slice(-24);
513
- const text = take.join("\n");
514
- return { text: text.slice(0, 60 * 1024), complete: transcript.length <= 60 * 1024, how: "stitched", why: null };
595
+ const text = take.join("\n").slice(0, 60 * 1024);
596
+ const stamp = cksum(Buffer.from(text, "utf8"));
597
+ if (prior !== null && prior === stamp) return { unchanged: true, checksum: stamp, complete: transcript.length <= 60 * 1024, how: "stitched", why: null };
598
+ return { text, checksum: stamp, complete: transcript.length <= 60 * 1024, how: "stitched", why: null };
515
599
  }
516
600
  // A shell pane: `recent` carries the history viewers scroll (the phone reads it);
517
601
  // a pane with none — fresh — falls back to the on-screen text so it is not blank.
@@ -594,6 +678,7 @@ async function serve() {
594
678
  let framed = false;
595
679
  let buffer = Buffer.alloc(0);
596
680
  const streams = new Map();
681
+ inputQueue = interactive ? new PaneLiveInputQueue(applyInput) : null;
597
682
  let nextChannel = 1;
598
683
  let timer;
599
684
  let polling = false;
@@ -640,9 +725,15 @@ async function serve() {
640
725
  out.push("");
641
726
  }
642
727
  out.push(dim + "──── trở lại hiện tại ────" + reset);
728
+ // The seam: the in-flight turn lives only on the screen, so end the seed with
729
+ // the screen itself — the viewer's first paint then continues it, not jumps.
730
+ try {
731
+ const screen = (await run(["pane", "read", hit.id, "--source", "visible", "--format", "text", "--raw"])).replace(/\s+$/, "");
732
+ if (screen) out.push(screen);
733
+ } catch { /* best-effort seam */ }
643
734
  parts.push(Buffer.from(out.join("\r\n") + "\r\n"));
644
735
  }
645
- if (Number.isSafeInteger(p.history) && p.history > 0) {
736
+ if (!blocks && Number.isSafeInteger(p.history) && p.history > 0) {
646
737
  try {
647
738
  const back = await run(["pane", "read", hit.id, "--source", "recent", "--lines", String(Math.min(2000, p.history)), "--format", "ansi", "--raw"]);
648
739
  const lines = back.split(/\r?\n/);
@@ -767,10 +858,9 @@ async function serve() {
767
858
  const prev = s.seen.get(t.address);
768
859
  if (prev === undefined) out.push({ method: "event", params: { seq: ++s.seq, type: "created", terminal: t.address, data: t } });
769
860
  else if (prev.join("\0") !== now.get(t.address).join("\0")) {
770
- const [title0, cwd0, space0, tabb0, status0, fg0] = prev;
771
- const [title1, cwd1, space1, tabb1, status1, fg1] = now.get(t.address);
772
- if (status0 !== status1) out.push({ method: "event", params: { seq: ++s.seq, type: "status", terminal: t.address, data: { status: status1, records: {}, reported: status1 !== null } } });
773
- if (fg0 !== fg1) out.push({ method: "event", params: { seq: ++s.seq, type: "foreground", terminal: t.address, data: t.foreground } });
861
+ const [title0, cwd0, space0, tabb0, status0] = prev;
862
+ const [title1, cwd1, space1, tabb1, status1] = now.get(t.address);
863
+ if (status0 !== status1) out.push({ method: "event", params: { seq: ++s.seq, type: "status", terminal: t.address, data: { status: t.status, records: {}, reported: t.status !== null } } });
774
864
  out.push({ method: "event", params: { seq: ++s.seq, type: "labels", terminal: t.address, data: { record: t } } });
775
865
  }
776
866
  }
@@ -866,20 +956,26 @@ async function serve() {
866
956
  clearTimeout(timer);
867
957
  clearTimeout(eventTimer);
868
958
  for (const channel of streams.keys()) release(channel);
959
+ inputQueue?.resync("connection closed");
960
+ shells.close();
869
961
  }
870
962
  }
871
963
 
872
964
  const command = args.join(" ");
873
965
  try {
874
966
  if (command === "--version" || command === "-V") console.log(`hc ${version} (Herdgate ${mode} TUI adapter)`);
875
- else if (command === "server status" || command === "server status --json") console.log(JSON.stringify(await status()));
967
+ else if (command === "server status" || command === "server status --json") {
968
+ const out = JSON.stringify(await status());
969
+ shells.close();
970
+ console.log(out);
971
+ }
876
972
  else if (command === "connect" || command === "connect --json") {
877
973
  await serve();
878
974
  } else {
879
975
  console.error("herdgate: TUI adapter supports only connect, --version, and server status");
880
976
  process.exitCode = 111;
881
977
  }
882
- } catch {
883
- console.error("herdgate: could not query the local Herdr TUI");
978
+ } catch (e) {
979
+ console.error(`herdgate: could not query the local Herdr TUI: ${e?.message ?? e}`);
884
980
  process.exitCode = 111;
885
981
  }
@@ -1,7 +1,8 @@
1
1
  // Native Herdr terminal controller. Never interprets a shell command. --takeover makes the
2
2
  // latest viewer own the stream: Herdr allows one controller per terminal, and this way a
3
3
  // reconnect or a second viewer (phone, desktop) replaces the old one instead of failing.
4
- import { spawn } from "node:child_process";
4
+ import { execFile, spawn } from "node:child_process";
5
+ import { randomBytes } from "node:crypto";
5
6
 
6
7
  const maxLine = 1024 * 1024;
7
8
 
@@ -61,3 +62,259 @@ async function* readFrames(stdout) {
61
62
  export function validDimension(value) {
62
63
  return Number.isInteger(value) && value > 0 && value <= 65535;
63
64
  }
65
+
66
+ // POSIX cksum (CRC-32 0x04C11DB7 + byte length, the same `cksum` coreutils prints):
67
+ // a content stamp that needs no stat and survives any transport. `readChangedCommand`
68
+ // stamps file reads with exactly this, so the phone can ask "same as before?" in one line.
69
+ const cksumTable = new Uint32Array(256).map((_, n) => {
70
+ let c = n << 24;
71
+ for (let k = 0; k < 8; k++) c = ((c << 1) ^ ((c & 0x80000000) !== 0 ? 0x04c11db7 : 0)) >>> 0;
72
+ return c >>> 0;
73
+ });
74
+ export function cksum(bytes) {
75
+ let crc = 0;
76
+ for (let i = 0; i < bytes.length; i++) crc = ((crc << 8) ^ cksumTable[((crc >>> 24) ^ bytes[i]) & 0xff]) >>> 0;
77
+ let len = bytes.length;
78
+ while (len > 0) { // the length rides the same CRC, low byte first, no leading zeros
79
+ crc = ((crc << 8) ^ cksumTable[((crc >>> 24) ^ (len & 0xff)) & 0xff]) >>> 0;
80
+ len = Math.floor(len / 256);
81
+ }
82
+ return `${(crc ^ 0xffffffff) >>> 0} ${bytes.length}`;
83
+ }
84
+
85
+ const newMarker = () => "HC_" + randomBytes(16).toString("hex");
86
+
87
+ /** One persistent `/bin/sh` with marker framing: every request is `<command> </dev/null`
88
+ * followed by a printf that emits `\n<unique marker> <exit code>\n`. stdin is detached
89
+ * per command so a hungry command cannot swallow the next request; a reply is decoded
90
+ * only once its whole delimiter is present, so chunked output never corrupts multibyte
91
+ * text. The shell is probed with `true` before it counts as alive; any channel failure
92
+ * (write error, early exit, timeout, over-limit) kills the whole generation — the
93
+ * written request is never retried, later requests fall back to one exec per command,
94
+ * and only an explicit reinit() may open the next generation. */
95
+ export function openShellManager({
96
+ exec,
97
+ shell = process.env.HERDR_SHELL || "/bin/sh",
98
+ probeCommand = "true",
99
+ timeoutMs = 4_000,
100
+ limitBytes = 8 * 1024 * 1024,
101
+ } = {}) {
102
+ const fallbackRun = exec || ((command) => new Promise((resolve) => {
103
+ execFile(shell, ["-c", command], { timeout: timeoutMs, maxBuffer: 512 * 1024, windowsHide: true }, (err, stdout) => {
104
+ resolve({ stdout: Buffer.from(stdout ?? ""), code: err && typeof err.code === "number" ? err.code : err ? 1 : 0 });
105
+ });
106
+ }));
107
+ let generation = 1;
108
+ let state = "idle"; // idle | opening | live | dead
109
+ let fails = 0;
110
+ let child = null;
111
+ let buffer = Buffer.alloc(0);
112
+ let waiting = []; // framed requests in submission order; head is decoded first
113
+ const stats = { shells: 0, shellRequests: 0, fallbackRequests: 0 };
114
+
115
+ const failChannel = (reason) => {
116
+ if (state === "dead") return;
117
+ const written = [];
118
+ const unwritten = [];
119
+ for (const req of waiting) (req.written ? written : unwritten).push(req);
120
+ waiting = [];
121
+ state = "dead";
122
+ fails++;
123
+ buffer = Buffer.alloc(0);
124
+ if (child) { try { child.stdin.end(); } catch { /* already gone */ } child.kill(); child = null; }
125
+ for (const req of written) {
126
+ clearTimeout(req.timer);
127
+ req.reject(Object.assign(new Error(`persistent shell failed: ${reason}`), { kind: "shell_failed", noRetry: true }));
128
+ }
129
+ // These were never written, so running them through the fallback is not a retry.
130
+ for (const req of unwritten) fallbackRun(req.command).then(req.resolve, req.reject);
131
+ };
132
+
133
+ const open = () => {
134
+ stats.shells++;
135
+ state = "opening";
136
+ const kid = spawn(shell, [], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
137
+ child = kid;
138
+ kid.stdout.on("data", (chunk) => {
139
+ buffer = Buffer.concat([buffer, chunk]);
140
+ if (buffer.length > limitBytes) return failChannel("frame over limit");
141
+ for (;;) {
142
+ const head = waiting[0];
143
+ if (!head || !head.written) break;
144
+ const start = buffer.indexOf(head.delimiter);
145
+ if (start < 0) break;
146
+ const end = buffer.indexOf(10, start + head.delimiter.length);
147
+ if (end < 0) break;
148
+ const code = Number.parseInt(buffer.subarray(start + head.delimiter.length, end).toString("ascii"), 10);
149
+ if (!Number.isInteger(code) || code < 0) return failChannel("corrupt frame");
150
+ const stdout = buffer.subarray(0, start);
151
+ buffer = buffer.subarray(end + 1);
152
+ waiting.shift();
153
+ clearTimeout(head.timer);
154
+ if (head.probe) {
155
+ if (code !== 0) return failChannel("probe failed");
156
+ state = "live";
157
+ }
158
+ head.resolve({ stdout, code });
159
+ pump();
160
+ }
161
+ });
162
+ kid.stdin.on("error", () => { if (child === kid) failChannel("stdin write failed"); });
163
+ kid.on("error", () => { if (child === kid) failChannel("shell did not start"); });
164
+ kid.on("exit", () => { if (child === kid && state !== "dead") failChannel("shell exited"); });
165
+ const probe = { probe: true, command: probeCommand, marker: newMarker(), written: false };
166
+ probe.delimiter = Buffer.from(`\n${probe.marker} `);
167
+ probe.promise = new Promise((resolve, reject) => { probe.resolve = resolve; probe.reject = reject; });
168
+ waiting.push(probe);
169
+ probe.promise.catch(() => {}); // the probe's own failure is reported by failChannel
170
+ };
171
+
172
+ function pump() {
173
+ if (state === "dead" || !child) return;
174
+ const head = waiting[0];
175
+ if (!head || head.written) return;
176
+ if (!head.probe && state !== "live") return; // nothing runs before the probe answers
177
+ head.written = true;
178
+ stats.shellRequests++;
179
+ head.timer = setTimeout(() => failChannel("request timed out"), timeoutMs);
180
+ head.timer.unref?.();
181
+ // The redirect wraps the whole command (braces), so pipelines keep their stdin while
182
+ // no command can ever read the marker stream meant for the next request.
183
+ const frame = `{ ${head.command} ; } </dev/null\nprintf '\\n%s %s\\n' '${head.marker}' "$?"\n`;
184
+ child.stdin.write(frame, (err) => { if (err) failChannel("stdin write failed"); });
185
+ }
186
+
187
+ return {
188
+ execute(command) {
189
+ if (state === "dead") { stats.fallbackRequests++; return fallbackRun(command); }
190
+ if (state === "idle") open();
191
+ const req = { command, marker: newMarker(), written: false };
192
+ req.delimiter = Buffer.from(`\n${req.marker} `);
193
+ const promise = new Promise((resolve, reject) => { req.resolve = resolve; req.reject = reject; });
194
+ req.promise = promise;
195
+ waiting.push(req);
196
+ pump();
197
+ return promise;
198
+ },
199
+ // The only way a failed generation comes back: an explicit new one.
200
+ reinit() {
201
+ failChannel("reinit");
202
+ generation++;
203
+ fails = 0;
204
+ state = "idle";
205
+ },
206
+ // End of the line for this manager: close the shell without failing anyone.
207
+ close() {
208
+ if (!child) { state = "dead"; return; }
209
+ const kid = child;
210
+ child = null;
211
+ state = "dead";
212
+ try { kid.stdin.end(); } catch { /* already gone */ }
213
+ kid.kill();
214
+ },
215
+ get generation() { return generation; },
216
+ get state() { return state; },
217
+ get fails() { return fails; },
218
+ stats,
219
+ };
220
+ }
221
+
222
+ const resyncError = (reason = "pane input needs resync; re-read, never replay") =>
223
+ Object.assign(new Error(reason), { kind: "needs_resync" });
224
+
225
+ /** Keystrokes from the phone ride a bounded FIFO (PaneLiveInputQueue semantics): adjacent
226
+ * keystroke batches for the same pane coalesce Nagle-style, every input is acknowledged
227
+ * in submission order before the next batch is written, and any ambiguous failure —
228
+ * delivery unknown, or the queue overflows — flips the whole queue to needsResync and
229
+ * drops it: the client must resync from a fresh read, and old input is never replayed. */
230
+ export class PaneLiveInputQueue {
231
+ constructor(apply, { limit = 256 } = {}) {
232
+ if (typeof apply !== "function") throw new Error("PaneLiveInputQueue needs an apply function");
233
+ this.apply = apply;
234
+ this.limit = limit;
235
+ this.state = "live"; // live | needsResync
236
+ this.enqueuedCount = 0;
237
+ this.acknowledgedCount = 0;
238
+ this.droppedCount = 0;
239
+ this.pending = [];
240
+ this.pumping = false;
241
+ }
242
+
243
+ enqueue(paneId, kind, payload = {}) {
244
+ if (this.state !== "live") return Promise.reject(resyncError());
245
+ if (this.pending.length >= this.limit) {
246
+ this.resync("input queue overflow");
247
+ return Promise.reject(resyncError("input queue overflow"));
248
+ }
249
+ const tail = this.pending[this.pending.length - 1];
250
+ if (kind === "keys" && tail && !tail.sent && tail.paneId === paneId && tail.kind === "keys" && Array.isArray(payload.keys)) {
251
+ tail.keys = tail.keys.concat(payload.keys); // one send-keys for a burst of keystrokes
252
+ return this.claim(tail);
253
+ }
254
+ const event = { paneId, kind, text: payload.text, keys: payload.keys ? [...payload.keys] : undefined, sent: false, waiters: [] };
255
+ this.pending.push(event);
256
+ const promise = this.claim(event);
257
+ queueMicrotask(() => this.pump()); // a beat to gather a burst before the write starts
258
+ return promise;
259
+ }
260
+
261
+ /** Drop not-yet-sent input for a pane (the viewer switched away from it). */
262
+ abandon(paneId) {
263
+ if (this.state !== "live") return;
264
+ this.pending = this.pending.filter((event) => {
265
+ if (event.paneId !== paneId || event.sent) return true;
266
+ this.droppedCount += event.waiters.length;
267
+ for (const waiter of event.waiters) waiter.reject(Object.assign(new Error("pane input abandoned"), { kind: "abandoned" }));
268
+ return false;
269
+ });
270
+ }
271
+
272
+ resync(reason = "pane input needs resync") {
273
+ if (this.state !== "live") return;
274
+ this.state = "needsResync";
275
+ const events = this.pending;
276
+ this.pending = [];
277
+ for (const event of events) {
278
+ this.droppedCount += event.waiters.length;
279
+ for (const waiter of event.waiters) waiter.reject(resyncError(reason));
280
+ }
281
+ }
282
+
283
+ claim(event) {
284
+ const seq = ++this.enqueuedCount;
285
+ return new Promise((resolve, reject) => event.waiters.push({ seq, resolve, reject }));
286
+ }
287
+
288
+ async pump() {
289
+ if (this.pumping || this.state !== "live") return;
290
+ this.pumping = true;
291
+ try {
292
+ while (this.pending.length && this.state === "live") {
293
+ const event = this.pending[0];
294
+ event.sent = true;
295
+ let failure = null;
296
+ try {
297
+ await this.apply({ paneId: event.paneId, kind: event.kind, text: event.text, keys: event.keys });
298
+ } catch (err) {
299
+ // The host answered no: a refusal is a refusal — this input is done, the rest drain on.
300
+ // Anything ambiguous (delivery unknown) leaves the channel untrustworthy: resync.
301
+ if (err && err.definitive === true) failure = err;
302
+ else return this.resync(err?.message ?? "pane input delivery failed");
303
+ }
304
+ this.pending.shift();
305
+ this.acknowledge(event, failure);
306
+ }
307
+ } finally {
308
+ this.pumping = false;
309
+ }
310
+ }
311
+
312
+ /** Acks come back strictly in submission order, one count per accepted input. */
313
+ acknowledge(event, failure) {
314
+ for (const waiter of event.waiters) {
315
+ this.acknowledgedCount++;
316
+ if (failure) waiter.reject(failure);
317
+ else waiter.resolve(this.acknowledgedCount);
318
+ }
319
+ }
320
+ }