@isomorph.ai/cli 0.4.2 → 0.5.1

package/dist/packages/harbour-cli/src/integrations.js

@@ -4,14 +4,14 @@ import { CliError } from "./output.js";
 import { CLI_VERSION } from "./version.js";
 export class GovernanceClient {
     apiUrl;
-    token;
     tenantId;
     fetchImpl;
+    token;
     constructor(apiUrl, token, tenantId, fetchImpl = fetch) {
         this.apiUrl = apiUrl;
-        this.token = token;
         this.tenantId = tenantId;
         this.fetchImpl = fetchImpl;
+        this.token = typeof token === "string" ? async () => token : token;
     }
     link(input) {
         return this.call("POST", "/v1/development/apps/link", { tenantId: this.tenantId, ...input });
@@ -35,6 +35,8 @@ export class GovernanceClient {
      * environment's lane (governance files the requests itself), the company's AI
      * setup when the app calls governed AI, and the CLI version. One call, one
      * refusal shape, instead of the sequential integrations → AI → pipeline cycles.
+     * `deploy` no longer calls this — its deploy route runs the same preflight
+     * before opening the operation; `promote` still asks it for production.
      */
     deployPreflight(appId, body) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/deploy-preflight`, body);
@@ -46,18 +48,59 @@ export class GovernanceClient {
     submitFeedback(appId, input) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/feedback`, input);
     }
+    // The kit's one deploy transport (governance ADR 0020): open or resume, hand
+    // over the package, then read the same status the console reads.
+    /** Opens the app's deployment, or resumes the one already open for this package (same sha256). 409 `DEPLOY_BLOCKED` carries every blocker in `details`; 409 `DEPLOY_IN_FLIGHT` names the operation still deploying another package. */
+    async startDeployment(appId, body) {
+        const { status, data } = await this.exchange("POST", deployments(appId), body);
+        return { operationRef: data.operationRef, upload: data.upload, status: data.status, resumed: status !== 201 };
+    }
+    /** The package is uploaded: from here the server carries the deployment on by itself (intake, the managed save, verification). */
+    completePackage(appId, operationRef, body) {
+        return this.call("POST", `${deployments(appId)}/${encodeURIComponent(operationRef)}/package`, body);
+    }
+    /** The operation's status, long-polled up to `waitSeconds` (0–15) and answered early on change. */
+    deploymentStatus(appId, operationRef, waitSeconds = 0) {
+        return this.call("GET", `${deployments(appId)}/${encodeURIComponent(operationRef)}?wait=${Math.min(15, Math.max(0, Math.floor(waitSeconds)))}`);
+    }
+    promoteDeployment(appId, operationRef, body) {
+        return this.call("POST", `${deployments(appId)}/${encodeURIComponent(operationRef)}/promote`, body);
+    }
+    retryDeployment(appId, operationRef) {
+        return this.call("POST", `${deployments(appId)}/${encodeURIComponent(operationRef)}/retry`, {});
+    }
     async call(method, path, body) {
+        return (await this.exchange(method, path, body)).data;
+    }
+    /**
+     * One request, with governance's refusal carried whole: its code (or category,
+     * or the HTTP status), its sentence, and its `details` for the caller. A 401 is
+     * retried once with a re-resolved token — a sibling process may have rotated
+     * the pair — and a second one is a sign-in refusal. A transport failure and a
+     * 5xx are named as such (`GOVERNANCE_UNREACHABLE`, `HTTP_5xx`) so a long poll
+     * can tell a transient fault from a refusal; see `waitForSettled`.
+     */
+    async exchange(method, path, body) {
         const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
-        const response = await this.fetchImpl(url, { method, headers: { authorization: `Bearer ${this.token}`, "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" })
-            .catch((error) => { throw new CliError("GOVERNANCE_UNREACHABLE", `Isomorph governance at ${new URL(url).host} could not be reached: ${transportFailure(error)}.`); });
+        let response = await this.send(url, method, body);
+        if (response.status === 401)
+            response = await this.send(url, method, body);
         const parsed = await response.json().catch(() => ({}));
         if (response.status === 401)
             throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.", undefined, undefined, undefined, { layer: "governance" });
-        if (!response.ok)
-            throw new CliError(parsed.error?.details?.code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message ?? "Isomorph governance rejected the request.", undefined, undefined, undefined, { layer: "governance" });
-        return (parsed.data ?? parsed);
+        if (!response.ok) {
+            const { code, remediationHint, ...details } = parsed.error?.details ?? {};
+            throw new CliError(code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message || "Isomorph governance rejected the request.", undefined, typeof remediationHint === "string" && remediationHint.trim() ? remediationHint.trim() : undefined, undefined, { layer: "governance", ...(Object.keys(details).length ? { details } : {}) });
+        }
+        return { status: response.status, data: (parsed.data ?? parsed) };
+    }
+    async send(url, method, body) {
+        const token = await this.token();
+        return this.fetchImpl(url, { method, headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" })
+            .catch((error) => { throw new CliError("GOVERNANCE_UNREACHABLE", `Isomorph governance at ${new URL(url).host} could not be reached: ${transportFailure(error)}.`); });
     }
 }
+const deployments = (appId) => `/v1/development/apps/${encodeURIComponent(appId)}/deployments`;
 /**
  * What actually failed under a `fetch` rejection. undici reports every transport
  * failure as `TypeError: fetch failed` and keeps the reason in `cause`: `getaddrinfo
@@ -314,18 +357,31 @@ export async function assertDeployReady(root, client, tenantId, bundle, environm
         throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
     const preflight = await client.deployPreflight(appId, { environment, callsAi, declaration, cliVersion: CLI_VERSION });
-    const blockers = Array.isArray(preflight.blockers) ? preflight.blockers.filter(blocker => blocker && typeof blocker.sentence === "string") : [];
-    if (preflight.ready && !blockers.length) {
+    if (preflight.ready && !blockersOf(preflight.blockers).length) {
         output(`Isomorph confirmed the app can deploy to ${environment}.`);
         return appId;
     }
+    throw deployBlocked(preflight.blockers, environment, output);
+}
+/** The blockers as governance listed them; anything that is not a sentence is dropped rather than printed as `undefined`. */
+function blockersOf(value) {
+    return Array.isArray(value) ? value.filter(blocker => blocker && typeof blocker.sentence === "string") : [];
+}
+/**
+ * The one refusal for a blocked deploy, wherever the preflight ran — `promote`'s
+ * own call or the deploy route's 409 `DEPLOY_BLOCKED`: every sentence printed,
+ * the fixes joined as the hint, and the code readers already know when the
+ * blockers are all of one kind.
+ */
+export function deployBlocked(value, environment, output) {
+    const blockers = blockersOf(value);
     output(`Isomorph cannot deploy to ${environment} yet:`);
     for (const blocker of blockers)
         output(`  ${blocker.sentence}`);
     const kinds = new Set(blockers.map(blocker => blocker.kind));
     const code = kinds.size === 1 ? BLOCKER_CODES[[...kinds][0]] ?? "DEPLOY_BLOCKED" : "DEPLOY_BLOCKED";
     const fixes = [...new Set(blockers.map(blocker => blocker.fix).filter(Boolean))].join(" ");
-    throw new CliError(code, blockers.map(blocker => blocker.sentence).join(" ") || `Isomorph cannot deploy this app to ${environment} yet.`, undefined, fixes || undefined, undefined, { layer: "governance" });
+    return new CliError(code, blockers.map(blocker => blocker.sentence).join(" ") || `Isomorph cannot deploy this app to ${environment} yet.`, undefined, fixes || undefined, undefined, { layer: "governance" });
 }
 /** The code readers already know for a refusal that is all of one kind. */
 const BLOCKER_CODES = { integration: "INTEGRATIONS_NOT_READY", ai: "AI_NOT_READY", cli: "CLI_UPGRADE_REQUIRED" };

package/dist/packages/harbour-cli/src/kit-bundle.manifest.js

@@ -1,28 +1,28 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "isomorph.kit-bundle/1.0",
-    "kitVersion": "0.4.0",
+    "kitVersion": "0.5.1",
     "sdk": {
         "package": "@isomorph.ai/app-sdk",
-        "version": "1.2.0",
-        "tarballSha256": "6b41494883215527a73e05a1e07d022552dfe3402915e23950e357e5e9381c49",
-        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:6b41494883215527a73e05a1e07d022552dfe3402915e23950e357e5e9381c49"
+        "version": "1.2.1",
+        "tarballSha256": "607e3896aa4116d82d0473677d38a68fecd4855a250cd44e038780290c335c67",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:607e3896aa4116d82d0473677d38a68fecd4855a250cd44e038780290c335c67"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:9c7750897be5ed44af332069f463f0cfe9ca94694450b49ab469c019c97d7757",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:52bfe8ca4e40fd38e662ab13c32cc842721f0d48b494561e99ac1607e49e8c74"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:558e3aa74f315a8bf2ae18f1344be3b8fad0203286f43d14d411a4a1f3e15dc0",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:578cc8d98ca687dc79d8567f46abc636db2df0b3d8a01ccf38b30d5932c43353"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:7f6377c465b46cfb45402ae12c3f05063bae7c780c1c2be3aab5bd75614e809a",
-            "sha256": "7f6377c465b46cfb45402ae12c3f05063bae7c780c1c2be3aab5bd75614e809a"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:e36aeea224867ebd7ae4a609284393460f707eaf6c50cb5f8ea1596926bae04b",
+            "sha256": "e36aeea224867ebd7ae4a609284393460f707eaf6c50cb5f8ea1596926bae04b"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:ea9fc7cab8b2ebf27fb39a59699cd3d76117d0f8fc00346f7d85cc1bab84778d",
-            "sha256": "ea9fc7cab8b2ebf27fb39a59699cd3d76117d0f8fc00346f7d85cc1bab84778d"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:0673c75610f7fc8a5f1dbc1ec39570eee2278301430e7bbd4b4323319e7a1e6e",
+            "sha256": "0673c75610f7fc8a5f1dbc1ec39570eee2278301430e7bbd4b4323319e7a1e6e"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:0e1ef627daae405f1043b4b434a446e3cee937c370cb64ea49d84dc07c484d21",
-            "sha256": "0e1ef627daae405f1043b4b434a446e3cee937c370cb64ea49d84dc07c484d21"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8c1fc2e83d6b4cfd056b5252b9676a32e1e49e0596bb072f2c33faef63781aab",
+            "sha256": "8c1fc2e83d6b4cfd056b5252b9676a32e1e49e0596bb072f2c33faef63781aab"
         }
     },
     "brief": {

package/dist/packages/harbour-cli/src/kit.js

@@ -98,7 +98,7 @@ export function newKitLock(bundle, tenantId = "", appId = "") {
     return { schema: "isomorph.kit-lock/1.0", appId, tenantId, bundle, createdAt: now, updatedAt: now };
 }
 // ---- Paths and identity --------------------------------------------------------
-/** Where a kit app keeps its declaration, lock, retained checks, gate-written inventory and (ignored) local state. */
+/** Where a kit app keeps its declaration, lock and app profile (committed), and its generated checks and local state (ignored). */
 export const KIT_DIRECTORY = ".isomorph";
 export function appRoot(rootArg) {
     if (!rootArg)
@@ -111,7 +111,7 @@ export function appRoot(rootArg) {
 export function kitPaths(root) {
     const kit = join(root, KIT_DIRECTORY);
     const local = join(kit, "local");
-    return { kit, local, declaration: join(kit, "integrations.json"), app: join(kit, "app.json"), lock: join(kit, "kit.lock.json"), checks: join(kit, "checks"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json") };
+    return { kit, local, declaration: join(kit, "integrations.json"), app: join(kit, "app.json"), lock: join(kit, "kit.lock.json"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json"), deployNote: join(local, "deploy.json") };
 }
 export function defaultAppProfile(root) {
     // A real description from the start: the person changes it, but a first
@@ -169,7 +169,9 @@ export function linkIdempotencyKey(tenantId, root) {
 /**
  * sha256 over the tracked app files (same boundary as deploy), so any
  * edit changes it — and, per file, the hash of its contents, so a stale check
- * can say WHICH path moved rather than only that something did.
+ * can say WHICH path moved rather than only that something did. The boundary
+ * leaves `.isomorph/checks/` out (analyzer.ts): the gate regenerates it on
+ * every check, and a regeneration is not a change to the app.
  */
 export async function sourceDigest(root) {
     const graph = await scanWorkspace(root, { sourceBoundary: "root" });

package/dist/packages/harbour-cli/src/local-runtime.js

@@ -370,19 +370,20 @@ export class LocalRuntime {
         })();
     }
     /**
-     * Starts the kit gate: the pinned gateway image's `gate` subcommand as a
-     * one-shot service of this project (`docker compose run`), the app mounted
-     * read-only at /workspace, its control listener published on `port`, the
-     * session's PostgreSQL and bucket named for its scratch database and files.
-     * Resolves to the container id; the caller drives the control API
-     * (check.ts) and stops it with stopGate.
+     * Starts the kit gate: the pinned native gateway's `gate` subcommand as a
+     * one-shot process of this project, the app as its workspace (worked on
+     * through a mirror, never written), its control listener on `port`, the
+     * session's PostgreSQL and bucket named for its scratch database and files,
+     * and this node (`HARBOUR_GATE_NODE`) to run the journeys with. Resolves to
+     * the gate id; the caller polls the control API (check.ts) and stops it
+     * with stopGate.
      */
-    async startGate(bundle, port, publicUrl) {
+    async startGate(bundle, port) {
         void bundle;
         if (!this.ports)
             throw new CliError("LOCAL_RUNTIME_FAILED", "The local runtime was not prepared.");
         const id = `gate-${Date.now()}`;
-        const child = spawn(this.binary, ["gate"], { cwd: this.root, env: { ...process.env, HARBOUR_GATE_WORKSPACE: this.root, HARBOUR_GATE_LISTEN: `127.0.0.1:${port}`, HARBOUR_GATE_PUBLIC_URL: publicUrl, HARBOUR_GATE_DATABASE_URL: `postgresql://${LOCAL.dbUser}:${LOCAL.dbPassword}@127.0.0.1:${this.ports.postgres}/${LOCAL.database}?sslmode=disable`, HARBOUR_GATE_S3_BUCKET: LOCAL.bucket, HARBOUR_GATE_FILES_DIRECTORY: join(kitPaths(this.root).state, "gate-files") }, stdio: ["ignore", "ignore", "pipe"] });
+        const child = spawn(this.binary, ["gate"], { cwd: this.root, env: { ...process.env, HARBOUR_GATE_WORKSPACE: this.root, HARBOUR_GATE_LISTEN: `127.0.0.1:${port}`, HARBOUR_GATE_NODE: process.execPath, HARBOUR_GATE_DATABASE_URL: `postgresql://${LOCAL.dbUser}:${LOCAL.dbPassword}@127.0.0.1:${this.ports.postgres}/${LOCAL.database}?sslmode=disable`, HARBOUR_GATE_S3_BUCKET: LOCAL.bucket, HARBOUR_GATE_FILES_DIRECTORY: join(kitPaths(this.root).state, "gate-files") }, stdio: ["ignore", "ignore", "pipe"] });
         this.gates.set(id, child);
         child.stderr?.on("data", chunk => this.gateOutput.set(id, `${this.gateOutput.get(id) ?? ""}${chunk}`.slice(-4000)));
         return id;

package/dist/packages/harbour-cli/src/operations.js

@@ -1,7 +1,14 @@
-import { structured } from "./remote-mcp-client.js";
 import { CliError } from "./output.js";
+/** The status reader for one operation, bound to the deployment route. */
+export function statusFetch(governance, appId, operationRef) {
+    return waitSeconds => governance.deploymentStatus(appId, operationRef, waitSeconds);
+}
 const DEPLOYMENT_TERMINAL = new Set(["LIVE", "FAILED", "STALE", "RETRYABLE_FAILURE"]);
 const PRODUCTION_TERMINAL = new Set(["LIVE", "FAILED", "MANUAL_RECOVERY"]);
+/** A save that has ended without a saved copy: nothing more happens to it without the builder acting. */
+const SAVE_FAILED = new Set(["FAILED", "RETRYABLE_FAILURE"]);
+/** The stages between the package hand-over and a deployment attempt, during which the server is at work with nothing for the builder to do. */
+const SERVER_AT_WORK = new Set(["inspection", "awaiting-approval", "verification"]);
 export function summarize(status) {
     return {
         ...(status.operation?.stage ? { stage: status.operation.stage } : {}),
@@ -10,9 +17,12 @@ export function summarize(status) {
         ...(status.production ? { production: pickProduction(status.production) } : {}),
         ...(status.waiting ? { waiting: { stage: status.waiting.stage, plainEnglish: status.waiting.plainEnglish } } : {}),
         ...(status.nextAction?.plainEnglish ? { nextStep: status.nextAction.plainEnglish } : {}),
-        ...(status.nextTool ? { nextTool: status.nextTool } : {})
+        ...(status.nextTool ? { nextTool: status.nextTool } : {}),
+        ...(isRecord(status.sourceControlEvidence) ? { sourceControlEvidence: status.sourceControlEvidence } : {}),
+        ...(isRecord(status.runnerEvidence) ? { runnerEvidence: status.runnerEvidence } : {})
     };
 }
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 function pickDeployment(value) {
     return {
         state: value.state,
@@ -63,9 +73,13 @@ function pickProduction(value) {
         ...(value.failure ? { failure: pickFailure(value.failure) } : {})
     };
 }
-export async function fetchStatus(client, operationRef, waitSeconds = 0) {
-    await client.initialize();
-    return structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds }));
+/**
+ * The one way a refusal the server recorded on the operation becomes a failure
+ * the builder can act on: the server's own code, sentence and fix where it gave
+ * them, the generic pair only where it gave nothing, and the operation always.
+ */
+export function recordedRefusal(failure, fallbackCode, fallbackMessage, operationRef, result) {
+    return new CliError(failure?.code ?? fallbackCode, failure?.message ?? fallbackMessage, operationRef, failure?.remediationHint, result, { layer: "governance" });
 }
 /** True when nothing more will change without a person acting. */
 export function isSettled(status) {
@@ -75,12 +89,29 @@ export function isSettled(status) {
         return PRODUCTION_TERMINAL.has(status.production.state);
     if (status.deployment)
         return DEPLOYMENT_TERMINAL.has(status.deployment.state);
-    return false;
+    return status.operation?.stage === "failed" || SAVE_FAILED.has(status.sourceSave?.status ?? "");
+}
+/**
+ * Whether the server is still at work before any deployment attempt exists:
+ * inspecting the package, saving it, verifying the saved copy. The CLI used to
+ * drive these as its own calls and waited on each; now the server takes them
+ * on its own, so a watch treats them as work in flight — bounded by the wait
+ * ceiling, never by the short grace window that follows a verified save.
+ */
+function saveInFlight(status) {
+    const save = status.sourceSave?.status ?? "";
+    return SERVER_AT_WORK.has(status.operation?.stage ?? "") || save === "AWAITING_APPROVAL" || save === "QUEUED" || save === "RUNNING";
 }
 /** What the wait was before `--max-wait` existed: a caller that never passes it waits exactly as long as it did. */
 const DEFAULT_MAX_WAIT_MS = 30 * 60_000;
 /** A line at least this often while nothing changes, so a wrapper with its own idle timeout (an agent's shell tool) keeps seeing output; see `follow`. */
 const HEARTBEAT_MS = 60_000;
+/** A status read that failed for a reason a later read may not: the network, or governance answering 5xx. A refusal (sign-in, not found) is not one. */
+function transient(error) {
+    if (!(error instanceof CliError))
+        return true;
+    return error.code === "GOVERNANCE_UNREACHABLE" || /^HTTP_5\d\d$/.test(error.code);
+}
 /**
  * Follow the operation until the preview deployment (or an in-flight production
  * promotion) settles. Isomorph long-polls up to 15 s per call and returns early
@@ -97,7 +128,7 @@ const HEARTBEAT_MS = 60_000;
  * left of the bound, so `--max-wait N` answers within N seconds — an agent's
  * tool with a total cap of N sees the answer instead of killing the command.
  */
-export async function waitForSettled(client, operationRef, output, options = {}) {
+export async function waitForSettled(fetch, operationRef, output, options = {}) {
     const now = options.now ?? Date.now;
     const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
     const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
@@ -117,7 +148,7 @@ export async function waitForSettled(client, operationRef, output, options = {})
             return last;
         let status;
         try {
-            status = await fetchStatus(client, operationRef, Math.min(15, Math.max(0, Math.floor(remainingMs / 1000))));
+            status = await fetch(Math.min(15, Math.max(0, Math.floor(remainingMs / 1000))));
             consecutiveFailures = 0;
         }
         catch (error) {
@@ -125,7 +156,7 @@ export async function waitForSettled(client, operationRef, output, options = {})
             // transiently (gateway timeout, dropped connection). The operation is
             // unaffected by our polling, so keep watching; give up only after a run
             // of failures, and say what the last one was instead of a generic error.
-            if (error instanceof CliError)
+            if (!transient(error))
                 throw error; // e.g. AUTH_REQUIRED: retrying cannot help.
             consecutiveFailures += 1;
             if (consecutiveFailures >= 5)
@@ -138,7 +169,7 @@ export async function waitForSettled(client, operationRef, output, options = {})
         if (isSettled(status))
             return status;
         const at = now();
-        bound = status.deployment || status.production ? maxWaitMs : graceMs;
+        bound = status.deployment || status.production || saveInFlight(status) ? maxWaitMs : graceMs;
         const line = progressLine(status);
         if (line !== lastLine) {
             output(line);
@@ -156,15 +187,26 @@ export async function waitForSettled(client, operationRef, output, options = {})
     }
 }
 function safeMessage(error) {
-    const raw = error instanceof Error ? error.message : String(error);
+    const raw = error instanceof CliError ? `${error.code}: ${error.message}` : error instanceof Error ? error.message : String(error);
     return raw.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").replace(/\s+/g, " ").trim().slice(0, 160) || "no details";
 }
 function activity(status) {
-    return status.production ? "promoting the app to production" : status.deployment ? "deploying the app" : "preparing the deployment";
+    if (status.production)
+        return "promoting the app to production";
+    if (status.deployment)
+        return "deploying the app";
+    return saveInFlight(status) ? "saving the app" : "preparing the deployment";
 }
+/** What the server is doing right now, as one line; printed when it changes. */
 function progressLine(status) {
     const stage = status.production ?? status.deployment;
-    return stage ? `Isomorph is ${activity(status)}${stage.message ? ` (${stage.message})` : ""}.` : "Isomorph saved the app and is preparing the deployment.";
+    if (stage)
+        return `Isomorph is ${activity(status)}${stage.message ? ` (${stage.message})` : ""}.`;
+    switch (status.operation?.stage) {
+        case "inspection": return "Isomorph is inspecting the app package.";
+        case "verification": return "Isomorph is verifying the saved app.";
+        default: return saveInFlight(status) ? "Isomorph is saving the app to the approved company code system. Nothing is deployed or released by that." : "Isomorph saved the app and is preparing the deployment.";
+    }
 }
 /**
  * The one sentence for a watch that has not ended: the heartbeat prints it as
@@ -172,7 +214,7 @@ function progressLine(status) {
  * wrapper that stops watching, or an agent whose tool did, runs the command
  * it names and continues the same operation — it never starts another.
  */
-function runningLine(status, elapsedMs, operationRef) {
+export function runningLine(status, elapsedMs, operationRef) {
     const seconds = Math.round(elapsedMs / 1000);
     return `Isomorph is still ${activity(status)} (${Math.floor(seconds / 60)}m${seconds % 60}s). Safe to stop watching: \`${continueCommand(operationRef)}\` picks it up; do not start another.`;
 }
@@ -180,10 +222,11 @@ function runningLine(status, elapsedMs, operationRef) {
  * The one command that resumes a watch, as the CLI's help and the agent guide
  * print it too. Bounded at two minutes so a wrapper with an idle timeout gets
  * an answer and runs it again, rather than cutting a 30-minute wait off and
- * learning nothing.
+ * learning nothing. It names the app folder because the deployment routes are
+ * addressed by the app: `status` reads the app's identity from `.isomorph/`.
  */
 export function continueCommand(operationRef) {
-    return `isomorph status --operation ${operationRef} --wait --max-wait 120 --json`;
+    return `isomorph status --app-root . --operation ${operationRef} --wait --max-wait 120 --json`;
 }
 /** The exit-relevant outcome of a status — success, a step the maker must take, an operation still in flight — as the summary with its `outcome` named; a failure is thrown. */
 export function outcomeFor(status, operationRef) {
@@ -210,14 +253,31 @@ export function outcomeFor(status, operationRef) {
     }
     if (status.deployment)
         return { ...summary, outcome: "running" };
-    // No deployment yet has two very different causes. A save that stalled or
-    // failed (RETRYABLE_FAILURE, FAILED) is resumed by running `deploy`
-    // again — observed 2026-09-14 (fourier "Dad Jokes"): a builder read the
-    // administrator sentence for a save that was simply resumable. Only a
-    // SUCCEEDED save with no deployment behind it is the company-setup case.
+    // Before any deployment, the server can refuse the package (intake) or fail to
+    // save it. Intake does not merely refuse: it records why — a stable code, one
+    // plain-English sentence, and the commands that fix it — on the operation. Say
+    // what the server said, and keep the generic line only for an operation that
+    // failed without any detail at all.
+    if (status.operation?.stage === "failed")
+        throw recordedRefusal(pickSourceFailure(status), "PACKAGE_REJECTED", "Isomorph could not safely accept this app package.", operationRef, summary);
     const save = status.sourceSave?.status;
-    if (save && save !== "SUCCEEDED")
+    if (save === "FAILED")
+        throw new CliError("FAILED", "Isomorph could not save the app.", operationRef, undefined, summary);
+    if (save === "RETRYABLE_FAILURE")
+        throw new CliError("RETRYABLE_FAILURE", "Isomorph could not complete the save yet. Resume this operation safely.", operationRef, undefined, summary);
+    // The server inspecting, saving or verifying is work in flight, like a deployment.
+    if (saveInFlight(status))
+        return { ...summary, outcome: "running" };
+    // No deployment yet has three different causes, and each names its own next
+    // step: a package the server has not received, a save in a state it does not
+    // carry on from by itself — resumed by running `deploy` again, observed
+    // 2026-09-14 (fourier "Dad Jokes"): a builder read the administrator sentence
+    // for a save that was simply resumable — and only a SUCCEEDED save with no
+    // deployment behind it is the company-setup case.
+    if (save && save !== "SUCCEEDED" && save !== "DUPLICATE")
         return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? `Isomorph has not finished saving the app (${save}). Run \`isomorph deploy\` again for this app: it resumes the same save and deploys; nothing is deployed twice.` };
+    if (!save && status.operation?.stage !== "complete")
+        return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? "Isomorph has not received this app's package yet. Run `isomorph deploy` again for this app: it continues the same operation; nothing is deployed twice." };
     return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? "Isomorph saved the app but has not started a deployment for this company yet. Ask your Isomorph administrator to connect deployment." };
 }
 /**
@@ -232,76 +292,46 @@ export function outcomeFor(status, operationRef) {
  * human by email and never reached the agent. The heartbeat, the bounded
  * `--max-wait`, and this outcome each close one part of that.
  */
-export async function follow(client, operationRef, output, options = {}) {
+export async function follow(fetch, operationRef, output, options = {}) {
     const now = options.now ?? Date.now;
     const startedAt = now();
-    const status = await waitForSettled(client, operationRef, output, options);
+    const status = await waitForSettled(fetch, operationRef, output, options);
     const summary = outcomeFor(status, operationRef);
     if (summary.outcome !== "running")
         return summary;
     const elapsedMs = now() - startedAt;
     return { ...summary, elapsedSeconds: Math.round(elapsedMs / 1000), nextStep: runningLine(status, elapsedMs, operationRef) };
 }
-export async function retryDeployment(client, operationRef, output, options = {}) {
-    await client.initialize();
-    const result = structured(await client.call("isomorph_retry_deployment", { operationId: operationRef }));
-    output(result.retry?.replayed ? "Isomorph had already accepted this retry." : "Isomorph accepted the deployment retry.");
+export async function retryDeployment(governance, appId, operationRef, output, options = {}) {
+    const result = await governance.retryDeployment(appId, operationRef);
+    output(result.replayed ? "Isomorph had already accepted this retry." : "Isomorph accepted the deployment retry.");
     if (options.wait === false)
-        return summarize(await fetchStatus(client, operationRef));
-    return follow(client, operationRef, output, options.waitOptions);
+        return summarize(result.status);
+    return follow(statusFetch(governance, appId, operationRef), operationRef, output, options.waitOptions);
 }
-/**
- * What governance records as the promotion attestation. `--confirm-tested` is
- * the one flag that means "the person tried the preview"; nothing is prompted
- * for, because the CLI is run by an agent and the person is in the browser.
- */
-export const PROMOTION_CONFIRMATION = "Tested.";
 /**
  * Promotion mirrors the console's "I tested this version" button: the maker
- * must have opened the live preview and say so, and the version they tested
- * is pinned so a redeployed preview is refused as stale rather than promoted
- * unseen.
+ * must have opened the live preview and say so. `--confirm-tested` is the one
+ * flag that means "the person tried the preview"; nothing is prompted for,
+ * because the CLI is run by an agent and the person is in the browser. The
+ * server pins the preview version it promotes from the operation's own live
+ * deployment and mints the attestation for the signed-in builder.
  */
-export async function promoteToProduction(client, operationRef, output, options = {}) {
-    const status = await fetchStatus(client, operationRef);
+export async function promoteToProduction(governance, appId, operationRef, app, output, options = {}) {
+    const fetch = statusFetch(governance, appId, operationRef);
+    const status = await fetch(0);
     if (status.production && !PRODUCTION_TERMINAL.has(status.production.state)) {
         output("Isomorph is already promoting this app to production.");
-        return options.wait === false ? summarize(status) : follow(client, operationRef, output, options.waitOptions);
+        return options.wait === false ? summarize(status) : follow(fetch, operationRef, output, options.waitOptions);
     }
     const deployment = status.deployment;
     if (deployment?.state !== "LIVE" || !deployment.versionId || !deployment.protectedUrl)
         throw new CliError("LIVE_PREVIEW_REQUIRED", "The preview must be live before it can be promoted. Check `isomorph status` first.", operationRef);
     if (!options.confirmedTested)
         throw new CliError("PROMOTION_NOT_CONFIRMED", `The preview has not been confirmed as tested: ${deployment.protectedUrl}`, operationRef, "Once the person has opened the preview and it works, run this again with --confirm-tested.");
-    const result = structured(await client.call("isomorph_promote_to_production", {
-        operationId: operationRef,
-        expectedPreviewVersionId: deployment.versionId,
-        confirmation: { schema: "isomorph.stage-approval/1.0", step: "confirm_preview_tested_and_promote", approved: true, approvedByUser: true, userApprovalText: PROMOTION_CONFIRMATION }
-    }));
+    const result = await governance.promoteDeployment(appId, operationRef, { tested: true, app });
     output("Isomorph accepted the production promotion.");
     if (options.wait === false)
-        return { ...summarize(status), ...(result.production ? { production: pickProduction(result.production) } : {}) };
-    return follow(client, operationRef, output, options.waitOptions);
-}
-export async function getAppSetup(client, operationRef) {
-    await client.initialize();
-    return structured(await client.call("isomorph_get_app_setup", { operationId: operationRef }));
-}
-export async function confirmProfile(client, operationRef, input, output) {
-    const setup = await getAppSetup(client, operationRef);
-    const displayName = input.displayName ?? setup.profile?.suggested?.displayName ?? setup.profile?.displayName;
-    const description = input.description ?? setup.profile?.suggested?.description ?? setup.profile?.description;
-    if (!displayName || !description)
-        throw new CliError("PROFILE_INCOMPLETE", "The app needs a name and a description in .isomorph/app.json; Isomorph had no suggestion to fall back on.", operationRef);
-    if (!setup.profile?.profileVersion)
-        throw new CliError("PROFILE_VERSION_MISSING", "Isomorph did not return the app details version.", operationRef);
-    await client.call("isomorph_confirm_app_profile", { operationId: operationRef, displayName, description, expectedVersion: setup.profile.profileVersion });
-    output(`Isomorph recorded the app's name and description: ${displayName}.`);
-    return getAppSetup(client, operationRef);
-}
-export async function confirmAudience(client, operationRef, emails, output) {
-    await client.initialize();
-    await client.call("isomorph_confirm_app_audience", { operationId: operationRef, emails });
-    output(emails.length ? `Isomorph recorded the app's audience: ${emails.length} colleague${emails.length === 1 ? "" : "s"}.` : "Isomorph recorded that only you can open the app for now.");
-    return getAppSetup(client, operationRef);
+        return summarize(result.status);
+    return follow(fetch, operationRef, output, options.waitOptions);
 }

package/dist/packages/harbour-cli/src/output.js

@@ -24,7 +24,9 @@ export function safeError(error) {
     // Paths and identifiers are a list field, never prose: `redact` bounds prose and
     // would elide the one token the reader needs. They are carried whole, always.
     const paths = error instanceof CliError && error.paths?.length ? error.paths : undefined;
-    return { code, layer, message: redact(raw) || NO_DETAIL, ...(hint ? { remediationHint: hint } : {}), ...(paths ? { paths } : {}) };
+    // Structured, so it is neither bounded nor redacted: a command's choices are its commands, and a refusal's blockers are what the reader acts on.
+    const details = error instanceof CliError && error.details && Object.keys(error.details).length ? error.details : undefined;
+    return { code, layer, message: redact(raw) || NO_DETAIL, ...(hint ? { remediationHint: hint } : {}), ...(paths ? { paths } : {}), ...(details ? { details } : {}) };
 }
 /** Anything that must never reach a terminal, a log or an envelope. */
 const SECRETS = /https?:\/\/\S+|Bearer\s+\S+|(?:x-harbour|authorization|content-type)[^\n]*/gi;
@@ -127,7 +129,11 @@ export function renderFailure(envelope) {
     const stages = ["production", "deployment"].filter(kind => result[kind]?.failure && result[kind]?.versionId).map(kind => `\n${stageLine(kind, result[kind])}`);
     // One path per line, verbatim: never through `said`, which would bound them.
     const paths = (error?.paths ?? []).map(path => `\n  ${path}`);
-    return `${error?.message ?? NO_DETAIL}${error?.remediationHint ? ` ${error.remediationHint}` : ""}${paths.join("")}${stages.join("")}\n`;
+    // A refusal's choices are commands: one per line, verbatim, however long the app root is.
+    const choices = (Array.isArray(error?.details?.choices) ? error.details.choices : [])
+        .filter(choice => typeof choice.command === "string")
+        .map(choice => `\n  ${choice.command}${typeof choice.description === "string" ? `  (${choice.description})` : ""}`);
+    return `${error?.message ?? NO_DETAIL}${error?.remediationHint ? ` ${error.remediationHint}` : ""}${paths.join("")}${choices.join("")}${stages.join("")}\n`;
 }
 /**
  * Server-supplied text on its way to a terminal, given exactly the treatment
@@ -243,6 +249,8 @@ export class CliError extends Error {
     layer;
     /** Paths and identifiers the message refers to, carried whole: the envelope never bounds them. */
     paths;
+    /** The structured half of a governance refusal (`error.details` on the wire, minus its `code`): what a caller reads to act on the refusal, never printed. */
+    details;
     /** `result` becomes the envelope's `result`: what the command knew about the operation when it failed. */
     constructor(code, message, operationRef, remediationHint, result, options = {}) {
         super(message);
@@ -252,5 +260,6 @@ export class CliError extends Error {
         this.result = result;
         this.layer = options.layer ?? layerFor(code);
         this.paths = options.paths?.length ? [...options.paths] : undefined;
+        this.details = options.details;
     }
 }