@howaboua/pi-shepherdr 0.2.27 → 0.2.28-core.12.1.gda85fa2e8a0f

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.
Files changed (112) hide show
  1. package/README.md +48 -48
  2. package/index.ts +7 -1
  3. package/package.json +2 -9
  4. package/src/agent-identity.ts +3 -3
  5. package/src/agents-contract.ts +10 -14
  6. package/src/agents-discovery.ts +34 -54
  7. package/src/agents-focus.ts +23 -35
  8. package/src/agents-spawn.ts +24 -23
  9. package/src/agents-tool.ts +4 -19
  10. package/src/agents-work.ts +4 -3
  11. package/src/attachment-notes.ts +8 -7
  12. package/src/attachment-protocol.ts +3 -2
  13. package/src/attachment-routing.ts +1 -1
  14. package/src/attachment-target.ts +10 -18
  15. package/src/attachment.ts +14 -9
  16. package/src/board/discovery.ts +67 -0
  17. package/src/board/host.ts +93 -63
  18. package/src/board/membership.ts +16 -11
  19. package/src/board/records.ts +185 -0
  20. package/src/close-idle.ts +2 -9
  21. package/src/context-briefing.ts +230 -0
  22. package/src/context-routing.ts +1 -1
  23. package/src/control-panel/index.ts +2 -4
  24. package/src/control-panel/items.ts +1 -11
  25. package/src/control-panel/view.ts +3 -9
  26. package/src/controller.ts +50 -63
  27. package/src/core/AGENTS.md +7 -4
  28. package/src/core/admission-broker.mjs +235 -0
  29. package/src/core/admission-endpoint.ts +180 -0
  30. package/src/core/admission-owner.mjs +52 -0
  31. package/src/core/admission-startup.ts +130 -0
  32. package/src/core/admission.ts +181 -0
  33. package/src/core/agents.ts +102 -0
  34. package/src/core/backend.ts +110 -84
  35. package/src/core/client.ts +16 -0
  36. package/src/core/focus-channel-helper.mjs +6 -27
  37. package/src/core/focus-channel-wire.mjs +9 -6
  38. package/src/core/focus-channel.ts +5 -3
  39. package/src/core/focus-window.ts +15 -4
  40. package/src/core/helper-bootstrap.mjs +70 -0
  41. package/src/core/helper-context.mjs +98 -0
  42. package/src/core/helper-core.mjs +121 -0
  43. package/src/core/machines.ts +30 -0
  44. package/src/core/registration.ts +7 -2
  45. package/src/core/remote-endpoint.ts +80 -74
  46. package/src/core/remote-helper.ts +330 -0
  47. package/src/core/remote-reader.ts +3 -42
  48. package/src/core/remote-service.mjs +239 -0
  49. package/src/core/remote-transport.ts +290 -0
  50. package/src/core/spawn.ts +20 -20
  51. package/src/core/terminal-peer.mjs +57 -0
  52. package/src/core/terminal.ts +4 -2
  53. package/src/delivery.ts +39 -0
  54. package/src/fleet/catalog.ts +16 -58
  55. package/src/fleet/connection.ts +9 -18
  56. package/src/fleet/index.ts +38 -76
  57. package/src/fleet/inspection.ts +9 -22
  58. package/src/fleet/machine.ts +28 -12
  59. package/src/fleet/monitor.ts +8 -29
  60. package/src/fleet/persistence.ts +2 -2
  61. package/src/fleet/reconnect.ts +5 -3
  62. package/src/fleet/setup.ts +6 -16
  63. package/src/launch-contract.ts +0 -3
  64. package/src/launch-location.ts +4 -132
  65. package/src/launch.ts +18 -144
  66. package/src/messages/attachments.ts +1 -1
  67. package/src/messages/attribution.ts +9 -14
  68. package/src/messages/events.ts +5 -9
  69. package/src/messages/focus.ts +2 -7
  70. package/src/messages/guidance.ts +2 -43
  71. package/src/messages/peer-sharing.ts +133 -0
  72. package/src/monitor-events.ts +14 -43
  73. package/src/monitor-extension-messages.ts +5 -6
  74. package/src/monitor-record.ts +4 -0
  75. package/src/monitor-state.ts +1 -101
  76. package/src/monitor.ts +38 -66
  77. package/src/notes-discovery.ts +67 -0
  78. package/src/peer-inbox.ts +21 -27
  79. package/src/remote/context-relay.ts +25 -10
  80. package/src/remote/notes-reader.mjs +67 -0
  81. package/src/remote/shepherdr-channel.mjs +1 -1
  82. package/src/remote/shepherdr-checkpoints.mjs +49 -102
  83. package/src/remote/shepherdr-context.mjs +1 -1
  84. package/src/remote/shepherdr-peer.mjs +19 -24
  85. package/src/remote/shepherdr-session.mjs +18 -7
  86. package/src/saved-context.ts +62 -0
  87. package/src/settlement/collector.ts +29 -9
  88. package/src/settlement/index.ts +35 -6
  89. package/src/shared-context-host.ts +27 -33
  90. package/src/shared-context.ts +44 -15
  91. package/src/spawn-context.ts +11 -3
  92. package/src/spawn-ownership.ts +1 -1
  93. package/src/ssh-setup.ts +40 -73
  94. package/src/types.ts +4 -8
  95. package/src/voice-handoff.ts +1 -1
  96. package/src/widget.ts +7 -2
  97. package/src/worker-ownership.ts +2 -8
  98. package/src/worker-service.ts +6 -14
  99. package/src/core/context-relay.mjs +0 -111
  100. package/src/core/remote-exec.ts +0 -122
  101. package/src/core/remote-helper.mjs +0 -244
  102. package/src/core/remote-relay.ts +0 -191
  103. package/src/core/request.ts +0 -124
  104. package/src/herdr-client.ts +0 -364
  105. package/src/herdr.ts +0 -268
  106. package/src/machine-catalog.ts +0 -83
  107. package/src/monitor-event.ts +0 -84
  108. package/src/remote/client.ts +0 -127
  109. package/src/remote/deployment.ts +0 -179
  110. package/src/remote/focus-channels.ts +0 -89
  111. package/src/remote/shepherdr.mjs +0 -504
  112. package/src/remote/transport.ts +0 -369
