@howaboua/pi-shepherdr 0.2.11 → 0.2.12

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/src/controller.ts CHANGED
@@ -3,7 +3,7 @@ import type {
3
3
  ExtensionContext,
4
4
  } from "@earendil-works/pi-coding-agent";
5
5
  import type { AgentBoard } from "./board/host.js";
6
- import { openBoardSettings } from "./board/settings.js";
6
+ import { controlPanelStatus, openControlPanel } from "./control-panel.js";
7
7
  import { sendPolicyMessage } from "./delivery.js";
8
8
  import type { AgentFleet } from "./fleet.js";
9
9
  import { loadAgentProfiles } from "./profiles.js";
@@ -21,106 +21,98 @@ export function registerAgentController(
21
21
  board: AgentBoard,
22
22
  ): void {
23
23
  let orchestrationEnabled = false;
24
+ const panels = new Set<Promise<void>>();
25
+ let sessionLifetime = new AbortController();
26
+ const resetLifetime = () => {
27
+ sessionLifetime.abort();
28
+ sessionLifetime = new AbortController();
29
+ };
30
+ const setOrchestration = async (
31
+ ctx: ExtensionContext,
32
+ enabled: boolean,
33
+ signal: AbortSignal,
34
+ ) => {
35
+ const sessionId = ctx.sessionManager.getSessionId();
36
+ const content = enabled ? await orchestrationMessage() : NORMAL_MESSAGE;
37
+ signal.throwIfAborted();
38
+ if (ctx.sessionManager.getSessionId() !== sessionId)
39
+ throw new Error("Session changed; retry /herdr");
40
+ orchestrationEnabled = enabled;
41
+ sendPolicyMessage(
42
+ pi,
43
+ {
44
+ customType: ORCHESTRATION_STATE_TYPE,
45
+ content,
46
+ details: { enabled },
47
+ display: true,
48
+ },
49
+ { triggerTurn: false },
50
+ );
51
+ };
52
+ const reconnect = async (
53
+ ctx: ExtensionContext,
54
+ machine: string | undefined,
55
+ signal: AbortSignal,
56
+ ) => {
57
+ if (!fleet.isActive()) {
58
+ await activateController(fleet, ctx);
59
+ signal.throwIfAborted();
60
+ if (!fleet.isActive())
61
+ throw new Error("Fleet inactive. Pi must run inside Herdr.");
62
+ }
63
+ await fleet.reload();
64
+ signal.throwIfAborted();
65
+ return fleet.connect(machine);
66
+ };
24
67
  pi.registerCommand("herdr", {
25
- description: "Toggle orchestration, message board, or reconnect machines",
26
- getArgumentCompletions: (prefix) =>
27
- [
28
- "connect",
29
- "board",
30
- "board on",
31
- "board off",
32
- "board inherit",
33
- "board on folder",
34
- "board off folder",
35
- "board inherit folder",
36
- "board on global",
37
- "board off global",
38
- ]
39
- .filter((action) => action.startsWith(prefix.trim().toLowerCase()))
40
- .map((value) => ({ label: value, value })),
68
+ description: "Shepherdr settings, status and SSH setup",
41
69
  handler: async (args, ctx) => {
42
- const [rawAction = "", ...rest] = args.trim().split(/\s+/);
43
- const action = rawAction.toLowerCase();
44
- if (!action) {
45
- orchestrationEnabled = restoreOrchestrationState(ctx);
46
- orchestrationEnabled = !orchestrationEnabled;
47
- sendPolicyMessage(
48
- pi,
49
- {
50
- customType: ORCHESTRATION_STATE_TYPE,
51
- content: orchestrationEnabled
52
- ? await orchestrationMessage()
53
- : NORMAL_MESSAGE,
54
- details: { enabled: orchestrationEnabled },
55
- display: true,
56
- },
57
- { triggerTurn: false },
58
- );
59
- ctx.ui.notify(
60
- orchestrationEnabled
61
- ? "Agent orchestration enabled"
62
- : "Normal mode enabled",
63
- "info",
64
- );
70
+ const commandSignal = sessionLifetime.signal;
71
+ const commandSessionId = ctx.sessionManager.getSessionId();
72
+ const current = () =>
73
+ !commandSignal.aborted &&
74
+ ctx.sessionManager.getSessionId() === commandSessionId;
75
+ if (args.trim()) {
76
+ ctx.ui.notify("Open /herdr, then choose a tab.", "warning");
65
77
  return;
66
78
  }
67
- if (action === "connect") {
68
- if (!fleet.isActive()) {
69
- await activateController(fleet, ctx);
70
- if (!fleet.isActive()) return;
71
- }
72
- try {
73
- await fleet.reload();
74
- ctx.ui.notify(fleet.connect(rest[0]), "info");
75
- } catch (error) {
76
- ctx.ui.notify(
77
- error instanceof Error ? error.message : String(error),
78
- "error",
79
- );
80
- }
81
- return;
82
- }
83
- if (action === "board") {
84
- try {
85
- if (rest.length === 0) {
86
- if (ctx.mode === "tui") await openBoardSettings(ctx, board);
87
- else ctx.ui.notify(board.status(ctx), "info");
88
- } else if (
89
- rest.length <= 2 &&
90
- (rest[0] === "on" || rest[0] === "off" || rest[0] === "inherit") &&
91
- (rest[1] === undefined ||
92
- rest[1] === "session" ||
93
- rest[1] === "folder" ||
94
- rest[1] === "global") &&
95
- !(rest[0] === "inherit" && rest[1] === "global")
96
- ) {
97
- await board.setSetting(
98
- ctx,
99
- rest[1] ?? "session",
100
- rest[0] === "inherit" ? undefined : rest[0] === "on",
101
- );
102
- ctx.ui.notify(board.status(ctx), "info");
103
- } else
104
- ctx.ui.notify(
105
- "Usage: /herdr board [on|off|inherit [session|folder] | on|off global]",
106
- "warning",
107
- );
108
- } catch (error) {
109
- ctx.ui.notify(String(error), "error");
110
- }
111
- return;
79
+ const options = {
80
+ fleet,
81
+ board,
82
+ orchestration: () => orchestrationEnabled,
83
+ setOrchestration: (enabled: boolean, signal: AbortSignal) =>
84
+ setOrchestration(ctx, enabled, signal),
85
+ reconnect: (machine: string | undefined, signal: AbortSignal) =>
86
+ reconnect(ctx, machine, signal),
87
+ signal: commandSignal,
88
+ };
89
+ orchestrationEnabled = restoreOrchestrationState(ctx);
90
+ try {
91
+ if (ctx.mode === "tui") {
92
+ const panel = openControlPanel(ctx, options);
93
+ panels.add(panel);
94
+ try {
95
+ await panel;
96
+ } finally {
97
+ panels.delete(panel);
98
+ }
99
+ } else ctx.ui.notify(controlPanelStatus(ctx, options), "info");
100
+ } catch (error) {
101
+ if (current()) ctx.ui.notify(String(error), "error");
112
102
  }
113
- ctx.ui.notify("Usage: /herdr [connect [machine] | board]", "warning");
114
103
  },
115
104
  });
116
105
 
117
106
  pi.on("session_start", async (_event, ctx) => {
107
+ resetLifetime();
118
108
  orchestrationEnabled = restoreOrchestrationState(ctx);
119
109
  await activateController(fleet, ctx);
120
110
  });
121
111
 
122
- pi.on("session_shutdown", () => {
112
+ pi.on("session_shutdown", async () => {
113
+ sessionLifetime.abort();
123
114
  fleet.deactivate();
115
+ await Promise.allSettled(panels);
124
116
  });
125
117
  }
126
118
 
package/src/fleet.ts CHANGED
@@ -107,6 +107,13 @@ function groupSaved(values: unknown[]): Map<string, unknown[]> {
107
107
  }
108
108
 
109
109
  export class AgentFleet {
110
+ private readonly listeners = new Set<() => void>();
111
+ subscribe(listener: () => void): () => void {
112
+ this.listeners.add(listener);
113
+ return () => {
114
+ this.listeners.delete(listener);
115
+ };
116
+ }
110
117
  private contextRelay:
111
118
  | ((
112
119
  ctx: ExtensionContext,
@@ -206,6 +213,7 @@ export class AgentFleet {
206
213
  this.runtimes.clear();
207
214
  renderAgentWidget(this.context, [], []);
208
215
  this.context = undefined;
216
+ for (const listener of this.listeners) listener();
209
217
  }
210
218
 
211
219
  isActive(): boolean {
@@ -278,7 +286,7 @@ export class AgentFleet {
278
286
  }
279
287
  if (runtime.status !== "connected" || !runtime.client || !runtime.monitor) {
280
288
  throw new Error(
281
- `Herdr machine ${JSON.stringify(name)} is ${runtime.status}${runtime.reason ? `: ${runtime.reason}` : ""}; run /herdr connect ${name} to retry`,
289
+ `Herdr machine ${JSON.stringify(name)} is ${runtime.status}${runtime.reason ? `: ${runtime.reason}` : ""}; open /herdr → Status to reconnect`,
282
290
  );
283
291
  }
284
292
  const remote =
@@ -442,6 +450,10 @@ export class AgentFleet {
442
450
  ? { monitoringIssue: runtime.monitoringIssue }
443
451
  : {}),
444
452
  ...(runtime.reason ? { reason: runtime.reason } : {}),
453
+ ...(runtime.contextRelayError
454
+ ? { contextRelayError: runtime.contextRelayError }
455
+ : {}),
456
+ ...(runtime.attempting ? { attempting: true } : {}),
445
457
  };
446
458
  }
447
459
 
@@ -469,7 +481,7 @@ export class AgentFleet {
469
481
  };
470
482
  this.refresh();
471
483
  this.context?.ui.notify(
472
- `${machine}: ${issue.message}${runtime.local ? "" : `\nRun /herdr connect ${machine} to retry`}`,
484
+ `${machine}: ${issue.message}${runtime.local ? "" : "\nOpen /herdr → Status to reconnect"}`,
473
485
  "warning",
474
486
  );
475
487
  },
@@ -511,7 +523,7 @@ export class AgentFleet {
511
523
  if (this.context !== ctx || this.runtimes.get(name) !== runtime) return;
512
524
  runtime.contextRelayError = errorMessage(error);
513
525
  ctx.ui.notify(
514
- `Context sharing unavailable on ${name}: ${runtime.contextRelayError}\nRun /herdr connect ${name} to retry sharing.`,
526
+ `Context sharing unavailable on ${name}: ${runtime.contextRelayError}\nOpen /herdr → Status to retry sharing.`,
515
527
  "warning",
516
528
  );
517
529
  }
@@ -523,6 +535,7 @@ export class AgentFleet {
523
535
  const generation = this.generation;
524
536
  if (!monitor || !ctx || runtime.attempting) return;
525
537
  runtime.attempting = true;
538
+ this.refresh();
526
539
  try {
527
540
  if (
528
541
  runtime.contextRelayError &&
@@ -549,6 +562,7 @@ export class AgentFleet {
549
562
  } finally {
550
563
  if (this.runtimes.get(name) === runtime && runtime.monitor === monitor)
551
564
  delete runtime.attempting;
565
+ this.refresh();
552
566
  }
553
567
  }
554
568
 
@@ -658,7 +672,7 @@ export class AgentFleet {
658
672
  runtime.reason = reason;
659
673
  this.changed();
660
674
  this.context?.ui.notify(
661
- `Shepherdr unavailable on ${name}: ${reason}\nRun /herdr connect ${name} to retry`,
675
+ `Shepherdr unavailable on ${name}: ${reason}\nOpen /herdr → Status to reconnect`,
662
676
  "warning",
663
677
  );
664
678
  }
@@ -673,6 +687,7 @@ export class AgentFleet {
673
687
  private refresh(): void {
674
688
  if (!this.context) return;
675
689
  renderAgentWidget(this.context, this.list(), this.statuses());
690
+ for (const listener of this.listeners) listener();
676
691
  }
677
692
 
678
693
  private persistedAgents(): Array<MonitoredAgent & { machine: string }> {
@@ -23,21 +23,14 @@ const Machine = Type.Object({
23
23
  const Catalog = Type.Array(Machine);
24
24
  export type SshMachine = Static<typeof Machine>;
25
25
 
26
- export async function readMachineCatalog(): Promise<
27
- Record<string, SshMachine>
28
- > {
26
+ export async function withHerdrBinary<T>(
27
+ run: (binary: string) => Promise<T>,
28
+ ): Promise<T> {
29
29
  const inheritedBinary = process.env["HERDR_BIN_PATH"]?.trim() || "herdr";
30
30
  let binary = inheritedBinary;
31
- const read = (path: string) =>
32
- promisify(execFile)(path, ["machine", "list", "--json"], {
33
- timeout: 10_000,
34
- maxBuffer: 1024 * 1024,
35
- encoding: "utf8",
36
- });
37
- let stdout: string;
38
31
  try {
39
32
  try {
40
- ({ stdout } = await read(binary));
33
+ return await run(binary);
41
34
  } catch (error) {
42
35
  if (
43
36
  !(error instanceof Error) ||
@@ -50,14 +43,27 @@ export async function readMachineCatalog(): Promise<
50
43
  }
51
44
  // Linux /proc executable paths can retain this suffix after replacement.
52
45
  binary = binary.slice(0, -" (deleted)".length);
53
- ({ stdout } = await read(binary));
46
+ return await run(binary);
54
47
  }
55
48
  } catch (error) {
56
49
  throw new Error(
57
- `Could not read Herdr machines${binary !== inheritedBinary ? " after retrying stale HERDR_BIN_PATH" : ""}: ${error instanceof Error ? error.message : String(error)}`,
50
+ `Herdr failed${binary !== inheritedBinary ? " after retrying stale HERDR_BIN_PATH" : ""}: ${error instanceof Error ? error.message : String(error)}`,
58
51
  { cause: error },
59
52
  );
60
53
  }
54
+ }
55
+
56
+ export async function readMachineCatalog(
57
+ signal?: AbortSignal,
58
+ ): Promise<Record<string, SshMachine>> {
59
+ const { stdout } = await withHerdrBinary((binary) =>
60
+ promisify(execFile)(binary, ["machine", "list", "--json"], {
61
+ signal,
62
+ timeout: 10_000,
63
+ maxBuffer: 1024 * 1024,
64
+ encoding: "utf8",
65
+ }),
66
+ );
61
67
  let value: unknown;
62
68
  try {
63
69
  value = JSON.parse(stdout);
package/src/messages.ts CHANGED
@@ -6,6 +6,7 @@ import {
6
6
  } from "@earendil-works/pi-coding-agent";
7
7
  import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
8
8
  import { activityTask } from "./activity.js";
9
+ import type { BoardBinding } from "./board/identity.js";
9
10
  import { sendPolicyMessage, startPreparedIdleTurn } from "./delivery.js";
10
11
  import { getCurrentPane, getSnapshot } from "./herdr.js";
11
12
  import type { HerdrConnection } from "./herdr-client.js";
@@ -25,6 +26,44 @@ const MAX_REALTIME_VOICE_PROMPT_BYTES = 8 * 1_024;
25
26
  const DELEGATED_WORKER_GUIDANCE =
26
27
  "If blocked mid-run, use a question-asking tool, not peer messages. Without one, end with the blocker. Finish with an assistant reply, not a separate send report; never watch your parent.";
27
28
 
29
+ export function attachmentMessage(
30
+ controllerContextAgent?: string,
31
+ boardAgent?: string,
32
+ ) {
33
+ return {
34
+ customType: "herdr-agent-attachment",
35
+ content: [
36
+ ...(controllerContextAgent
37
+ ? [
38
+ `Controller notes/history: ${controllerContextAgent}; own context unchanged`,
39
+ ]
40
+ : []),
41
+ ...(boardAgent ? [`Shared board: ${boardAgent}`] : []),
42
+ ].join("\n"),
43
+ display: true,
44
+ };
45
+ }
46
+
47
+ export function detachmentMessage(
48
+ controllerContextAgent?: string,
49
+ board?: BoardBinding,
50
+ ) {
51
+ return {
52
+ customType: "herdr-agent-detachment",
53
+ content: [
54
+ ...(controllerContextAgent
55
+ ? [
56
+ `Detached controller: ${controllerContextAgent}; checkpoints read-only, history unavailable; own context unchanged`,
57
+ ]
58
+ : []),
59
+ ...(board
60
+ ? [`Board restored: ${board.boardId} as ${board.agentName}`]
61
+ : []),
62
+ ].join("\n"),
63
+ display: true,
64
+ };
65
+ }
66
+
28
67
  function xml(value: string): string {
29
68
  return value
30
69
  .replaceAll("&", "&amp;")
@@ -0,0 +1,98 @@
1
+ // @howaboua/pi-shepherdr managed bridge
2
+ import { open } from "node:fs/promises";
3
+ import { isDeepStrictEqual } from "node:util";
4
+
5
+ /** @param {import('node:fs/promises').FileHandle} file @param {number} size */
6
+ async function* reverseSessionLines(file, size) {
7
+ let position = size;
8
+ let partial = Buffer.alloc(0);
9
+ while (position > 0) {
10
+ const length = Math.min(64 * 1024, position);
11
+ position -= length;
12
+ const chunk = Buffer.allocUnsafe(length);
13
+ const { bytesRead } = await file.read(chunk, 0, length, position);
14
+ const data = Buffer.concat([chunk.subarray(0, bytesRead), partial]);
15
+ let end = data.length;
16
+ for (let index = data.length - 1; index >= 0; index -= 1) {
17
+ if (data[index] !== 10) continue;
18
+ yield data.subarray(index + 1, end);
19
+ end = index;
20
+ }
21
+ partial = data.subarray(0, end);
22
+ }
23
+ yield partial;
24
+ }
25
+
26
+ /** @param {string} path @param {{protocol: 1, threadId: string, sessionId: string, agentName: string, storage: "session"}} identity */
27
+ export async function readPersistedNoteEntries(path, identity) {
28
+ const file = await open(path, "r");
29
+ try {
30
+ const metadata = await file.stat();
31
+ const head = Buffer.alloc(64 * 1024);
32
+ const { bytesRead } = await file.read(head, 0, head.length, 0);
33
+ const newline = head.subarray(0, bytesRead).indexOf(10);
34
+ if (newline < 0) throw new Error("Invalid saved session header");
35
+ const header = JSON.parse(head.subarray(0, newline).toString("utf8"));
36
+ if (header.type !== "session" || header.id !== identity.threadId)
37
+ throw new Error("Saved checkpoint owner identity changed");
38
+ const entries = [];
39
+ let target;
40
+ let done = false;
41
+ let identityChecked = false;
42
+ let bytes = 0;
43
+ for await (const line of reverseSessionLines(file, metadata.size)) {
44
+ if (!line.length) continue;
45
+ let entry;
46
+ try {
47
+ entry = JSON.parse(line.toString("utf8"));
48
+ } catch {
49
+ throw new Error(
50
+ "Saved session contains an incomplete record; retry after the owner settles",
51
+ );
52
+ }
53
+ if (
54
+ entry.type === "custom" &&
55
+ entry.customType === "codex-context-agent" &&
56
+ entry.data?.threadId === identity.threadId
57
+ ) {
58
+ if (identityChecked || !isDeepStrictEqual(entry.data, identity))
59
+ throw new Error("Saved checkpoint owner identity changed");
60
+ identityChecked = true;
61
+ }
62
+ if (done || typeof entry.id !== "string" || entry.type === "session")
63
+ continue;
64
+ target ??= entry.id;
65
+ if (entry.id !== target) continue;
66
+ if (
67
+ (entry.type === "custom" &&
68
+ ["codex-context-note", "codex-context-note-snapshot"].includes(
69
+ entry.customType,
70
+ )) ||
71
+ (entry.type === "branch_summary" &&
72
+ entry.details?.codexContextNoteHandoff)
73
+ ) {
74
+ bytes += line.length;
75
+ if (bytes > 7 * 1024 * 1024)
76
+ throw new Error("Saved checkpoints exceed the transport limit");
77
+ entries.push(entry);
78
+ }
79
+ if (
80
+ entry.type === "custom" &&
81
+ entry.customType === "codex-context-note-snapshot"
82
+ )
83
+ done = true;
84
+ if (typeof entry.parentId !== "string") done = true;
85
+ else target = entry.parentId;
86
+ }
87
+ if (!identityChecked)
88
+ throw new Error("Saved checkpoint owner identity is unavailable");
89
+ const after = await file.stat();
90
+ if (after.size !== metadata.size || after.mtimeMs !== metadata.mtimeMs)
91
+ throw new Error(
92
+ "Saved checkpoint owner is changing; retry after it settles",
93
+ );
94
+ return { entries: entries.reverse(), savedAt: metadata.mtimeMs };
95
+ } finally {
96
+ await file.close();
97
+ }
98
+ }
@@ -4,6 +4,7 @@ import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
4
4
  import { createConnection, createServer } from "node:net";
5
5
  import { homedir } from "node:os";
6
6
  import { dirname, join } from "node:path";
7
+ import { readPersistedNoteEntries } from "./shepherdr-checkpoints.mjs";
7
8
  import { readReceiver } from "./shepherdr-peer.mjs";
8
9
 
9
10
  const MAX_BYTES = 8 * 1024 * 1024;
@@ -41,6 +42,50 @@ function hasCode(error, code) {
41
42
  * @returns {Promise<unknown>} */
42
43
  export async function requestContext(path, request, signal) {
43
44
  signal?.throwIfAborted();
45
+ if (
46
+ request &&
47
+ typeof request === "object" &&
48
+ "operation" in request &&
49
+ request.operation === "attachment-persisted-notes"
50
+ ) {
51
+ if (
52
+ !("identity" in request) ||
53
+ !request.identity ||
54
+ typeof request.identity !== "object"
55
+ )
56
+ throw new Error("Invalid saved checkpoint identity");
57
+ const identity = request.identity;
58
+ if (
59
+ !("protocol" in identity) ||
60
+ identity.protocol !== 1 ||
61
+ !("threadId" in identity) ||
62
+ typeof identity.threadId !== "string" ||
63
+ !identity.threadId ||
64
+ !("sessionId" in identity) ||
65
+ typeof identity.sessionId !== "string" ||
66
+ !identity.sessionId ||
67
+ !("agentName" in identity) ||
68
+ typeof identity.agentName !== "string" ||
69
+ !/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(identity.agentName) ||
70
+ !("storage" in identity) ||
71
+ identity.storage !== "session"
72
+ )
73
+ throw new Error("Invalid saved checkpoint identity");
74
+ if (path.endsWith(".shepherdr-context.json"))
75
+ return readPersistedNoteEntries(
76
+ path.slice(0, -".shepherdr-context.json".length),
77
+ {
78
+ ...identity,
79
+ protocol: 1,
80
+ threadId: identity.threadId,
81
+ sessionId: identity.sessionId,
82
+ agentName: identity.agentName,
83
+ storage: "session",
84
+ },
85
+ );
86
+ // A relay can only reach the authenticated owner, which selects its own
87
+ // saved session. Never interpret a relay path as a checkpoint file.
88
+ }
44
89
  let descriptor;
45
90
  try {
46
91
  descriptor = JSON.parse(await readReceiver(path));
@@ -11,7 +11,7 @@ import {
11
11
  import { sendPeerMessage } from "./shepherdr-peer.mjs";
12
12
  import { readSessionView } from "./shepherdr-session.mjs";
13
13
 
14
- const BRIDGE_VERSION = 11;
14
+ const BRIDGE_VERSION = 13;
15
15
  const MAX_FRAME_BYTES = 8 * 1024 * 1024;
16
16
  const subscriptions = new Map();
17
17
  const contextRelays = new Map();
@@ -14,10 +14,11 @@ import type {
14
14
  SessionView,
15
15
  } from "./types.js";
16
16
 
17
- const BRIDGE_VERSION = 11;
17
+ const BRIDGE_VERSION = 13;
18
18
  const REMOTE_HELPER = "~/.pi/agent/shepherdr.mjs";
19
19
  const REMOTE_PEER_HELPER = "~/.pi/agent/shepherdr-peer.mjs";
20
20
  const REMOTE_SESSION_HELPER = "~/.pi/agent/shepherdr-session.mjs";
21
+ const REMOTE_CHECKPOINT_HELPER = "~/.pi/agent/shepherdr-checkpoints.mjs";
21
22
  const REMOTE_CONTEXT_HELPER = "~/.pi/agent/shepherdr-context.mjs";
22
23
  const MAX_FRAME_BYTES = 8 * 1024 * 1024;
23
24
  const MAX_DIAGNOSTIC_BYTES = 8 * 1024;
@@ -201,7 +202,7 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
201
202
  config: SshMachine,
202
203
  onClose: (error: Error) => void,
203
204
  ): Promise<RemoteHerdrClient> {
204
- const [source, peerSource, sessionSource, contextSource] =
205
+ const [source, peerSource, sessionSource, contextSource, checkpointSource] =
205
206
  await Promise.all([
206
207
  readFile(
207
208
  fileURLToPath(new URL("./remote/shepherdr.mjs", import.meta.url)),
@@ -221,9 +222,15 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
221
222
  new URL("./remote/shepherdr-context.mjs", import.meta.url),
222
223
  ),
223
224
  ),
225
+ readFile(
226
+ fileURLToPath(
227
+ new URL("./remote/shepherdr-checkpoints.mjs", import.meta.url),
228
+ ),
229
+ ),
224
230
  ]);
225
231
  await deploy(config, peerSource, REMOTE_PEER_HELPER);
226
232
  await deploy(config, sessionSource, REMOTE_SESSION_HELPER);
233
+ await deploy(config, checkpointSource, REMOTE_CHECKPOINT_HELPER);
227
234
  await deploy(config, contextSource, REMOTE_CONTEXT_HELPER);
228
235
  await deploy(config, source, REMOTE_HELPER);
229
236
  const child = spawnConnector(config, remoteCommand(config));
@@ -272,7 +279,7 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
272
279
  contextRelayPath(): string {
273
280
  if (!this.relayPath)
274
281
  throw new Error(
275
- "Shared context relay is unavailable; run /herdr connect to retry",
282
+ "Shared context relay is unavailable; open /herdr → Status to retry",
276
283
  );
277
284
  return this.relayPath;
278
285
  }