@phren/cli 0.3.53 → 0.3.55

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 (55) hide show
  1. package/dist/bridge/account-add.d.ts +7 -0
  2. package/dist/bridge/account-add.js +39 -0
  3. package/dist/bridge/claude-accounts.js +1 -1
  4. package/dist/bridge/client.js +1 -1
  5. package/dist/bridge/command.js +2 -0
  6. package/dist/bridge/computers.js +3 -2
  7. package/dist/bridge/conductor-role.d.ts +162 -2
  8. package/dist/bridge/conductor-role.js +56 -23
  9. package/dist/bridge/conductor-succession.d.ts +100 -0
  10. package/dist/bridge/conductor-succession.js +649 -0
  11. package/dist/bridge/continuation-launch.d.ts +54 -0
  12. package/dist/bridge/continuation-launch.js +106 -0
  13. package/dist/bridge/dispatch-command.js +11 -4
  14. package/dist/bridge/dispatch-hosts.d.ts +3 -0
  15. package/dist/bridge/dispatch-hosts.js +6 -1
  16. package/dist/bridge/dispatch-returns.d.ts +21 -3
  17. package/dist/bridge/dispatch-returns.js +169 -39
  18. package/dist/bridge/dispatch.d.ts +11 -0
  19. package/dist/bridge/dispatch.js +70 -5
  20. package/dist/bridge/git.js +82 -8
  21. package/dist/bridge/hand-off-queue.d.ts +3 -0
  22. package/dist/bridge/hand-off-queue.js +8 -0
  23. package/dist/bridge/hand-off.d.ts +13 -0
  24. package/dist/bridge/hand-off.js +20 -1
  25. package/dist/bridge/install.js +0 -6
  26. package/dist/bridge/launch-brief.d.ts +2 -0
  27. package/dist/bridge/launch-brief.js +19 -8
  28. package/dist/bridge/move-computers.d.ts +47 -0
  29. package/dist/bridge/move-computers.js +118 -0
  30. package/dist/bridge/peer-handoff.d.ts +5 -0
  31. package/dist/bridge/peer-handoff.js +52 -0
  32. package/dist/bridge/projects.js +13 -8
  33. package/dist/bridge/request-origin.d.ts +6 -0
  34. package/dist/bridge/request-origin.js +20 -0
  35. package/dist/bridge/scoped-gateway.d.ts +2 -1
  36. package/dist/bridge/scoped-gateway.js +16 -3
  37. package/dist/bridge/server-launch.d.ts +2 -0
  38. package/dist/bridge/server-launch.js +2 -0
  39. package/dist/bridge/server-routes.d.ts +6 -0
  40. package/dist/bridge/server-routes.js +228 -15
  41. package/dist/bridge/server.js +46 -24
  42. package/dist/bridge/session-move.d.ts +28 -1
  43. package/dist/bridge/session-move.js +266 -25
  44. package/dist/bridge/socket-budget.d.ts +29 -0
  45. package/dist/bridge/socket-budget.js +62 -0
  46. package/dist/bridge/terminal-herdr.js +14 -0
  47. package/dist/bridge/terminal-tmux.js +1 -0
  48. package/dist/bridge/terminal.d.ts +2 -0
  49. package/dist/bridge/terminal.js +6 -0
  50. package/dist/bridge/worker-relocation.d.ts +5 -0
  51. package/dist/bridge/worker-relocation.js +33 -0
  52. package/dist/bridge-hook.mjs +16480 -14296
  53. package/dist/modules/registry.js +8 -8
  54. package/dist/tools/dispatch.js +2 -1
  55. package/package.json +1 -1