@@ -0,0 +1,230 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import {
3
+ buildSessionContext,
4
+ type ExtensionAPI,
5
+ type ExtensionContext,
6
+ type SessionEntry,
7
+ } from "@earendil-works/pi-coding-agent";
8
+ import type {
9
+ CODEX_CONTEXT_BRIEFING_TYPE,
10
+ CodexContextBriefing,
11
+ CodexContextBriefingHandler,
12
+ } from "@howaboua/pi-codex-conversion/developer-messages";
13
+ import { registerInferenceBriefing } from "./delivery.js";
14
+
15
+ // Conversion projects this durable protocol in inference, compaction and native replay.
16
+ const BRIEFING: typeof CODEX_CONTEXT_BRIEFING_TYPE = "codex-context-briefing";
17
+
18
+ export function registerContextBriefing(
19
+ pi: ExtensionAPI,
20
+ record: CodexContextBriefingHandler,
21
+ ) {
22
+ const hosted = registerInferenceBriefing(pi, record);
23
+ pi.on("context_with_system", async (event, ctx) => {
24
+ if (hosted.hosted()) return;
25
+ try {
26
+ await record(ctx, undefined, event.messages);
27
+ return { messages: projectNative(ctx, event.messages) };
28
+ } catch (error) {
29
+ ctx.abort();
30
+ throw error;
31
+ }
32
+ });
33
+ }
34
+
35
+ export function contextBriefingWindow(
36
+ ctx: ExtensionContext,
37
+ windowId?: string,
38
+ ) {
39
+ const branch = ctx.sessionManager.getBranch();
40
+ const compaction = branch.findLastIndex(
41
+ (entry) =>
42
+ entry.type === "compaction" &&
43
+ !(
44
+ entry.details &&
45
+ typeof entry.details === "object" &&
46
+ "strategy" in entry.details &&
47
+ entry.details.strategy === "codex-context-window"
48
+ ),
49
+ );
50
+ const boundary = branch.findLastIndex((entry) => briefingIdentity(entry));
51
+ return compaction > boundary
52
+ ? branch[compaction]!.id
53
+ : (windowId ??
54
+ (boundary >= 0
55
+ ? briefingIdentity(branch[boundary]!)?.currentWindowId
56
+ : undefined) ??
57
+ ctx.sessionManager.getSessionId());
58
+ }
59
+
60
+ export function hasContextRollover(ctx: ExtensionContext): boolean {
61
+ return ctx.sessionManager.getBranch().some((entry) => {
62
+ if (entry.type === "compaction") return true;
63
+ return (briefingIdentity(entry)?.windowNumber ?? 0) > 0;
64
+ });
65
+ }
66
+
67
+ /** Consume owner-authored identities without depending on an optional runtime. */
68
+ function briefingIdentity(entry: SessionEntry) {
69
+ if (entry.type !== "custom_message") return;
70
+ const details = entry.details;
71
+ if (!details || typeof details !== "object") return;
72
+ let identity: unknown;
73
+ if (
74
+ entry.customType === "notes-compaction:window:v1" &&
75
+ "protocol" in details &&
76
+ details.protocol === 1 &&
77
+ "kind" in details &&
78
+ details.kind === "window" &&
79
+ "identity" in details
80
+ )
81
+ identity = details.identity;
82
+ else if (
83
+ entry.customType === "codex-context-window" &&
84
+ "contextManagement" in details &&
85
+ details.contextManagement &&
86
+ typeof details.contextManagement === "object" &&
87
+ "kind" in details.contextManagement &&
88
+ details.contextManagement.kind === "window"
89
+ )
90
+ identity = details.contextManagement;
91
+ if (
92
+ identity &&
93
+ typeof identity === "object" &&
94
+ "currentWindowId" in identity &&
95
+ typeof identity.currentWindowId === "string" &&
96
+ identity.currentWindowId &&
97
+ "windowNumber" in identity &&
98
+ typeof identity.windowNumber === "number" &&
99
+ Number.isInteger(identity.windowNumber) &&
100
+ identity.windowNumber >= 0
101
+ )
102
+ return {
103
+ currentWindowId: identity.currentWindowId,
104
+ windowNumber: identity.windowNumber,
105
+ };
106
+ }
107
+
108
+ export async function recordContextBriefing(
109
+ pi: ExtensionAPI,
110
+ ctx: ExtensionContext,
111
+ owner: string,
112
+ key: string,
113
+ content: () => Promise<string | undefined>,
114
+ ) {
115
+ const saved = ctx.sessionManager
116
+ .getEntries()
117
+ .findLast(
118
+ (entry) =>
119
+ entry.type === "custom" &&
120
+ entry.customType === BRIEFING &&
121
+ readBriefing(entry.data).owner === owner &&
122
+ readBriefing(entry.data).key === key,
123
+ );
124
+ if (saved?.type === "custom") {
125
+ // Tree may select an ancestor before its metadata child. Reuse immutable bytes/ID.
126
+ if (
127
+ !ctx.sessionManager
128
+ .getBranch()
129
+ .some(
130
+ (entry) =>
131
+ entry.type === "custom" &&
132
+ entry.customType === BRIEFING &&
133
+ readBriefing(entry.data).owner === owner &&
134
+ readBriefing(entry.data).key === key,
135
+ )
136
+ )
137
+ pi.appendEntry(BRIEFING, readBriefing(saved.data));
138
+ return;
139
+ }
140
+ const value = await content();
141
+ if (value === undefined) return;
142
+ pi.appendEntry(BRIEFING, {
143
+ protocol: 1,
144
+ id: randomUUID(),
145
+ owner,
146
+ key,
147
+ content: value,
148
+ } satisfies CodexContextBriefing);
149
+ }
150
+
151
+ function projectNative(
152
+ ctx: ExtensionContext,
153
+ messages: NativeMessage[],
154
+ ): NativeMessage[] {
155
+ const entries = ctx.sessionManager.getBranch().map((entry) => {
156
+ if (entry.type !== "custom" || entry.customType !== BRIEFING) return entry;
157
+ const briefing = readBriefing(entry.data);
158
+ return {
159
+ ...entry,
160
+ type: "custom_message" as const,
161
+ content: briefing.content,
162
+ display: false,
163
+ details: briefing,
164
+ };
165
+ });
166
+ const reconstructed = buildSessionContext(entries).messages;
167
+ const positions = new Map<string, number[]>();
168
+ messages.forEach((message, index) => {
169
+ const key = messageKey(message);
170
+ const indices = positions.get(key) ?? [];
171
+ indices.push(index);
172
+ positions.set(key, indices);
173
+ });
174
+ const insertions = new Map<number, NativeMessage[]>();
175
+ let pending: NativeMessage[] = [];
176
+ let last = messages[0]?.role === "system" ? 0 : -1;
177
+ const insert = (index: number) => {
178
+ if (!pending.length) return;
179
+ const position =
180
+ messages[0]?.role === "system" ? Math.max(1, index) : index;
181
+ insertions.set(position, [...(insertions.get(position) ?? []), ...pending]);
182
+ pending = [];
183
+ };
184
+ for (const message of reconstructed) {
185
+ const index = positions.get(messageKey(message))?.shift();
186
+ if (index !== undefined) {
187
+ insert(index);
188
+ last = index;
189
+ } else if (message.role === "custom" && message.customType === BRIEFING) {
190
+ pending.push(message);
191
+ }
192
+ }
193
+ insert(last + 1);
194
+ return messages
195
+ .flatMap((message, index) => [...(insertions.get(index) ?? []), message])
196
+ .concat(insertions.get(messages.length) ?? []);
197
+ }
198
+
199
+ type NativeMessage = ReturnType<typeof buildSessionContext>["messages"][number];
200
+ function messageKey(message: NativeMessage) {
201
+ return JSON.stringify([
202
+ message.role,
203
+ message.timestamp,
204
+ message.role === "custom"
205
+ ? message.customType === BRIEFING
206
+ ? readBriefing(message.details).id
207
+ : message.customType
208
+ : message.role === "toolResult"
209
+ ? message.toolCallId
210
+ : undefined,
211
+ ]);
212
+ }
213
+ function readBriefing(value: unknown): CodexContextBriefing {
214
+ if (
215
+ !value ||
216
+ typeof value !== "object" ||
217
+ !("protocol" in value) ||
218
+ value.protocol !== 1 ||
219
+ !("id" in value) ||
220
+ typeof value.id !== "string" ||
221
+ !("owner" in value) ||
222
+ typeof value.owner !== "string" ||
223
+ !("key" in value) ||
224
+ typeof value.key !== "string" ||
225
+ !("content" in value) ||
226
+ typeof value.content !== "string"
227
+ )
228
+ throw new Error("Invalid saved context briefing");
229
+ return value as CodexContextBriefing;
230
+ }
@@ -1,6 +1,6 @@
1
1
  import { isDeepStrictEqual } from "node:util";
