@mycadet/cli 0.13.0-dev.202610231952.fa65022 → 0.13.0-dev.202610241003.f9cbe80

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 (87) hide show
  1. package/node_modules/@mycadet/local-mode/src/__tests__/status.test.ts +0 -4
  2. package/node_modules/@mycadet/local-mode/src/index.ts +6 -2
  3. package/node_modules/@mycadet/local-mode/src/lockfile-contract.test.ts +0 -3
  4. package/node_modules/@mycadet/local-mode/src/lockfile-contract.ts +0 -2
  5. package/node_modules/@mycadet/local-mode/src/lockfile.test.ts +0 -31
  6. package/node_modules/@mycadet/local-mode/src/lockfile.ts +28 -48
  7. package/package.json +1 -1
  8. package/src/__tests__/app-command.test.ts +2 -2
  9. package/src/__tests__/assistant-client-cloud-auth.test.ts +2 -2
  10. package/src/__tests__/assistant-client-refresh.test.ts +2 -2
  11. package/src/__tests__/assistant-config.test.ts +28 -27
  12. package/src/__tests__/backup-ops.test.ts +4 -3
  13. package/src/__tests__/backup.test.ts +2 -2
  14. package/src/__tests__/client-tui-refresh.test.ts +3 -3
  15. package/src/__tests__/connect-import.test.ts +4 -52
  16. package/src/__tests__/debug.test.ts +1 -1
  17. package/src/__tests__/devices.test.ts +5 -6
  18. package/src/__tests__/gateway-token.test.ts +3 -3
  19. package/src/__tests__/helpers/lockfile-entry.ts +37 -0
  20. package/src/__tests__/host-teleport-docker.test.ts +2 -2
  21. package/src/__tests__/host-teleport.test.ts +15 -15
  22. package/src/__tests__/local-runtime-version.test.ts +4 -2
  23. package/src/__tests__/multi-local.test.ts +14 -25
  24. package/src/__tests__/nginx-ingress.test.ts +73 -5
  25. package/src/__tests__/orphan-detection.test.ts +13 -12
  26. package/src/__tests__/ps-cloud-status.test.ts +9 -9
  27. package/src/__tests__/restore.test.ts +32 -28
  28. package/src/__tests__/retire-local.test.ts +25 -29
  29. package/src/__tests__/retire.test.ts +33 -32
  30. package/src/__tests__/root-backup-docker.test.ts +2 -2
  31. package/src/__tests__/root-backup.test.ts +2 -3
  32. package/src/__tests__/root-restore-command.test.ts +2 -2
  33. package/src/__tests__/setup.test.ts +2 -5
  34. package/src/__tests__/signing-key-continuity.test.ts +2 -93
  35. package/src/__tests__/sleep.test.ts +13 -6
  36. package/src/__tests__/teleport-backup.test.ts +8 -2
  37. package/src/__tests__/teleport.test.ts +1 -1
  38. package/src/__tests__/tui-midsession-refresh.test.ts +4 -23
  39. package/src/__tests__/tunnel-stop.test.ts +2 -3
  40. package/src/__tests__/tunnel.test.ts +27 -16
  41. package/src/__tests__/uninstall.test.ts +31 -28
  42. package/src/__tests__/upgrade-local.test.ts +29 -15
  43. package/src/__tests__/upgrade-root-recovery.test.ts +2 -2
  44. package/src/__tests__/use.test.ts +16 -24
  45. package/src/__tests__/wake-error.test.ts +0 -1
  46. package/src/__tests__/wake.test.ts +22 -24
  47. package/src/commands/client.ts +5 -5
  48. package/src/commands/completions.test.ts +2 -2
  49. package/src/commands/debug.ts +13 -5
  50. package/src/commands/devices.ts +5 -5
  51. package/src/commands/gateway/token.ts +4 -4
  52. package/src/commands/hatch.ts +2 -2
  53. package/src/commands/login.ts +2 -2
  54. package/src/commands/logs.ts +4 -4
  55. package/src/commands/pair.ts +5 -5
  56. package/src/commands/ps.ts +23 -17
  57. package/src/commands/restore.ts +32 -20
  58. package/src/commands/retire.ts +6 -6
  59. package/src/commands/sleep.ts +117 -96
  60. package/src/commands/uninstall.ts +6 -4
  61. package/src/commands/upgrade.ts +200 -140
  62. package/src/commands/wake.ts +93 -93
  63. package/src/lib/__tests__/local-gateway-cli.test.ts +3 -3
  64. package/src/lib/__tests__/runtime-url.test.ts +1 -15
  65. package/src/lib/assistant-client.ts +5 -2
  66. package/src/lib/assistant-config.ts +43 -81
  67. package/src/lib/cloud-login.ts +12 -6
  68. package/src/lib/constants.ts +0 -1
  69. package/src/lib/docker.ts +11 -11
  70. package/src/lib/exec-apple-container.ts +2 -2
  71. package/src/lib/hatch-local.ts +12 -6
  72. package/src/lib/health-check.ts +123 -109
  73. package/src/lib/host-teleport.ts +31 -23
  74. package/src/lib/ingress-config.ts +2 -2
  75. package/src/lib/live-voice/connection.ts +2 -2
  76. package/src/lib/local.ts +76 -48
  77. package/src/lib/nginx-ingress.ts +41 -10
  78. package/src/lib/orphan-detection.ts +4 -3
  79. package/src/lib/retire-apple-container.ts +2 -2
  80. package/src/lib/retire-local.ts +11 -5
  81. package/src/lib/root-backup.ts +35 -21
  82. package/src/lib/runtime-url.ts +4 -4
  83. package/src/lib/ssh-apple-container.ts +2 -2
  84. package/src/lib/sync-cloud-assistants.ts +5 -5
  85. package/src/lib/teleport-backup.ts +15 -13
  86. package/src/lib/tunnel.ts +6 -6
  87. package/src/lib/upgrade-lifecycle.ts +36 -30