@@ -0,0 +1,7 @@
1
+ import { z } from "zod";
2
+ import { type Json } from "./protocol.js";
3
+ export declare const accountAddSchema: z.ZodObject<{
4
+ slug: z.ZodString;
5
+ }, z.core.$strict>;
6
+ /** Open a shell for the owner to complete the existing interactive flow. */
7
+ export declare function addClaudeAccount(input: unknown, server: string): Promise<Json>;
@@ -0,0 +1,39 @@
1
+ import { existsSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { z } from "zod";
4
+ import { homeDir } from "../home-paths.js";
5
+ import { claudeHomes } from "./claude-accounts.js";
6
+ import { BridgeError, bridgeRoot } from "./protocol.js";
7
+ import { terminalProvider } from "./terminal.js";
8
+ export const accountAddSchema = z.object({ slug: z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/) }).strict();
9
+ const adding = new Set();
10
+ const pendingPanes = new Map();
11
+ /** Open a shell for the owner to complete the existing interactive flow. */
12
+ export async function addClaudeAccount(input, server) {
13
+ const { slug } = accountAddSchema.parse(input);
14
+ const key = `${bridgeRoot()}\0${slug}`;
15
+ if (adding.has(key) || claudeHomes().some(home => home.id === slug) || existsSync(path.join(homeDir(), `.claude-${slug}`)))
16
+ throw new BridgeError(409, "That Claude account already exists or is being added.");
17
+ adding.add(key);
18
+ try {
19
+ const terminal = terminalProvider();
20
+ if (!terminal.shellCommand)
21
+ throw new BridgeError(503, "This terminal cannot open an interactive account login.");
22
+ const pending = pendingPanes.get(key);
23
+ if (pending && (await terminal.listPanes(pending.server)).some(pane => pane.pane === pending.pane))
24
+ throw new BridgeError(409, "That Claude account is already being added in an open pane.");
25
+ pendingPanes.delete(key);
26
+ const before = new Set((await terminal.listPanes(server)).map(pane => pane.pane));
27
+ await terminal.create(server, { label: `Add Claude account ${slug}`, cwd: homeDir() });
28
+ const created = (await terminal.listPanes(server)).filter(pane => !before.has(pane.pane));
29
+ if (created.length !== 1)
30
+ throw new BridgeError(409, "The new account pane could not be identified safely.");
31
+ const pane = created[0];
32
+ pendingPanes.set(key, { server, pane: pane.pane });
33
+ await terminal.shellCommand(server, pane.pane, `phren bridge accounts add -- '${slug}'`);
34
+ return { target: { server, workspace: pane.workspace, tab: pane.tab, pane: pane.pane, source: "claude" }, terminalOnly: true };
35
+ }
36
+ finally {
37
+ adding.delete(key);
38
+ }
39
+ }
@@ -12,7 +12,7 @@ import { claudeConfigDir, homeDir } from "../home-paths.js";
12
12
  import { atomic, bridgeRoot } from "./protocol.js";
13
13
  import { claudePlan, monthlyAnniversary, subscriptionDate } from "./subscription.js";
14
14
  export const DEFAULT_ACCOUNT = "default";
15
- const SLUG = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
15
+ const SLUG = /^[a-z0-9][a-z0-9-]{0,31}$/;
16
16
  export function isAccountSlug(value) { return value === DEFAULT_ACCOUNT || SLUG.test(value); }