2
2
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
3
- import type { ContextAgentIdentity } from "@howaboua/pi-notes-compaction/context-sharing";
3
+ import type { ContextAgentIdentity } from "@howaboua/pi-agent-comms/context-sharing";
4
4
  import {
5
5
  attachmentOwner,
6
6
  attachmentRoutes,
@@ -15,12 +15,10 @@ export function controlPanelStatus(options: PanelOptions): string {
15
15
  ),
16
16
  ...(!options.fleet.isActive()
17
17
  ? [
18
- "Fleet inactive. Run Pi inside Herdr; open /herdr → Status to reconnect.",
18
+ "Fleet inactive. Run Pi inside a Core terminal; open /herdr → Status to reconnect.",
19
19
  ]
20
20
  : []),
21
- process.env["HC_TERMINAL_SOCKET"]
22
- ? "Open /herdr in TUI for Settings and Status. Manage machines in Herdr or with hc machine add."
23
- : "Open /herdr in TUI for Settings, Status and SSH Connections.",
21
+ "Open /herdr in TUI for Settings, Status and Connections.",
24
22
  ].join("\n");
25
23
  }
26
24
 
@@ -16,14 +16,6 @@ export function buildPanelItems(
16
16
  draft: SshSetupDraft,
17
17
  ): SettingItem[] {
18
18
  if (tab === "Connections") {
19
- if (process.env["HC_TERMINAL_SOCKET"])
20
- return [
21
- {
22
- id: "core-machines",
23
- label: "Manage machines in Herdr or with hc machine add",
24
- currentValue: "",
25
- },
26
- ];
27
19
  return sshSetupItems(draft);
28
20
  }
29
21
  if (tab === "Status")
@@ -33,9 +25,7 @@ export function buildPanelItems(
33
25
  label: "Refresh and reconnect",
34
26
  currentValue: "Enter",
35
27
  values: ["Enter"],
36
- description: process.env["HC_TERMINAL_SOCKET"]
37
- ? "Refresh Core machines and retry connections."
38
- : "Reload Herdr profiles and retry connections.",
28
+ description: "Refresh Core machines and retry connections.",
39
29
  },
40
30
  ...options.fleet.statuses().map((machine) => ({
41
31
  id: `machine:${machine.id}`,
@@ -147,15 +147,9 @@ export class PanelView {
147
147
  ),
148
148
  "",
149
149
  ...wrap(
150
- this.tab === "Settings"
151
- ? ""
152
- : this.tab === "Connections"
153
- ? process.env["HC_TERMINAL_SOCKET"]
154
- ? ""
155
- : "Remote needs Node on SSH PATH and Pi with Herdr integration. Herdr prepares its server before saving."
156
- : process.env["HC_TERMINAL_SOCKET"]
157
- ? "Select a machine to reconnect."
158
- : `${this.owners.fleet.isActive() ? "" : "Run Pi inside Herdr. "}Add SSH targets in Connections; select a machine here to reconnect.`,
150
+ this.tab === "Status" && !this.owners.fleet.isActive()
151
+ ? "Run Pi inside a Core terminal."
152
+ : "",
159
153
  ).filter((line) => line.trim()),
160
154
  "",
161
155
  ];
package/src/controller.ts CHANGED
@@ -2,13 +2,13 @@ import type {
2
2
  ExtensionAPI,
3
3
  ExtensionContext,
4
4
  } from "@earendil-works/pi-coding-agent";
5
+ import { closeIdleChildren } from "./close-idle.js";
5
6
  import {
6
7
  contextBriefingWindow,
7
8
  hasContextRollover,
8
9
  recordContextBriefing,
9
10
  registerContextBriefing,
10
- } from "@howaboua/pi-agent-board/integration";
11
- import { closeIdleChildren } from "./close-idle.js";
11
+ } from "./context-briefing.js";
12
12
  import { controlPanelStatus, openControlPanel } from "./control-panel/index.js";
13
13
  import { sendPolicyMessage } from "./delivery.js";
14
14
  import type { AgentFleet } from "./fleet/index.js";
@@ -70,64 +70,54 @@ export function registerAgentController(
70
70
  signal.throwIfAborted();
71
71
  return fleet.connect(machine);
72
72
  };
73
- registerContextBriefing(
74
- pi,
75
- "orchestration",
76
- (ctx) => restoreOrchestrationState(ctx).enabled,
77
- async (ctx, windowId, messages) => {
78
- const sessionId = ctx.sessionManager.getSessionId();
79
- const state = restoreOrchestrationState(ctx);
80
- const window = contextBriefingWindow(ctx, windowId);
81
- // Initialization and compaction may keep earlier messages. Only actual
82
- // selected context proves a toggle still supplies this window's guidance.
83
- if (
84
- state.visible &&
85
- messages?.some(
86
- (message) =>
87
- message.role === "custom" &&
88
- message.customType === ORCHESTRATION_STATE_TYPE &&
89
- message.timestamp === state.timestamp,
90
- )
73
+ registerContextBriefing(pi, async (ctx, windowId, messages) => {
74
+ const sessionId = ctx.sessionManager.getSessionId();
75
+ const state = restoreOrchestrationState(ctx);
76
+ const window = contextBriefingWindow(ctx, windowId);
77
+ // Initialization and compaction may keep earlier messages. Only actual
78
+ // selected context proves a toggle still supplies this window's guidance.
79
+ if (
80
+ state.visible &&
81
+ messages?.some(
82
+ (message) =>
83
+ message.role === "custom" &&
84
+ message.customType === ORCHESTRATION_STATE_TYPE &&
85
+ message.timestamp === state.timestamp,
91
86
  )
92
- return;
93
- const key = JSON.stringify([sessionId, window, state.id]);
94
- await recordContextBriefing(
95
- pi,
96
- ctx,
97
- "shepherdr-orchestration",
98
- key,
99
- async () => {
100
- const content = await orchestrationMessage(state.enabled);
101
- if (
102
- ctx.sessionManager.getSessionId() !== sessionId ||
103
- restoreOrchestrationState(ctx).id !== state.id
104
- )
105
- throw new Error("Orchestration changed during its briefing");
106
- ctx.signal?.throwIfAborted();
107
- return content;
108
- },
109
- );
110
- },
111
- );
112
- registerContextBriefing(
113
- pi,
114
- "active agents",
115
- () => fleet.list().length > 0,
116
- async (ctx, windowId) => {
117
- if (!hasContextRollover(ctx)) return;
118
- const key = JSON.stringify([
119
- ctx.sessionManager.getSessionId(),
120
- contextBriefingWindow(ctx, windowId),
121
- ]);
122
- await recordContextBriefing(
123
- pi,
124
- ctx,
125
- "shepherdr-active-agents",
126
- key,
127
- async () => activeAgentsBriefing(fleet.list(), fleet.statuses()),
128
- );
129
- },
130
- );
87
+ )
88
+ return;
89
+ const key = JSON.stringify([sessionId, window, state.id]);
90
+ await recordContextBriefing(
91
+ pi,
92
+ ctx,
93
+ "shepherdr-orchestration",
94
+ key,
95
+ async () => {
96
+ const content = await orchestrationMessage(state.enabled);
97
+ if (
98
+ ctx.sessionManager.getSessionId() !== sessionId ||
99
+ restoreOrchestrationState(ctx).id !== state.id
100
+ )
101
+ throw new Error("Orchestration changed during its briefing");
102
+ ctx.signal?.throwIfAborted();
103
+ return content;
104
+ },
105
+ );
106
+ });
107
+ registerContextBriefing(pi, async (ctx, windowId) => {
108
+ if (!hasContextRollover(ctx)) return;
109
+ const key = JSON.stringify([
110
+ ctx.sessionManager.getSessionId(),
111
+ contextBriefingWindow(ctx, windowId),
112
+ ]);
113
+ await recordContextBriefing(
114
+ pi,
115
+ ctx,
116
+ "shepherdr-active-agents",
117
+ key,
118
+ async () => activeAgentsBriefing(fleet.list(), fleet.statuses()),
119
+ );
120
+ });
131
121
  pi.registerCommand("herdr", {
132
122
  description: "Shepherdr settings, status, SSH setup and close-idle",
133
123
  handler: async (args, ctx) => {
@@ -224,10 +214,7 @@ async function activateController(
224
214
  fleet: AgentFleet,
225
215
  ctx: ExtensionContext,
226
216
  ): Promise<boolean> {
227
- if (
228
- !(process.env["HC_TERMINAL_ID"] && process.env["HC_TERMINAL_SOCKET"]) &&
229
- (process.env["HERDR_ENV"] !== "1" || !process.env["HERDR_SOCKET_PATH"])
230
- ) {
217
+ if (!process.env["HC_TERMINAL_ID"] || !process.env["HC_TERMINAL_SOCKET"]) {
231
218
  ctx.ui.notify("Shepherdr requires Pi to run inside Herdr", "error");
232
219
  return false;
233
220
  }
@@ -1,6 +1,9 @@
1
1
  - Shared `pane_id` is an internal address key here, not a window pane identity. Emit terminal identity; never manufacture layout/focus IDs. Scope remote addresses by permanent Core ID, not session names or mutable machine aliases.
2
2
  - Agent launches pass `caller` to the originating Core so it qualifies remote parent links. `parent` resolves on the target Core and can select an unrelated terminal with the same local ID. Keep `no_notify`, not `no_parent`: sidebar ancestry and notification delivery are separate.
3
- - Remote subscriptions are invalidations: Core 0.1.14 retains old aliases after rename. Host aggregate lists omit slow machines, so supervision reads the selected Core's own list through the verified helper. An empty startup mirror requires a direct get, not rollback.
4
- - Remote helper bundling reuses the unchanged native peer/session/context readers. Keep its data-URL relative-import map complete when those helpers gain dependencies; never edit or deploy over the legacy bridge.
5
- - Closing a plain Core request does not cancel accepted remote execution. Keep remote watches and exec watchdogs bounded; abort local callbacks before releasing their monitor/client owner.
6
- - Fleet teardown is synchronous. Context relay route ownership spans replacement connections: fence startup behind the previous owner's completed close, including accepted startup, and release route entries after bounded cleanup. Keep relay payload limits aligned in remote-relay.ts and context-relay.mjs; poll batches must fit raw exec/context limits after JSON escaping, not just each request.
3
+ - Host aggregate terminal lists can omit slow remotes. Use local event snapshots and the selected remote Core's own view; remote events invalidate watched records. An empty startup mirror requires a direct terminal.get, not rollback.
4
+ - remote-helper.ts bundles native peer/session/context readers as data URLs. Keep its explicit module map and rewritten relative imports complete when helper dependencies change. Bootstrap must stay below command-size limits; send the module bundle only after credited attachment admission, never install helper files or use machine.exec polling.
5
+ - Saved Notes reads optionally bundle the provider's public session reader, manifest dependency and exact-session index lookup. Resolve broken optional bundles to deferred error modules, never a rejected base-helper bundle. Checkpoints must import their reader lazily, resolving to that bundle or an explicit unavailable stub, never a package import on the remote machine. Keep discovery and parsing in Notes, retain cancellation and frame bounds, and reject oversized results rather than truncate saved data.
6
+ - Keep voice focus on its separate private helper so large Notes payloads cannot block the voice channel. App focus must verify a window on the target Core, not infer window identity from terminal IDs.
7
+ - Closing a request does not cancel accepted remote work. Preserve uncertain-delivery errors, bound startup and cleanup, and abort callbacks before releasing their owner. A helper accepted after cancellation must still be killed; its wire lease bounds cleanup after route loss.
8
+ - Fleet teardown is synchronous, helper close is asynchronous. Context routes in remote-transport.ts span replacement connections: await the previous owner's completed close before route startup, then remove only your own route entry after bounded cleanup. Keep frame/context limits aligned across transport, wire and helper.
9
+ - Admission ends at native readiness or read completion, never worker settlement. Keep control, subscriptions and reverse context calls outside its lanes. Core's 16-exec limit does not apply to native terminal launches. Broker loss must never replay accepted work or leak scheduling into model-facing results.