package/src/lib/docker.ts CHANGED
@@ -15,10 +15,10 @@ import cliPkg from "../../package.json";
15
15
 
16
16
  import {
17
17
  findAssistantByName,
18
- saveAssistantEntry,
18
+ saveLockfileAssistant,
19
19
  setActiveAssistant,
20
20
  } from "./assistant-config";
21
- import type { AssistantEntry } from "./assistant-config";
21
+ import type { LockfileAssistant } from "./assistant-config";
22
22
  import { buildHatchConfigValues, writeInitialConfig } from "./config-utils";
23
23
  import { printInstanceDetails } from "./instance-details";
24
24
  import { buildServiceRunArgs } from "./statefulset.js";
@@ -937,7 +937,7 @@ export function isNoSuchContainerError(err: unknown): boolean {
937
937
  * generate). Empty volumes just get fresh state on first boot.
938
938
  */
939
939
  export async function recreateDockerContainers(
940
- entry: AssistantEntry,
940
+ entry: LockfileAssistant,
941
941
  ): Promise<void> {
942
942
  const info = entry.containerInfo;
943
943
  if (!info?.assistantImage || !info.gatewayImage || !info.cesImage) {
@@ -981,7 +981,7 @@ export async function recreateDockerContainers(
981
981
  }
982
982
 
983
983
  const gatewayPort =
984
- parseGatewayPort(entry.runtimeUrl) ??
984
+ parseGatewayPort(entry.runtimeUrl ?? "") ??
985
985
  getDefaultPorts(getCurrentEnvironment()).gateway;
986
986
  const assistantPort = info.assistantPort ?? ASSISTANT_INTERNAL_PORT;
987
987
  const device = getOrCreateHostDeviceId();
@@ -1006,7 +1006,7 @@ export async function recreateDockerContainers(
1006
1006
  // Persist what the recreation decided (the gateway port in the runtime
1007
1007
  // url, the assistant port when it defaulted) so plain `docker start`
1008
1008
  // wakes work and clients reach the right endpoints.
1009
- saveAssistantEntry({
1009
+ saveLockfileAssistant({
1010
1010
  ...entry,
1011
1011
  runtimeUrl: `http://localhost:${gatewayPort}`,
1012
1012
  containerInfo: { ...info, assistantPort },
@@ -1699,7 +1699,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
1699
1699
  CADET_DEVICE_ID: hostDeviceId,
1700
1700
  };
1701
1701
  const runtimeUrl = `http://localhost:${gatewayPort}`;
1702
- const dockerEntry: AssistantEntry = {
1702
+ const dockerEntry: LockfileAssistant = {
1703
1703
  assistantId: instanceName,
1704
1704
  runtimeUrl,
1705
1705
  cloud: "docker",
@@ -1713,7 +1713,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
1713
1713
  },
1714
1714
  };
1715
1715
  if (params.initialArchive) {
1716
- saveAssistantEntry(dockerEntry);
1716
+ saveLockfileAssistant(dockerEntry);
1717
1717
  }
1718
1718
  await startContainers(
1719
1719
  {
@@ -1736,7 +1736,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
1736
1736
  const containersUpAt = Date.now();
1737
1737
 
1738
1738
  emitProgress(5, 6, "Saving configuration...");
1739
- saveAssistantEntry(dockerEntry);
1739
+ saveLockfileAssistant(dockerEntry);
1740
1740
  setActiveAssistant(instanceName);
1741
1741
 
1742
1742
  if (params.initialArchive) {
@@ -1813,7 +1813,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
1813
1813
  }
1814
1814
 
1815
1815
  if (watch && repoRoot) {
1816
- saveAssistantEntry({ ...dockerEntry, watcherPid: process.pid });
1816
+ saveLockfileAssistant({ ...dockerEntry, watcherPid: process.pid });
1817
1817
 
1818
1818
  const stopWatcher = startFileWatcher({
1819
1819
  signingKey,
@@ -1836,7 +1836,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
1836
1836
  log("\n🛑 Shutting down...");
1837
1837
  stopWatcher();
1838
1838
  await stopContainers(res);
1839
- saveAssistantEntry({ ...dockerEntry, watcherPid: undefined });
1839
+ saveLockfileAssistant({ ...dockerEntry, watcherPid: undefined });
1840
1840
  log("✅ Docker instance stopped.");
1841
1841
  resolve();
1842
1842
  };
@@ -1849,7 +1849,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
1849
1849
  // file watchers and let the process terminate.
1850
1850
  process.on("SIGTERM", () => {
1851
1851
  stopWatcher();
1852
- saveAssistantEntry({ ...dockerEntry, watcherPid: undefined });
1852
+ saveLockfileAssistant({ ...dockerEntry, watcherPid: undefined });
1853
1853
  resolve();
1854
1854
  });
1855
1855
  });
@@ -1,7 +1,7 @@
1
1
  import { createConnection } from "net";
2
2
  import { existsSync } from "fs";
3
3
 
4
- import type { AssistantEntry } from "./assistant-config";
4
+ import type { LockfileAssistant } from "./assistant-config";
5
5
 
6
6
  /**
7
7
  * Execute a command inside an Apple Container assistant via the management
@@ -9,7 +9,7 @@ import type { AssistantEntry } from "./assistant-config";
9
9
  * terminal, and exits with the appropriate code.
10
10
  */
11
11
  export async function execAppleContainer(
12
- entry: AssistantEntry,
12
+ entry: LockfileAssistant,
13
13
  command: string[],
14
14
  service: string,
15
15
  ): Promise<void> {
@@ -18,10 +18,11 @@ import cliPkg from "../../package.json";
18
18
  import {
19
19
  allocateLocalResources,
20
20
  findAssistantByName,
21
- saveAssistantEntry,
21
+ getLocalInstanceDir,
22
+ saveLockfileAssistant,
22
23
  setActiveAssistant,
23
24
  } from "./assistant-config.js";
24
- import type { AssistantEntry } from "./assistant-config.js";
25
+ import type { LockfileAssistant } from "./assistant-config.js";
25
26
  import { green, yellow } from "./color.js";
26
27
  import { buildHatchConfigValues, writeInitialConfig } from "./config-utils.js";
27
28
  import {
@@ -218,7 +219,12 @@ export async function hatchLocal(
218
219
 
219
220
  const resources = await allocateLocalResources(instanceName);
220
221
 
221
- const logsDir = join(resources.instanceDir, "workspace", "data", "logs");
222
+ const logsDir = join(
223
+ getLocalInstanceDir(resources),
224
+ "workspace",
225
+ "data",
226
+ "logs",
227
+ );
222
228
  archiveLogFile("hatch.log", logsDir);
223
229
  resetLogFile("hatch.log");
224
230
 
@@ -304,7 +310,7 @@ export async function hatchLocal(
304
310
  params.initialArchive,
305
311
  )
306
312
  : generateLocalSigningKey();
307
- persistRootSigningKey(resources.instanceDir, signingKey);
313
+ persistRootSigningKey(getLocalInstanceDir(resources), signingKey);
308
314
  const bootstrapSecret = generateLocalSigningKey();
309
315
  let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
310
316
  try {
@@ -343,7 +349,7 @@ export async function hatchLocal(
343
349
  }
344
350
 
345
351
  const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
346
- const localEntry: AssistantEntry = {
352
+ const localEntry: LockfileAssistant = {
347
353
  assistantId: instanceName,
348
354
  runtimeUrl,
349
355
  cloud: "local",
@@ -353,7 +359,7 @@ export async function hatchLocal(
353
359
  };
354
360
 
355
361
  reporter.progress(5, 6, "Saving configuration...");
356
- saveAssistantEntry(localEntry);
362
+ saveLockfileAssistant(localEntry);
357
363
  setActiveAssistant(instanceName);
358
364
 
359
365
  return { resources, runtimeUrl, loopbackUrl, bootstrapSecret };
@@ -1,4 +1,5 @@
1
1
  import { loopbackSafeFetch } from "./loopback-fetch.js";
2
+ import type { LockfileAssistant } from "./assistant-config.js";
2
3
  import { z } from "zod";
3
4
 
4
5
  const HealthResponseSchema = z.object({
@@ -15,67 +16,6 @@ export interface HealthCheckResult {
15
16
  version?: string;
16
17
  }
17
18
 
18
- export async function checkManagedHealth(
19
- runtimeUrl: string,
20
- assistantId: string,
21
- ): Promise<HealthCheckResult> {
22
- const { readCloudToken } = await import("./cloud-client.js");
23
- const token = readCloudToken();
24
- if (!token) {
25
- return {
26
- status: "error (auth)",
27
- detail: "not logged in — run `cadet login`",
28
- };
29
- }
30
-
31
- let headers: Record<string, string>;
32
- try {
33
- const { authHeaders } = await import("./cloud-client.js");
34
- headers = await authHeaders(token, runtimeUrl);
35
- } catch (err) {
36
- return {
37
- status: "error (auth)",
38
- detail: err instanceof Error ? err.message : "org lookup failed",
39
- };
40
- }
41
-
42
- try {
43
- const url = `${runtimeUrl}/v1/assistants/${encodeURIComponent(assistantId)}/healthz/`;
44
- const controller = new AbortController();
45
- const timeoutId = setTimeout(
46
- () => controller.abort(),
47
- HEALTH_CHECK_TIMEOUT_MS,
48
- );
49
-
50
- const response = await loopbackSafeFetch(url, {
51
- signal: controller.signal,
52
- headers,
53
- });
54
-
55
- clearTimeout(timeoutId);
56
-
57
- if (!response.ok) {
58
- return { status: `error (${response.status})`, detail: null };
59
- }
60
-
61
- const data = HealthResponseSchema
62
- .catch({})
63
- .parse(await response.json());
64
- const status = data.status || "unknown";
65
- return {
66
- status,
67
- detail: status !== "healthy" ? (data.message ?? null) : null,
68
- version: data.version,
69
- };
70
- } catch (error) {
71
- const status =
72
- error instanceof Error && error.name === "AbortError"
73
- ? "timeout"
74
- : "unreachable";
75
- return { status, detail: null };
76
- }
77
- }
78
-
79
19
  export interface ManagedProcessEntry {
80
20
  name: string;
81
21
  status: "running" | "not_running" | "unreachable";
@@ -126,51 +66,6 @@ export async function fetchGatewayPs(
126
66
  }
127
67
  }
128
68
 
129
- export async function fetchManagedPs(
130
- runtimeUrl: string,
131
- assistantId: string,
132
- ): Promise<ManagedPsResponse | null> {
133
- const { readCloudToken, authHeaders } =
134
- await import("./cloud-client.js");
135
- const token = readCloudToken();
136
- if (!token) return null;
137
-
138
- let headers: Record<string, string>;
139
- try {
140
- headers = await authHeaders(token, runtimeUrl);
141
- } catch {
142
- return null;
143
- }
144
-
145
- // Try the /ps endpoint first; fall back to legacy /connection-status
146
- // for platform versions that haven't rolled it out yet.
147
- try {
148
- const psUrl = `${runtimeUrl}/v1/assistants/${encodeURIComponent(assistantId)}/ps/`;
149
- const controller = new AbortController();
150
- const timeoutId = setTimeout(() => controller.abort(), 5000);
151
-
152
- const response = await loopbackSafeFetch(psUrl, {
153
- signal: controller.signal,
154
- headers,
155
- });
156
-
157
- clearTimeout(timeoutId);
158
-
159
- if (response.ok) {
160
- return (await response.json()) as ManagedPsResponse;
161
- }
162
-
163
- // /ps not available — fall back to legacy connection-status
164
- if (response.status === 404 || response.status === 405) {
165
- return fetchLegacyConnectionStatus(runtimeUrl, assistantId, headers);
166
- }
167
-
168
- return null;
169
- } catch {
170
- return null;
171
- }
172
- }
173
-
174
69
  const LegacyConnectionStatusSchema = z.object({
175
70
  state: z.string(),
176
71
  is_awake: z.boolean(),
@@ -247,9 +142,128 @@ export async function checkHealth(
247
142
  return { status: `error (${response.status})`, detail: null };
248
143
  }
249
144
 
250
- const data = HealthResponseSchema
251
- .catch({})
252
- .parse(await response.json());
145
+ const data = HealthResponseSchema.catch({}).parse(await response.json());
146
+ const status = data.status || "unknown";
147
+ return {
148
+ status,
149
+ detail: status !== "healthy" ? (data.message ?? null) : null,
150
+ version: data.version,
151
+ };
152
+ } catch (error) {
153
+ const status =
154
+ error instanceof Error && error.name === "AbortError"
155
+ ? "timeout"
156
+ : "unreachable";
157
+ return { status, detail: null };
158
+ }
159
+ }
160
+
161
+ /**
162
+ * Cadet Cloud process listing for an entry, tolerating a missing recorded
163
+ * gateway URL (cloud entries may never have one).
164
+ */
165
+ export async function fetchCloudPs(
166
+ entry: LockfileAssistant,
167
+ ): Promise<ManagedPsResponse | null> {
168
+ if (!entry.runtimeUrl) return null;
169
+ const runtimeUrl = entry.runtimeUrl;
170
+
171
+ const { readCloudToken, authHeaders } = await import("./cloud-client.js");
172
+ const token = readCloudToken();
173
+ if (!token) return null;
174
+
175
+ let headers: Record<string, string>;
176
+ try {
177
+ headers = await authHeaders(token, runtimeUrl);
178
+ } catch {
179
+ return null;
180
+ }
181
+
182
+ // Try the /ps endpoint first; fall back to legacy /connection-status
183
+ // for platform versions that haven't rolled it out yet.
184
+ try {
185
+ const psUrl = `${runtimeUrl}/v1/assistants/${encodeURIComponent(entry.assistantId)}/ps/`;
186
+ const controller = new AbortController();
187
+ const timeoutId = setTimeout(() => controller.abort(), 5000);
188
+
189
+ const response = await loopbackSafeFetch(psUrl, {
190
+ signal: controller.signal,
191
+ headers,
192
+ });
193
+
194
+ clearTimeout(timeoutId);
195
+
196
+ if (response.ok) {
197
+ return (await response.json()) as ManagedPsResponse;
198
+ }
199
+
200
+ // /ps not available — fall back to legacy connection-status
201
+ if (response.status === 404 || response.status === 405) {
202
+ return fetchLegacyConnectionStatus(
203
+ runtimeUrl,
204
+ entry.assistantId,
205
+ headers,
206
+ );
207
+ }
208
+
209
+ return null;
210
+ } catch {
211
+ return null;
212
+ }
213
+ }
214
+
215
+ /**
216
+ * Cadet Cloud health for an entry, tolerating a missing recorded gateway URL
217
+ * (cloud entries may never have one).
218
+ */
219
+ export async function checkCloudHealth(
220
+ entry: LockfileAssistant,
221
+ ): Promise<HealthCheckResult> {
222
+ if (!entry.runtimeUrl) {
223
+ return { status: "unknown", detail: "no runtime URL" };
224
+ }
225
+ const runtimeUrl = entry.runtimeUrl;
226
+
227
+ const { readCloudToken } = await import("./cloud-client.js");
228
+ const token = readCloudToken();
229
+ if (!token) {
230
+ return {
231
+ status: "error (auth)",
232
+ detail: "not logged in — run `cadet login`",
233
+ };
234
+ }
235
+
236
+ let headers: Record<string, string>;
237
+ try {
238
+ const { authHeaders } = await import("./cloud-client.js");
239
+ headers = await authHeaders(token, runtimeUrl);
240
+ } catch (err) {
241
+ return {
242
+ status: "error (auth)",
243
+ detail: err instanceof Error ? err.message : "org lookup failed",
244
+ };
245
+ }
246
+
247
+ try {
248
+ const url = `${runtimeUrl}/v1/assistants/${encodeURIComponent(entry.assistantId)}/healthz/`;
249
+ const controller = new AbortController();
250
+ const timeoutId = setTimeout(
251
+ () => controller.abort(),
252
+ HEALTH_CHECK_TIMEOUT_MS,
253
+ );
254
+
255
+ const response = await loopbackSafeFetch(url, {
256
+ signal: controller.signal,
257
+ headers,
258
+ });
259
+
260
+ clearTimeout(timeoutId);
261
+
262
+ if (!response.ok) {
263
+ return { status: `error (${response.status})`, detail: null };
264
+ }
265
+
266
+ const data = HealthResponseSchema.catch({}).parse(await response.json());
253
267
  const status = data.status || "unknown";
254
268
  return {
255
269
  status,
@@ -1,10 +1,10 @@
1
1
  import { rm } from "node:fs/promises";
2
2
  import { z } from "zod";
3
3
  import cliPkg from "../../package.json";
4
- import type { AssistantEntry } from "./assistant-config.js";
4
+ import type { LockfileAssistant } from "./assistant-config.js";
5
5
  import {
6
6
  findAssistantByName,
7
- removeAssistantEntry,
7
+ removeLockfileAssistant,
8
8
  setActiveAssistant,
9
9
  } from "./assistant-config.js";
10
10
  import { createBackup, pruneOldBackups } from "./backup-ops.js";
@@ -40,24 +40,24 @@ type HostEnvironment = "local" | "docker";
40
40
  export class TeleportRecoveryError extends AggregateError {}
41
41
 
42
42
  export interface HostTeleportOps {
43
- storage(entry: AssistantEntry): HostStorage;
44
- sleep(entry: AssistantEntry): Promise<void>;
45
- backup(entry: AssistantEntry): Promise<string>;
46
- version(entry: AssistantEntry): Promise<string | undefined>;
43
+ storage(entry: LockfileAssistant): HostStorage;
44
+ sleep(entry: LockfileAssistant): Promise<void>;
45
+ backup(entry: LockfileAssistant): Promise<string>;
46
+ version(entry: LockfileAssistant): Promise<string | undefined>;
47
47
  hatch(
48
48
  env: HostEnvironment,
49
49
  name: string | undefined,
50
50
  archive: string,
51
- ): Promise<AssistantEntry>;
51
+ ): Promise<LockfileAssistant>;
52
52
  restore(
53
- entry: AssistantEntry,
53
+ entry: LockfileAssistant,
54
54
  archive: string,
55
55
  recovery: string,
56
56
  ): Promise<void>;
57
- retire(entry: AssistantEntry): Promise<void>;
57
+ retire(entry: LockfileAssistant): Promise<void>;
58
58
  }
59
59
 
60
- function storageFor(entry: AssistantEntry): HostStorage {
60
+ function storageFor(entry: LockfileAssistant): HostStorage {
61
61
  return entry.cloud === "docker"
62
62
  ? new DockerRootStorage(entry)
63
63
  : new LocalRootStorage(entry);
@@ -68,9 +68,11 @@ const defaultOps: HostTeleportOps = {
68
68
  sleep: (entry) =>
69
69
  sleepAssistant(entry, { force: false, wait: false, waitMs: null }),
70
70
  backup: async (entry) => {
71
- const archive = await createBackup(entry.runtimeUrl, entry.assistantId, {
72
- prefix: `${entry.assistantId}-pre-teleport`,
73
- });
71
+ const archive = entry.runtimeUrl
72
+ ? await createBackup(entry.runtimeUrl, entry.assistantId, {
73
+ prefix: `${entry.assistantId}-pre-teleport`,
74
+ })
75
+ : undefined;
74
76
  if (!archive) {
75
77
  throw new Error(
76
78
  `Could not capture '${entry.assistantId}'; teleport aborted.`,
@@ -120,16 +122,16 @@ const defaultOps: HostTeleportOps = {
120
122
  } else {
121
123
  await retireLocal(entry.assistantId, entry);
122
124
  }
123
- removeAssistantEntry(entry.assistantId);
125
+ removeLockfileAssistant(entry.assistantId);
124
126
  },
125
127
  };
126
128
 
127
129
  export async function readHostRuntimeVersion(
128
- entry: AssistantEntry,
130
+ entry: LockfileAssistant,
129
131
  ): Promise<string | undefined> {
130
132
  if (entry.cloud !== "docker") {
131
133
  return (
132
- (await fetchCurrentVersion(entry.runtimeUrl)) ??
134
+ (entry.runtimeUrl ? await fetchCurrentVersion(entry.runtimeUrl) : undefined) ??
133
135
  entry.resources?.runtimeVersion
134
136
  );
135
137
  }
@@ -190,7 +192,7 @@ async function startAndCheck(storage: HostStorage): Promise<void> {
190
192
  }
191
193
 
192
194
  export async function teleportHostInstallation(
193
- source: AssistantEntry,
195
+ source: LockfileAssistant,
194
196
  targetEnv: HostEnvironment,
195
197
  targetName: string | undefined,
196
198
  options: { dryRun: boolean; keepSource: boolean },
@@ -208,10 +210,10 @@ export async function teleportHostInstallation(
208
210
  }
209
211
 
210
212
  async function performHostTeleport(
211
- source: AssistantEntry,
213
+ source: LockfileAssistant,
212
214
  targetEnv: HostEnvironment,
213
215
  targetName: string | undefined,
214
- existing: AssistantEntry | null,
216
+ existing: LockfileAssistant | null,
215
217
  options: { dryRun: boolean; keepSource: boolean },
216
218
  ops: HostTeleportOps,
217
219
  ): Promise<void> {
@@ -246,7 +248,7 @@ async function performHostTeleport(
246
248
  );
247
249
  const sourceStorage = ops.storage(source);
248
250
  const sourceWasRunning = await sourceStorage.running();
249
- let target: AssistantEntry | undefined;
251
+ let target: LockfileAssistant | undefined;
250
252
  let ready = false;
251
253
  try {
252
254
  await ops.sleep(source);
@@ -331,7 +333,7 @@ const DockerConfiguration = z.object({
331
333
 
332
334
  /** Recreate standard CLI containers so immutable env cannot override imported identity. */
333
335
  async function dockerReplacementOptions(
334
- entry: AssistantEntry,
336
+ entry: LockfileAssistant,
335
337
  ): Promise<Parameters<typeof startContainers>[0]> {
336
338
  const res = dockerResourceNames(entry.assistantId);
337
339
  const states = new Map<string, z.infer<typeof DockerConfiguration>>();
@@ -410,7 +412,13 @@ async function dockerReplacementOptions(
410
412
  env(res.assistantContainer),
411
413
  env(res.gatewayContainer),
412
414
  );
413
- const gatewayPort = Number(new URL(entry.runtimeUrl).port);
415
+ const gatewayUrl = entry.runtimeUrl;
416
+ if (!gatewayUrl) {
417
+ throw new Error(
418
+ `Docker assistant '${entry.assistantId}' has no recorded gateway URL.`,
419
+ );
420
+ }
421
+ const gatewayPort = Number(new URL(gatewayUrl).port);
414
422
  const assistantPort = entry.containerInfo?.assistantPort;
415
423
  if (!Number.isSafeInteger(gatewayPort) || gatewayPort < 1 || !assistantPort) {
416
424
  throw new Error(
@@ -433,7 +441,7 @@ async function dockerReplacementOptions(
433
441
  }
434
442
 
435
443
  export async function restoreHostTeleportTarget(
436
- entry: AssistantEntry,
444
+ entry: LockfileAssistant,
437
445
  archive: string,
438
446
  recovery: string,
439
447
  ): Promise<void> {
@@ -9,7 +9,7 @@ import {
9
9
  type TunnelRecord,
10
10
  } from "@mycadet/service-contracts/ingress";
11
11
 
12
- import type { AssistantEntry } from "./assistant-config.js";
12
+ import type { LockfileAssistant } from "./assistant-config.js";
13
13
  import { getStateDir } from "./environments/paths.js";
14
14
  import { getCurrentEnvironment } from "./environments/resolve.js";
15
15
 
@@ -22,7 +22,7 @@ import { getCurrentEnvironment } from "./environments/resolve.js";
22
22
  */
23
23
 
24
24
  /** Container topologies whose gateway runs on this machine without host `resources`. */
25
- export function isLocalContainerEntry(entry: AssistantEntry): boolean {
25
+ export function isLocalContainerEntry(entry: LockfileAssistant): boolean {
26
26
  return entry.cloud === "docker" || entry.cloud === "apple-container";
27
27
  }
28
28
 
@@ -31,7 +31,7 @@ import {
31
31
  getAssistantDisplayName,
32
32
  lookupAssistantByIdentifier,
33
33
  resolveTargetAssistant,
34
- type AssistantEntry,
34
+ type LockfileAssistant,
35
35
  } from "../assistant-config.js";
36
36
  import { getGatewayUrl } from "../runtime-url.js";
37
37
  import { getCloudUrl, readCloudToken } from "../cloud-client.js";
@@ -138,7 +138,7 @@ export async function resolveLiveVoiceConnection(
138
138
  * by the upgrade that uses it.
139
139
  */
140
140
  async function resolveCloudConnection(
141
- entry: AssistantEntry,
141
+ entry: LockfileAssistant,
142
142
  ): Promise<LiveVoiceConnection> {
143
143
  const sessionToken = readCloudToken();
144
144
  if (!sessionToken) {