17
17
  function defaultHome(env) {
18
18
  const configured = Boolean(env.CLAUDE_CONFIG_DIR?.trim());
@@ -5,7 +5,7 @@ export async function hookRequest(route, data, options = { socketPath: socketPat
5
5
  const payload = data === undefined ? undefined : JSON.stringify(data);
6
6
  const method = options.method ?? (payload === undefined ? "GET" : "POST");
7
7
  const req = request({ ...options, path: route, method,
8
- headers: { Host: "phren.local", Connection: "close", ...(payload ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) } : {}) } }, response => {
8
+ headers: { Host: "phren.local", Connection: "close", ...options.headers, ...(payload ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) } : {}) } }, response => {
9
9
  const chunks = [];
10
10
  let size = 0;
11
11
  response.on("data", chunk => {
@@ -37,6 +37,8 @@ export async function runBridge(args, version) {
37
37
  break;
38
38
  }
39
39
  case "accounts": {
40
+ if (args[1] === "add" && args[2] === "--")
41
+ args.splice(2, 1);
40
42
  if (args.length === 1) {
41
43
  for (const harness of (await harnessInventory()).harnesses) {
42
44
  console.log(`${harness.source}: ${harness.installed ? `installed ${harness.version ?? ""}`.trim() : "not installed"}, ${harness.usable ? "usable" : `not usable (${harness.reason ?? "unknown"})`}`);
@@ -20,7 +20,7 @@ export function publicComputerKey(value) {
20
20
  return `ssh-ed25519 ${match[1]}`;
21
21
  }
22
22
  export function computerKeyLine(name, publicKey) {
23
- return `restrict,${peerForcedCommand} ${publicComputerKey(publicKey)} phren-computer:${computerName.parse(name)}`;
23
+ return `restrict,${peerForcedCommand.replace(" peer\"", ` peer:${computerName.parse(name)}\"`)} ${publicComputerKey(publicKey)} phren-computer:${name}`;
24
24
  }
25
25
  async function regularFile(file) {
26
26
  const info = await lstat(file).catch((error) => {
@@ -72,7 +72,8 @@ export async function acceptComputer(name, input, sshDirectory = path.join(homed
72
72
  computerName.parse(name);
73
73
  const prefixes = [`restrict,${peerForcedCommand} `, `restrict,pty,${forcedCommand} `];
74
74
  const raw = input.trim();
75
- const prefix = prefixes.find(value => raw.startsWith(value));
75
+ const namedPeer = /^restrict,command="sh ~\/\.local\/share\/phren\/bridge\/dispatch-scoped peer:[A-Za-z0-9_.-]+" /.exec(raw)?.[0];
76
+ const prefix = namedPeer ?? prefixes.find(value => raw.startsWith(value));
76
77
  const publicKey = publicComputerKey(prefix ? raw.slice(prefix.length) : raw);
77
78
  const line = computerKeyLine(name, publicKey);
78
79
  const encoded = publicKey.split(" ")[1];
@@ -38,6 +38,85 @@ declare const setNameSchema: z.ZodObject<{
38
38
  export type SetName = z.infer<typeof setNameSchema>;
39
39
  /** `conductor` absent is legacy mode: nothing has decided the role yet, so a
40
40
  * conductor is still recognized by its mux name. `null` is no conductor. */
41
+ export declare const successionSchema: z.ZodObject<{
42
+ id: z.ZodString;
43
+ generation: z.ZodString;
44
+ side: z.ZodEnum<{
45
+ origin: "origin";
46
+ successor: "successor";
47
+ }>;
48
+ phase: z.ZodEnum<{
49
+ aborted: "aborted";
50
+ committed: "committed";
51
+ prepared: "prepared";
52
+ preparing: "preparing";
53
+ }>;
54
+ originId: z.ZodString;
55
+ destinationId: z.ZodString;
56
+ previous: z.ZodObject<{
57
+ server: z.ZodString;
58
+ pane: z.ZodString;
59
+ terminal: z.ZodOptional<z.ZodString>;
60
+ workspace: z.ZodOptional<z.ZodString>;
61
+ tab: z.ZodOptional<z.ZodString>;
62
+ source: z.ZodOptional<z.ZodEnum<{
63
+ claude: "claude";
64
+ codex: "codex";
65
+ copilot: "copilot";
66
+ opencode: "opencode";
67
+ phren: "phren";
68
+ }>>;
69
+ session: z.ZodOptional<z.ZodString>;
70
+ since: z.ZodString;
71
+ by: z.ZodEnum<{
72
+ launch: "launch";
73
+ migrated: "migrated";
74
+ owner: "owner";
75
+ }>;
76
+ }, z.core.$strip>;
77
+ from: z.ZodObject<{
78
+ server: z.ZodString;
79
+ workspace: z.ZodString;
80
+ tab: z.ZodString;
81
+ pane: z.ZodString;
82
+ source: z.ZodEnum<{
83
+ claude: "claude";
84
+ codex: "codex";
85
+ copilot: "copilot";
86
+ opencode: "opencode";
87
+ phren: "phren";
88
+ }>;
89
+ session: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
90
+ }, z.core.$strip>;
91
+ connection: z.ZodObject<{
92
+ name: z.ZodString;
93
+ server: z.ZodString;
94
+ fingerprint: z.ZodString;
95
+ id: z.ZodString;
96
+ }, z.core.$strict>;
97
+ workers: z.ZodOptional<z.ZodArray<z.ZodObject<{
98
+ id: z.ZodString;
99
+ fingerprint: z.ZodOptional<z.ZodString>;
100
+ }, z.core.$strict>>>;
101
+ revoked: z.ZodOptional<z.ZodBoolean>;
102
+ activated: z.ZodOptional<z.ZodBoolean>;
103
+ target: z.ZodOptional<z.ZodObject<{
104
+ server: z.ZodString;
105
+ workspace: z.ZodString;
106
+ tab: z.ZodString;
107
+ pane: z.ZodString;
108
+ source: z.ZodEnum<{
109
+ claude: "claude";
110
+ codex: "codex";
111
+ copilot: "copilot";
112
+ opencode: "opencode";
113
+ phren: "phren";
114
+ }>;
115
+ session: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
116
+ }, z.core.$strip>>;
117
+ resume: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
118
+ }, z.core.$strict>;
119
+ export type ConductorSuccession = z.infer<typeof successionSchema>;
41
120
  declare const stateSchema: z.ZodObject<{
42
121
  version: z.ZodLiteral<1>;
43
122
  conductor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -65,10 +144,91 @@ declare const stateSchema: z.ZodObject<{
65
144
  name: z.ZodNullable<z.ZodString>;
66
145
  namedAt: z.ZodString;
67
146
  }, z.core.$strip>>;
147
+ succession: z.ZodOptional<z.ZodObject<{
148
+ id: z.ZodString;
149
+ generation: z.ZodString;
150
+ side: z.ZodEnum<{
151
+ origin: "origin";
152
+ successor: "successor";
153
+ }>;
154
+ phase: z.ZodEnum<{
155
+ aborted: "aborted";
156
+ committed: "committed";
157
+ prepared: "prepared";
158
+ preparing: "preparing";
159
+ }>;
160
+ originId: z.ZodString;
161
+ destinationId: z.ZodString;
162
+ previous: z.ZodObject<{
163
+ server: z.ZodString;
164
+ pane: z.ZodString;
165
+ terminal: z.ZodOptional<z.ZodString>;
166
+ workspace: z.ZodOptional<z.ZodString>;
167
+ tab: z.ZodOptional<z.ZodString>;
168
+ source: z.ZodOptional<z.ZodEnum<{
169
+ claude: "claude";
170
+ codex: "codex";
171
+ copilot: "copilot";
172
+ opencode: "opencode";
173
+ phren: "phren";
174
+ }>>;
175
+ session: z.ZodOptional<z.ZodString>;
176
+ since: z.ZodString;
177
+ by: z.ZodEnum<{
178
+ launch: "launch";
179
+ migrated: "migrated";
180
+ owner: "owner";
181
+ }>;
182
+ }, z.core.$strip>;
183
+ from: z.ZodObject<{
184
+ server: z.ZodString;
185
+ workspace: z.ZodString;
186
+ tab: z.ZodString;
187
+ pane: z.ZodString;
188
+ source: z.ZodEnum<{
189
+ claude: "claude";
190
+ codex: "codex";
191
+ copilot: "copilot";
192
+ opencode: "opencode";
193
+ phren: "phren";
194
+ }>;
195
+ session: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
196
+ }, z.core.$strip>;
197
+ connection: z.ZodObject<{
198
+ name: z.ZodString;
199
+ server: z.ZodString;
200
+ fingerprint: z.ZodString;
201
+ id: z.ZodString;
202
+ }, z.core.$strict>;
203
+ workers: z.ZodOptional<z.ZodArray<z.ZodObject<{
204
+ id: z.ZodString;
205
+ fingerprint: z.ZodOptional<z.ZodString>;
206
+ }, z.core.$strict>>>;
207
+ revoked: z.ZodOptional<z.ZodBoolean>;
208
+ activated: z.ZodOptional<z.ZodBoolean>;
209
+ target: z.ZodOptional<z.ZodObject<{
210
+ server: z.ZodString;
211
+ workspace: z.ZodString;
212
+ tab: z.ZodString;
213
+ pane: z.ZodString;
214
+ source: z.ZodEnum<{
215
+ claude: "claude";
216
+ codex: "codex";
217
+ copilot: "copilot";
218
+ opencode: "opencode";
219
+ phren: "phren";
220
+ }>;
221
+ session: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
222
+ }, z.core.$strip>>;
223
+ resume: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
224
+ }, z.core.$strict>>;
68
225
  }, z.core.$strip>;
69
226
  export type RoleState = z.infer<typeof stateSchema>;
70
227
  /** The saved state; undefined before the file exists. */
71
- export declare function readRoleState(): Promise<RoleState | undefined>;
228
+ export declare function readRoleState(root?: string): Promise<RoleState | undefined>;
229
+ /** Uses the same serialization as every local role writer. */
230
+ export declare function updateConductorAuthority(root: string, change: (state: RoleState) => Promise<RoleState>): Promise<RoleState>;
231
+ export declare function assertRoleMutable(state: RoleState | undefined): void;
72
232
  /** For tests: forget the cached state. */
73
233
  export declare function resetRoleState(): void;
74
234
  /** A pane running an agent the Hook can talk to. */
@@ -78,7 +238,7 @@ export declare const runsAgent: (pane: Json | undefined) => pane is Json;
78
238
  * agent runs there right now. A recorded pane gone from the snapshot ends the
79
239
  * role. In legacy mode a live pane with a conductor name is adopted and saved.
80
240
  */
81
- export declare function conductorPane(server: string, s: Json): Promise<Json | undefined>;
241
+ export declare function conductorPane(server: string, s: Json, root?: string): Promise<Json | undefined>;
82
242
  /** The recorded conductor, whatever its server; undefined in legacy mode or with none. */
83
243
  export declare function recordedConductor(): Promise<ConductorRecord | undefined>;
84
244
  /** Makes `pane` on `server` this computer's conductor, replacing any record. */
@@ -3,7 +3,7 @@ import path from "node:path";
3
3
  import { z } from "zod";
4
4
  import { conductorOriginChanged } from "./dispatch-origins.js";
5
5
  import { isConductorName, paneAgentName } from "./herdr.js";
6
- import { atomicInPrivateDir, BridgeError, bridgeRoot, id, objects, provider, serverName } from "./protocol.js";
6
+ import { atomicInPrivateDir, BridgeError, bridgeRoot, id, objects, provider, serverName, targetSchema } from "./protocol.js";
7
7
  /**
8
8
  * Which pane is this computer's conductor, as the Hook keeps it
9
9
  * (docs/conductor-sets.md). The role follows the pane: server, pane id and
@@ -21,15 +21,23 @@ const recordSchema = z.object({
21
21
  const setNameSchema = z.object({ name: z.string().min(1).max(60).nullable(), namedAt: z.string().datetime() });
22
22
  /** `conductor` absent is legacy mode: nothing has decided the role yet, so a
23
23
  * conductor is still recognized by its mux name. `null` is no conductor. */
24
- const stateSchema = z.object({ version: z.literal(1), conductor: recordSchema.nullable().optional(), set: setNameSchema.optional() });
25
- const roleFile = () => path.join(bridgeRoot(), "conductor-role.json");
24
+ export const successionSchema = z.object({
25
+ id: z.string().uuid(), generation: z.string().uuid(), side: z.enum(["origin", "successor"]),
26
+ phase: z.enum(["preparing", "prepared", "committed", "aborted"]),
27
+ originId: z.string().uuid(), destinationId: z.string().uuid(), previous: recordSchema, from: targetSchema,
28
+ connection: z.object({ name: serverName, server: serverName, fingerprint: z.string().regex(/^[a-f0-9]{64}$/), id: z.string().uuid() }).strict(),
29
+ workers: z.array(z.object({ id: z.string().uuid(), fingerprint: z.string().regex(/^[a-f0-9]{64}$/).optional() }).strict()).optional(),
30
+ revoked: z.boolean().optional(), activated: z.boolean().optional(), target: targetSchema.optional(), resume: z.record(z.string(), z.unknown()).optional(),
31
+ }).strict();
32
+ const stateSchema = z.object({ version: z.literal(1), conductor: recordSchema.nullable().optional(), set: setNameSchema.optional(), succession: successionSchema.optional() });
33
+ const roleFile = (root = bridgeRoot()) => path.join(root, "conductor-role.json");
26
34
  /** The Hook is the only writer, so the last state it read or wrote stands in for the file. */
27
- let cached;
35
+ const cached = new Map();
28
36
  /** The saved state; undefined before the file exists. */
29
- export async function readRoleState() {
30
- const file = roleFile();
31
- if (cached?.file === file)
32
- return cached.state;
37
+ export async function readRoleState(root = bridgeRoot()) {
38
+ const file = roleFile(root);
39
+ if (cached.has(file))
40
+ return cached.get(file);
33
41
  // Read once per process and synchronously: the overview's time budget
34
42
  // should not wait on disk for a file of a few hundred bytes.
35
43
  let text;
@@ -51,26 +59,39 @@ export async function readRoleState() {
51
59
  state = { version: 1, conductor: null };
52
60
  }
53
61
  }
54
- cached = { file, state };
62
+ cached.set(file, state);
55
63
  return state;
56
64
  }
57
- async function writeRoleState(state) {
58
- const file = roleFile();
65
+ async function writeRoleState(state, root = bridgeRoot()) {
66
+ const file = roleFile(root);
59
67
  await atomicInPrivateDir(file, JSON.stringify(state, null, 2) + "\n");
60
- cached = { file, state };
68
+ cached.set(file, state);
61
69
  conductorOriginChanged(state.conductor);
62
70
  }
63
71
  /** Every read-modify-write of the state runs one at a time: an overview poll
64
72
  * noting a moved pane must not interleave with a make or stop and bring back
65
73
  * the record it replaced. */
66
- let queue = Promise.resolve();
67
- function serialized(run) {
74
+ const queues = new Map();
75
+ function serialized(run, root = bridgeRoot()) {
76
+ const queue = queues.get(root) ?? Promise.resolve();
68
77
  const next = queue.then(run, run);
69
- queue = next.catch(() => undefined);
78
+ queues.set(root, next.catch(() => undefined));
70
79
  return next;
71
80
  }
81
+ /** Uses the same serialization as every local role writer. */
82
+ export function updateConductorAuthority(root, change) {
83
+ return serialized(async () => {
84
+ const state = await change(await readRoleState(root) ?? { version: 1 });
85
+ await writeRoleState(state, root);
86
+ return state;
87
+ }, root);
88
+ }
89
+ export function assertRoleMutable(state) {
90
+ if (state?.succession && state.succession.phase !== "aborted")
91
+ throw new BridgeError(409, "The conductor is moving or delegated to another computer; reconcile its ownership before changing the role.");
92
+ }
72
93
  /** For tests: forget the cached state. */
73
- export function resetRoleState() { cached = undefined; }
94
+ export function resetRoleState() { cached.clear(); }
74
95
  const liveStatus = (pane) => !["completed", "exited", "failed", "stopped"].includes(String(pane.agent_status));
75
96
  /** A pane running an agent the Hook can talk to. */
76
97
  export const runsAgent = (pane) => !!pane && provider.safeParse(pane.agent).success && liveStatus(pane);
@@ -103,14 +124,19 @@ function recordedPane(record, s) {
103
124
  * agent runs there right now. A recorded pane gone from the snapshot ends the
104
125
  * role. In legacy mode a live pane with a conductor name is adopted and saved.
105
126
  */
106
- export function conductorPane(server, s) {
127
+ export function conductorPane(server, s, root = bridgeRoot()) {
128
+ const write = (state) => writeRoleState(state, root);
107
129
  return serialized(async () => {
108
- const state = await readRoleState();
130
+ const state = await readRoleState(root);
131
+ if (state?.succession?.side === "origin" && state.succession.phase === "committed")
132
+ return undefined;
133
+ if (state?.succession?.side === "successor" && ["preparing", "prepared"].includes(state.succession.phase))
134
+ return undefined;
109
135
  if (state?.conductor === undefined) {
110
136
  const named = objects(s.panes).find(pane => isConductorName(paneAgentName(s, pane)) && runsAgent(pane));
111
137
  if (!named)
112
138
  return undefined;
113
- await writeRoleState({ ...state, version: 1, conductor: recordFor(server, named, "migrated") });
139
+ await write({ ...state, version: 1, conductor: recordFor(server, named, "migrated") });
114
140
  return named;
115
141
  }
116
142
  const record = state.conductor;
@@ -121,21 +147,23 @@ export function conductorPane(server, s) {
121
147
  // The pane went away or was recreated (a moved tab, a Herdr restart): the
122
148
  // role follows the session, so a pane running it takes the role over.
123
149
  const adopted = record.session ? sessionPane(record.session, s) : undefined;
150
+ if (!adopted && state.succession && state.succession.phase !== "aborted")
151
+ return undefined;
124
152
  if (!adopted) {
125
- await writeRoleState({ ...state, conductor: null });
153
+ await write({ ...state, conductor: null });
126
154
  return undefined;
127
155
  }
128
- await writeRoleState({ ...state, conductor: { ...recordFor(server, adopted, record.by, record.session), since: record.since } });
156
+ await write({ ...state, conductor: { ...recordFor(server, adopted, record.by, record.session), since: record.since } });
129
157
  return adopted;
130
158
  }
131
159
  // Keep the place current: a pane moved to another tab or workspace is the same pane.
132
160
  const moved = (id.safeParse(pane.workspace_id).success && pane.workspace_id !== record.workspace) || (id.safeParse(pane.tab_id).success && pane.tab_id !== record.tab)
133
161
  || (provider.safeParse(pane.agent).success && pane.agent !== record.source);
134
162
  if (moved)
135
- await writeRoleState({ ...state, conductor: { ...record, workspace: String(pane.workspace_id), tab: String(pane.tab_id),
163
+ await write({ ...state, conductor: { ...record, workspace: String(pane.workspace_id), tab: String(pane.tab_id),
136
164
  ...(provider.safeParse(pane.agent).success ? { source: pane.agent } : {}) } });
137
165
  return pane;
138
- });
166
+ }, root);
139
167
  }
140
168
  /** The recorded conductor, whatever its server; undefined in legacy mode or with none. */
141
169
  export async function recordedConductor() {
@@ -145,6 +173,7 @@ export async function recordedConductor() {
145
173
  export function recordConductor(server, pane, by, session) {
146
174
  return serialized(async () => {
147
175
  const state = await readRoleState() ?? { version: 1 };
176
+ assertRoleMutable(state);
148
177
  const record = recordFor(server, pane, by, session);
149
178
  await writeRoleState({ ...state, conductor: record });
150
179
  return record;
@@ -153,10 +182,13 @@ export function recordConductor(server, pane, by, session) {
153
182
  /** Move only the captured role. The optional hand-over holds the receipt
154
183
  * writer's queue while preparing routing and committing this role; it must
155
184
  * roll routing back if commit fails. No role writer can interleave here. */
185
+ // This CAS covers local targets. ConductorSuccessionService owns remote
186
+ // generations while keeping the receipts and grants on their original Hook.
156
187
  export function transferConductor(expected, server, pane, session, handOver = commit => commit()) {
157
188
  return serialized(async () => {
158
189
  const state = await readRoleState();
159
190
  const current = state?.conductor;
191
+ assertRoleMutable(state);
160
192
  // Include the generation (since), terminal and session, so a stop/make
161
193
  // or another move cannot be overwritten even if it used the same pane.
162
194
  if (!current || !recordSchema.keyof().options.every(field => current[field] === expected[field])) {
@@ -182,6 +214,7 @@ export function clearConductor(pane) {
182
214
  return serialized(async () => {
183
215
  const state = await readRoleState();
184
216
  const record = state?.conductor ?? undefined;
217
+ assertRoleMutable(state);
185
218
  if (record && pane !== undefined && record.pane !== pane)
186
219
  return undefined;
187
220
  // Written even with nothing to clear: a stop also ends legacy mode, so a
@@ -0,0 +1,100 @@
1
+ import type { PeerIdentity } from "./request-origin.js";
2
+ import type { OriginPane } from "./dispatch.js";
3
+ import { z } from "zod";
4
+ import { type ConductorRecord, type ConductorSuccession } from "./conductor-role.js";
5
+ import { peerRequest, type HookPeer } from "./peers.js";
6
+ import { type DispatchHost } from "./dispatch-hosts.js";
7
+ import { type Json, type Target } from "./protocol.js";
8
+ declare const actions: z.ZodEnum<{
9
+ approve: "approve";
10
+ dispatch: "dispatch";
11
+ "grants-add": "grants-add";
12
+ "grants-list": "grants-list";
13
+ "grants-remove": "grants-remove";
14
+ hand_off: "hand_off";
15
+ returns: "returns";
16
+ }>;
17
+ type Action = z.infer<typeof actions>;
18
+ export type ConductorExecutor = (action: Action, data: Json, origin: OriginPane, remote?: boolean) => Promise<Json>;
19
+ interface Options {
20
+ root: string;
21
+ computer: {
22
+ id: string;
23
+ name: string;
24
+ };
25
+ peers?: () => Promise<HookPeer[]>;
26
+ request?: typeof peerRequest;
27
+ validate: (target: Target) => Promise<Json>;
28
+ isSuccessor?: (origin: {
29
+ server: string;
30
+ pane: string;
31
+ }, id: string) => Promise<boolean>;
32
+ snapshot: (server: string) => Promise<Json>;
33
+ deliver: (target: Target, text: string, deliveryId: string) => Promise<Json>;
34
+ /** All existing worker computers must be reachable before reserving a move. */
35
+ checkWorkers: (from: Target) => Promise<void>;
36
+ }
37
+ /** Check the original Hook's actual receipts over its own pinned directory,
38
+ * before any role reservation, hand-off or successor launch. */
39
+ export declare function preflightConductorWorkers(from: Target, computerId: string, peers?: () => Promise<HookPeer[]>, request?: typeof peerRequest): Promise<void>;
40
+ /** A owns the generation and every receipt/approval/grant. B holds only a
41
+ * delegated pane and operation outbox. No login or bearer credential crosses
42
+ * Hooks. Peer writes are authenticated by fetching their intent back over
43
+ * our own enrolled, pinned SSH account, rather than trusting a claimed alias. */
44
+ export declare class ConductorSuccessionService {
45
+ private readonly options;
46
+ private readonly peers;
47
+ private readonly request;
48
+ private readonly reservedCallers;
49
+ private readonly operations;
50
+ constructor(options: Options);
51
+ /** Synchronous admission also pauses conductor calls during preflight. */
52
+ reserveCaller(target: {
53
+ server: string;
54
+ pane: string;
55
+ }): () => void;
56
+ private assertCallerAvailable;
57
+ private file;
58
+ private save;
59
+ status(id: string): Promise<ConductorSuccession>;
60
+ /** Identity is supplied only by the scoped SSH gateway, never the body. */
61
+ authorize(id: string, caller: PeerIdentity | undefined, preparingOrigin?: string): Promise<void>;
62
+ private workerIdentities;
63
+ private connection;
64
+ private change;
65
+ begin(id: string, expected: ConductorRecord, from: Target, destination: DispatchHost, computerId: string, resume?: Json): Promise<ConductorSuccession>;
66
+ ensurePrepared(id: string): Promise<void>;
67
+ prepare(input: unknown): Promise<Json>;
68
+ /** The prepared successor pulls the canonical launch over its own pin.
69
+ * An unrelated enrolled peer cannot pre-empt a known move id with a brief. */
70
+ saveLaunch(id: string, input: Json): Promise<void>;
71
+ launchIntent(id: string): Promise<Json>;
72
+ verifiedLaunch(input: Json): Promise<Json>;
73
+ prepared(id: string, target: Target): Promise<void>;
74
+ commit(id: string): Promise<ConductorSuccession>;
75
+ private transition;
76
+ activate(input: unknown): Promise<Json>;
77
+ private activateOnce;
78
+ finish(id: string): Promise<void>;
79
+ private finishOnce;
80
+ /** Explicit owner revocation on A ends delegation without restoring the
81
+ * old chat. This is distinct from rolling back an uncertain commit. */
82
+ stopOrigin(pane?: unknown): Promise<Json | undefined>;
83
+ abort(id: string): Promise<void>;
84
+ call(action: Action, data: Json, origin: unknown, execute: () => Promise<Json>): Promise<Json>;
85
+ private identifyComputer;
86
+ private resolveComputer;
87
+ /** Automatic failover has no authority from the fenced old pane. Its
88
+ * generation is checked against the live successor before executing at A. */
89
+ automatic(action: Action, data: Json, origin: unknown, execute: () => Promise<Json>): Promise<Json>;
90
+ outgoing(id: string, operationId: string): Promise<Json>;
91
+ operate(input: unknown, execute: ConductorExecutor): Promise<Json>;
92
+ acknowledge(input: unknown, acknowledge: (rows: Json[]) => Promise<void>): Promise<Json>;
93
+ forward(origin: unknown, text: string, deliveryId: string): Promise<{
94
+ delivered: boolean;
95
+ } | undefined>;
96
+ notice(input: unknown): Promise<Json>;
97
+ notification(id: string, deliveryId: string): Promise<Json>;
98
+ reconcile(): Promise<void>;
99
+ }
100
+ export {};