@astrale-os/cli 0.8.1-alpha.7 → 1.0.0-beta.1

package/README.md

@@ -13,6 +13,12 @@ curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh
 The installer places a verified standalone binary at
 `~/.astrale/bin/astrale` by default. No local runtime is installed.
 
+During the prerelease period, install the current standalone beta explicitly:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | ASTRALE_CHANNEL=beta sh
+```
+
 Optional installer environment:
 
 ```bash
@@ -29,6 +35,12 @@ ships the [Domain Studio](studio/README.md) (`astrale studio`):
 npm install -g @astrale-os/cli
 ```
 
+During the prerelease period, install the current beta explicitly:
+
+```bash
+npm install -g @astrale-os/cli@beta
+```
+
 The npm build bundles all dependencies, so no private-registry access is needed.
 `astrale studio` launches a local web GUI to author and inspect a domain, with
 local Claude Code and Codex agent harnesses (`--harness claude|codex`); it runs on
@@ -36,9 +48,9 @@ local Claude Code and Codex agent harnesses (`--harness claude|codex`); it runs
 (the rest of the CLI needs only Node ≥ 22). The curl-installed standalone binary
 above does not include the studio — use the npm install for `astrale studio`.
 
-> Pre-1.0, `npm install -g @astrale-os/cli` installs the latest published
-> build (currently an alpha). The curl installer's channels (alpha/beta/rc) are
-> a binary-only concept.
+> Prereleases use their matching npm dist-tag (`alpha`, `beta`, or `rc`); bare
+> `npm install -g @astrale-os/cli` follows the stable `latest` tag. The curl
+> installer has separate binary channels with the same names.
 
 ## Quickstart
 

package/dist/astrale.js

@@ -9738,7 +9738,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "0.8.1-alpha.7",
+    version: "1.0.0-beta.1",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -9799,7 +9799,7 @@ var init_package = __esm(() => {
       "lint:fix": "oxlint --fix .",
       format: "pnpm exec oxfmt --write .",
       "format:check": "pnpm exec oxfmt --check .",
-      test: "bun test src",
+      test: "bun test src && node --test scripts/*.test.mjs",
       "test:watch": "bun test --watch src"
     },
     dependencies: {
@@ -9814,10 +9814,10 @@ var init_package = __esm(() => {
       zod: "^3.25.0"
     },
     devDependencies: {
-      "@astrale-os/kernel-client": "0.6.0-beta.3",
+      "@astrale-os/kernel-client": ">=0.6.0-beta.3 <1.0.0",
       "@astrale-os/ox": ">=0.1.0 <1.0.0",
-      "@astrale-os/sdk": "0.5.0-beta.3",
-      "@astrale-os/shell": "0.3.8-beta.2",
+      "@astrale-os/sdk": ">=0.5.0-beta.3 <1.0.0",
+      "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
       "@astrale/commitlint-config": "jsr:~2.0.1",
       "@commitlint/cli": "~20.3.1",
       "@commitlint/config-conventional": "~20.3.1",
@@ -86817,10 +86817,6 @@ async function connectAdminInstances(context, dependencies = {}) {
           throw new AdminHostNotFoundError(hostId);
         return instanceFromSummary(await binding6.$.invoke(Host.$.method("createInstance"), Path.parse(host.path), input));
       }
-      const inventory = await hostInventory(context.graph, binding6, Host, fleet);
-      const eligible = inventory.hosts.filter((host) => host.state === "ready" && host.path !== inventory.reserved);
-      if (eligible.length > 1)
-        throw hostSelectionRequired(eligible.map((host) => host.id));
       return instanceFromSummary(await binding6.$.invoke(Fleet.$.method("createInstance"), fleet, input));
     },
     status: (identifier) => invokeInstance("status", identifier),
@@ -86864,9 +86860,6 @@ async function hostInventory(graph, binding6, Host, fleet) {
     ...reserved === undefined ? {} : { reserved }
   });
 }
-function hostSelectionRequired(ids2) {
-  return new Error(`alphaCreate could not choose a host: ${ids2.length} ready hosts are assigned (${[...ids2].sort().join(", ")}). ` + "Specify host_id once multi-host placement is enabled.");
-}
 function instanceFromSummary(input) {
   const value2 = record9(input, "Admin Instance summary");
   const failure = value2.failure === undefined ? undefined : record9(value2.failure, "Admin failure");
@@ -87021,16 +87014,20 @@ function schemaUpgradeDetails2(reason) {
   if (!record10(reason) || reason.code !== "SCHEMA_UPGRADE_INCOMPATIBLE")
     return;
   const details = record10(reason.details) ? reason.details : {};
-  return {
-    ...typeof details.origin === "string" ? { origin: details.origin } : {},
-    ...typeof details.issue === "string" ? { issue: details.issue } : {},
-    ...typeof details.expected === "string" ? { expected: details.expected } : {},
-    ...typeof details.actual === "string" ? { actual: details.actual } : {}
-  };
+  const origin = typeof details.origin === "string" ? details.origin : undefined;
+  if (details.issue === "issuer-changed" && origin !== undefined && typeof details.installedIssuer === "string" && typeof details.replacementIssuer === "string") {
+    return {
+      origin,
+      issue: details.issue,
+      installedIssuer: details.installedIssuer,
+      replacementIssuer: details.replacementIssuer
+    };
+  }
+  return origin === undefined ? {} : { origin };
 }
 function schemaUpgradeHint(details) {
   const target2 = details.origin ?? "<origin>";
-  const explanation = details.expected !== undefined && details.actual !== undefined ? "A replacement cannot change an installed Domain issuer." : "The replacement changes an immutable part of the installed Domain.";
+  const explanation = details.issue === "issuer-changed" ? "A replacement cannot change an installed Domain issuer." : "The replacement changes an immutable part of the installed Domain.";
   return `${explanation} If this change is intentional, first run ` + `\`astrale domain uninstall ${target2}\`, then install it again. ` + "The Kernel refuses uninstall while dependents or business data remain; uninstall never deletes business data.";
 }
 function reasonWithCode(input, code) {
@@ -87063,7 +87060,7 @@ var init_reasons = __esm(() => {
 });
 
 // src/connection/errors.ts
-async function formatKernelError(error52, isRaw, urlArg = "", debug = false) {
+async function formatKernelError(error52, isRaw, urlArg = "", debug = false, opts = {}) {
   const url3 = urlArg || (error52 instanceof Error ? error52.url ?? "" : "");
   const localContext = await contextForError(error52);
   if (error52 instanceof AstraleError) {
@@ -87088,7 +87085,7 @@ async function formatKernelError(error52, isRaw, urlArg = "", debug = false) {
   const name = error52.name;
   switch (name) {
     case "TransportError":
-      presentTransportError(error52, isRaw, url3, localContext);
+      presentTransportError(error52, isRaw, url3, localContext, opts.recovery);
       break;
     case "ResponseError": {
       const code = error52.code;
@@ -87117,11 +87114,9 @@ async function formatKernelError(error52, isRaw, urlArg = "", debug = false) {
         presentFunctionInputIssues(inputIssues);
         if (queryRepair !== undefined)
           presentQueryInputRepair(queryRepair);
-        if (upgrade?.expected !== undefined) {
-          log.dim(`  installed issuer: ${upgrade.expected}`);
-        }
-        if (upgrade?.actual !== undefined) {
-          log.dim(`  replacement issuer: ${upgrade.actual}`);
+        if (upgrade?.issue === "issuer-changed") {
+          log.dim(`  installed issuer: ${upgrade.installedIssuer}`);
+          log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`);
         }
         if (hint !== undefined)
           log.dim(`  ${hint}`);
@@ -87194,7 +87189,7 @@ function mapPublicError(error52) {
   }
   return { code: name && name !== "Error" ? name : "UNKNOWN", message: error52.message };
 }
-function presentTransportError(error52, isRaw, url3, context) {
+function presentTransportError(error52, isRaw, url3, context, recovery) {
   const phase = transportPhase(error52);
   const delivery = transportDelivery(error52);
   const code = phase === "connect" ? "CONNECTION_ERROR" : phase === "timeout" ? "TIMEOUT" : phase === "closed" ? "DISCONNECTED" : "TRANSPORT_ERROR";
@@ -87205,7 +87200,8 @@ function presentTransportError(error52, isRaw, url3, context) {
       ...url3 === "" ? {} : { url: url3 },
       ...phase === undefined ? {} : { phase },
       ...delivery === undefined ? {} : { delivery },
-      ...context === undefined ? {} : { context }
+      ...context === undefined ? {} : { context },
+      ...delivery === "unknown" && recovery !== undefined ? recovery : {}
     });
     return;
   }
@@ -87218,10 +87214,18 @@ function presentTransportError(error52, isRaw, url3, context) {
     log.dim("  Check the target and run `astrale status`.");
   else if (phase === "timeout")
     log.dim("  Try increasing `--timeout`.");
-  else if (delivery === "unknown") {
+  else if (delivery === "unknown")
+    printOperationRecovery(recovery);
+  printLocalContext(context);
+}
+function printOperationRecovery(recovery) {
+  if (recovery === undefined) {
     log.dim("  Delivery is unknown; do not automatically retry a mutating call.");
+    return;
   }
-  printLocalContext(context);
+  log.dim("  Delivery is unknown; retry with the same operation id:");
+  log.dim(`  operation: ${recovery.operation}`);
+  log.dim(`  ${recovery.retry}`);
 }
 function presentFunctionInputIssues(issues) {
   for (const issue2 of issues) {
@@ -88640,7 +88644,9 @@ async function runKernelCommand(input) {
   } catch (error52) {
     if (!isRaw && spin)
       spin.fail(`${label} failed`);
-    await formatKernelError(error52, isRaw, undefined, opts.debug);
+    await formatKernelError(error52, isRaw, undefined, opts.debug, {
+      recovery: input.recovery
+    });
     process.exit(1);
   }
 }
@@ -89766,7 +89772,9 @@ var init_update = __esm(() => {
 // src/commands/update.ts
 var exports_update = {};
 __export(exports_update, {
-  default: () => update_default
+  cliStale: () => cliStale,
+  default: () => update_default,
+  fetchNpmTargetVersion: () => fetchNpmTargetVersion
 });
 async function refreshSkills() {
   if (!detectSkill(ASTRALE_CLI_SKILL).installed) {
@@ -89815,29 +89823,35 @@ async function refreshSdkDeps(check3, assumeYes = false) {
   }
   return true;
 }
-async function cliStale(opts) {
+async function cliStale(opts, dependencies = CLI_STALE_DEPENDENCIES) {
   const running = package_default.version;
-  const latest = await fetchNpmLatestVersion().catch(() => {
-    return;
-  });
   try {
-    const r = await updateAstrale({
+    const r = await dependencies.update({
       check: true,
       channel: opts.channel,
       version: opts.version,
       currentVersion: running
     });
     if (r.status === "updated") {
-      return { stale: false, managed: false, current: running, latest: latest ?? running };
+      return {
+        stale: false,
+        managed: false,
+        current: r.currentVersion,
+        latest: r.currentVersion,
+        channel: r.channel
+      };
     }
     return {
-      stale: latest !== undefined ? latest !== running : r.status === "available",
+      stale: r.status === "available",
       managed: false,
-      current: running,
-      latest: latest ?? r.latestVersion,
-      channel: latest !== undefined ? "npm" : r.channel
+      current: r.currentVersion,
+      latest: r.latestVersion,
+      channel: r.channel
     };
   } catch {
+    const latest = await dependencies.fetchPackageVersion(opts).catch(() => {
+      return;
+    });
     return {
       stale: latest !== undefined && latest !== running,
       managed: true,
@@ -89846,8 +89860,9 @@ async function cliStale(opts) {
     };
   }
 }
-async function fetchNpmLatestVersion() {
-  const response2 = await fetch("https://registry.npmjs.org/@astrale-os/cli/latest");
+async function fetchNpmTargetVersion(opts) {
+  const target2 = opts.version ?? (opts.channel === "stable" ? "latest" : opts.channel) ?? "latest";
+  const response2 = await fetch(`https://registry.npmjs.org/@astrale-os/cli/${target2}`);
   if (!response2.ok)
     throw new Error(`npm registry HTTP ${response2.status}`);
   const body = await response2.json();
@@ -89863,7 +89878,7 @@ async function sdkStale() {
   const outdated = await findSdkOutdated();
   return { stale: outdated.length > 0, inProject: true, outdated };
 }
-var update_default;
+var CLI_STALE_DEPENDENCIES, update_default;
 var init_update2 = __esm(() => {
   init_package();
   init_log();
@@ -89872,6 +89887,10 @@ var init_update2 = __esm(() => {
   init_sdk_deps();
   init_skills();
   init_update();
+  CLI_STALE_DEPENDENCIES = {
+    update: updateAstrale,
+    fetchPackageVersion: fetchNpmTargetVersion
+  };
   update_default = {
     name: "update",
     description: "Check for and install Astrale CLI updates",
@@ -93593,11 +93612,12 @@ __export(exports_install, {
   default: () => install_default,
   directInstallCallInput: () => directInstallCallInput,
   domainRefFromTarget: () => domainRefFromTarget,
+  installDirect: () => installDirect,
   installViaAdmin: () => installViaAdmin,
   isIdentityOverride: () => isIdentityOverride,
   probeDeclaredOrigin: () => probeDeclaredOrigin
 });
-function directInstallCallInput(url3, token, operation2 = crypto.randomUUID()) {
+function directInstallCallInput(url3, operation2, token) {
   return Object.freeze({
     operation: operation2,
     domains: [
@@ -93611,6 +93631,15 @@ function directInstallCallInput(url3, token, operation2 = crypto.randomUUID()) {
     ]
   });
 }
+function acceptOperationId(input) {
+  if (typeof input !== "string" || !OPERATION_ID_PATTERN.test(input)) {
+    throw new AstraleError("INVALID_FLAG", "--operation must be a canonical lowercase UUIDv4.", "Omit --operation for a fresh install; use it only with the exact UUID printed for recovery.");
+  }
+  return input;
+}
+function createOperationId() {
+  return acceptOperationId(globalThis.crypto.randomUUID());
+}
 async function installViaAdmin(target2, opts, dependencies = {}) {
   const admin = { ...defaultAdminInstallDependencies, ...dependencies };
   const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI);
@@ -93648,8 +93677,9 @@ async function installViaAdmin(target2, opts, dependencies = {}) {
       log.dim(`  origin: ${result.origin}`);
       log.dim(`  url:    ${result.url}`);
     });
-  } catch (e) {
-    fatal(e, opts);
+  } catch (error52) {
+    await formatKernelError(error52, isMachine(opts), undefined, opts.debug);
+    process.exit(1);
   }
 }
 function assertInstallTargetReady(instance) {
@@ -93712,40 +93742,49 @@ async function activeSlug() {
     return;
   }
 }
-async function installDirect(target2, opts) {
+async function installDirect(target2, opts, dependencies = {}) {
+  const direct = { ...defaultDirectInstallDependencies, ...dependencies };
   let host = "";
   let consentedOrigin;
+  let operation2;
   try {
     if (!target2) {
       throw new AstraleError("MISSING_ARG", "--direct requires a domain url.", "e.g. astrale domain install https://crm.acme.dev --direct");
     }
     host = validateInstallUrl(target2);
+    operation2 = opts.operation === undefined ? direct.createOperationId() : direct.acceptOperationId(opts.operation);
     consentedOrigin = await ensureIdentityOverrideConsent(target2, host, opts.allowIdentityOverride ?? false);
   } catch (e) {
-    fatal(e);
+    fatal(e, opts);
   }
   const url3 = target2;
-  await runKernelCommand({
+  const retry = directInstallRetry(url3, operation2, opts);
+  await direct.runKernelCommand({
     opts,
-    label: `Installing domain from ${url3}`,
-    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, directInstallCallInput(url3, opts.token))),
+    label: `Installing domain from ${url3} (operation ${operation2})`,
+    recovery: { operation: operation2, retry },
+    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, directInstallCallInput(url3, operation2, opts.token))),
     format: (result, fmtOpts, isRaw) => {
       if (isRaw) {
         output(result, fmtOpts);
         return;
       }
       const installed = result.transitions[0]?.intent;
-      if (installed === undefined) {
+      if (!installed)
         throw new Error("Kernel install returned no committed Domain transition.");
-      }
       const revision = installed.target?.schemaRevision ?? result.operation;
       log.success(`Domain installed: ${installed.origin}@${revision}`);
+      log.dim(`  operation:   ${result.operation}`);
       if (isIdentityOverride(installed.origin, host) && installed.origin !== consentedOrigin) {
         log.warn(`Installed origin "${installed.origin}" differs from the serving host "${host}" ` + `and was not confirmed before install (the worker's /meta did not declare it). ` + `Every ${installed.origin}/* call on this instance now routes to ${host}.`);
       }
     }
   });
 }
+function directInstallRetry(url3, operation2, opts) {
+  const instance = opts.instance === undefined ? "" : ` -i ${opts.instance}`;
+  return `astrale domain install ${url3} --direct --operation ${operation2}${instance}`;
+}
 function validateInstallUrl(value2) {
   let url3;
   try {
@@ -93798,12 +93837,13 @@ async function probeDeclaredOrigin(url3) {
     return;
   }
 }
-var install_default, defaultAdminInstallDependencies;
+var OPERATION_ID_PATTERN, install_default, defaultAdminInstallDependencies, defaultDirectInstallDependencies;
 var init_install3 = __esm(() => {
   init_path5();
   init_kernel2();
   init_source();
   init_connection2();
+  init_errors12();
   init_errors2();
   init_admin_domain();
   init_admin_instance();
@@ -93813,6 +93853,7 @@ var init_install3 = __esm(() => {
   init_output();
   init_prompt();
   init_validation2();
+  OPERATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
   install_default = {
     name: "install",
     description: "Install a domain on an instance (via the admin catalog, or --direct from a url)",
@@ -93831,6 +93872,10 @@ Behavior:
   origin differs from its serving host, it requires explicit consent (an
   interactive DANGER prompt, or --allow-identity-override in scripts).
 
+  A fresh, strong operation id is generated automatically. Use --operation
+  only to retry or recover the exact same direct install after an outcome-unknown
+  timeout or disconnect.
+
 Examples:
   $ astrale domain install crm.acme.dev -i staging          # by origin, via admin
   $ astrale domain install https://crm.acme.dev             # by url, via admin
@@ -93855,12 +93900,19 @@ Examples:
         flags: "--token <token>",
         description: "Bearer token for private domain install endpoints (--direct only)"
       },
+      {
+        flags: "--operation <uuid>",
+        description: "Reuse an exact direct-install operation id for explicit retry/recovery"
+      },
       {
         flags: "--allow-identity-override",
         description: "Consent to a domain whose origin differs from its serving host (--direct only)"
       }
     ],
     action: async (target2, opts) => {
+      if (opts.operation !== undefined && !opts.direct) {
+        fatal(new AstraleError("INVALID_FLAG", "--operation is valid only with --direct.", "Ordinary direct installs generate a fresh operation id automatically."), opts);
+      }
       if (opts.direct) {
         await installDirect(target2, opts);
         return;
@@ -93873,6 +93925,11 @@ Examples:
     listDomains: listAdminDomainsInContext,
     install: installAdminDomainInContext
   });
+  defaultDirectInstallDependencies = Object.freeze({
+    acceptOperationId,
+    createOperationId,
+    runKernelCommand
+  });
 });
 
 // src/commands/domain/uninstall.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.1-alpha.7",
+  "version": "1.0.0-beta.1",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -62,10 +62,10 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@astrale-os/kernel-client": "0.6.0-beta.3",
+    "@astrale-os/kernel-client": ">=0.6.0-beta.3 <1.0.0",
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
-    "@astrale-os/sdk": "0.5.0-beta.3",
-    "@astrale-os/shell": "0.3.8-beta.2",
+    "@astrale-os/sdk": ">=0.5.0-beta.3 <1.0.0",
+    "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
     "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "~20.3.1",
     "@commitlint/config-conventional": "~20.3.1",
@@ -107,7 +107,7 @@
     "lint:fix": "oxlint --fix .",
     "format": "pnpm exec oxfmt --write .",
     "format:check": "pnpm exec oxfmt --check .",
-    "test": "bun test src",
+    "test": "bun test src && node --test scripts/*.test.mjs",
     "test:watch": "bun test --watch src"
   }
 }

package/src/admin/instance/__tests__/client.test.ts

@@ -153,7 +153,7 @@ describe('V2 Admin Instance adapter', () => {
     )
   })
 
-  test('invokes Fleet.createInstance with an internal operation identity', async () => {
+  test('delegates default placement to Fleet without reading Host inventory', async () => {
     const created = {
       id: '@instance-node',
       slug: 'demo',
@@ -179,6 +179,8 @@ describe('V2 Admin Instance adapter', () => {
       Path.id(NodeId('fleet')),
       { operationId: 'cli.instance.create:test', slug: 'demo' },
     )
+    expect(contract.graph.query).not.toHaveBeenCalled()
+    expect(contract.graph.neighbors).not.toHaveBeenCalled()
   })
 
   test('resolves --host-id to an exact Host receiver and rejects the reserved Admin Host', async () => {

package/src/admin/instance/client.ts

@@ -119,15 +119,9 @@ export async function connectAdminInstances(
         )
       }
 
-      // Preserve the existing interactive multi-Host picker without accepting a
-      // doomed operation first. Graph read policy exposes only caller-usable
-      // Hosts; the reserved Admin Host is excluded explicitly.
-      const inventory = await hostInventory(context.graph, binding, Host, fleet)
-      const eligible = inventory.hosts.filter(
-        (host) => host.state === 'ready' && host.path !== inventory.reserved,
-      )
-      if (eligible.length > 1) throw hostSelectionRequired(eligible.map((host) => host.id))
-
+      // Default placement belongs to Admin. Avoid a redundant Host graph read:
+      // it requires broader graph authority than this Fleet operation and can
+      // deny an otherwise authorized caller before the server selects a Host.
       return instanceFromSummary(
         await binding.$.invoke(Fleet.$.method('createInstance') as never, fleet, input as never),
       )
@@ -200,13 +194,6 @@ async function hostInventory(
   })
 }
 
-function hostSelectionRequired(ids: readonly string[]): Error {
-  return new Error(
-    `alphaCreate could not choose a host: ${ids.length} ready hosts are assigned (${[...ids].sort().join(', ')}). ` +
-      'Specify host_id once multi-host placement is enabled.',
-  )
-}
-
 type DynamicDefinition = ReturnType<DomainBinding['$']['class']>
 
 function instanceFromSummary(input: unknown): InstanceInfo {

package/src/commands/__tests__/domain-install-operation.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test'
+
+import { installDirect } from '../domain/install'
+
+const GENERATED = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+const RETRY = '139137b5-af47-47ce-92b2-b64a2b0c63d7'
+
+const originalFetch = globalThis.fetch
+
+class ExitError extends Error {}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+describe('direct domain install operation identity', () => {
+  test('generates one operation before transport and exposes it for recovery', async () => {
+    globalThis.fetch = mock(async () =>
+      Response.json({ domainName: 'crm.test' }),
+    ) as unknown as typeof fetch
+    const create = mock(() => GENERATED)
+    const requests: unknown[] = []
+    let recovery: unknown
+
+    await installDirect(
+      'https://crm.test',
+      { direct: true, json: true },
+      {
+        createOperationId: create,
+        runKernelCommand: async (input) => {
+          recovery = input.recovery
+          requests.push(
+            await input.fn({
+              session: {
+                call: async (call: { input: unknown }) => call.input,
+              },
+            } as never),
+          )
+        },
+      },
+    )
+
+    expect(create).toHaveBeenCalledTimes(1)
+    expect(requests).toEqual([
+      {
+        operation: GENERATED,
+        domains: [{ source: { kind: 'remote', url: 'https://crm.test' } }],
+      },
+    ])
+    expect(recovery).toEqual({
+      operation: GENERATED,
+      retry: `astrale domain install https://crm.test --direct --operation ${GENERATED}`,
+    })
+  })
+
+  test('accepts an explicit operation only as the exact retry identity', async () => {
+    globalThis.fetch = mock(async () =>
+      Response.json({ domainName: 'crm.test' }),
+    ) as unknown as typeof fetch
+    const create = mock(() => GENERATED)
+    const accepted: string[] = []
+    const requests: unknown[] = []
+
+    await installDirect(
+      'https://crm.test',
+      { direct: true, operation: RETRY, json: true },
+      {
+        createOperationId: create,
+        acceptOperationId: (input) => {
+          accepted.push(String(input))
+          return RETRY
+        },
+        runKernelCommand: async (input) => {
+          requests.push(
+            await input.fn({
+              session: {
+                call: async (call: { input: unknown }) => call.input,
+              },
+            } as never),
+          )
+        },
+      },
+    )
+
+    expect(create).not.toHaveBeenCalled()
+    expect(accepted).toEqual([RETRY])
+    expect(requests).toEqual([
+      {
+        operation: RETRY,
+        domains: [{ source: { kind: 'remote', url: 'https://crm.test' } }],
+      },
+    ])
+  })
+
+  test('rejects a non-UUID operation before metadata or Kernel transport', async () => {
+    const originalExit = process.exit
+    const originalWrite = process.stderr.write
+    const fetch = mock(async () => Response.json({ domainName: 'crm.test' }))
+    const run = mock(async () => undefined)
+    globalThis.fetch = fetch as unknown as typeof globalThis.fetch
+    process.exit = (() => {
+      throw new ExitError('exit')
+    }) as typeof process.exit
+    process.stderr.write = (() => true) as typeof process.stderr.write
+    try {
+      await expect(
+        installDirect(
+          'https://crm.test',
+          { direct: true, operation: 'guessable-operation', json: true },
+          { runKernelCommand: run },
+        ),
+      ).rejects.toBeInstanceOf(ExitError)
+    } finally {
+      process.exit = originalExit
+      process.stderr.write = originalWrite
+    }
+
+    expect(fetch).not.toHaveBeenCalled()
+    expect(run).not.toHaveBeenCalled()
+  })
+})