@isomorph.ai/cli 0.3.4 → 0.4.0-rc.1

package/dist/packages/harbour-cli/src/{productionise.js → deploy.js}

@@ -1,22 +1,28 @@
 import { homedir } from "node:os";
 import { basename, dirname, parse, resolve } from "node:path";
-import { readdir, readFile, mkdir, rename, writeFile } from "node:fs/promises";
+import { readFile, mkdir, rename, writeFile } from "node:fs/promises";
 import { scanWorkspace } from "../../../src/analyzer.js";
 import { createSourceManifest } from "../../../src/source-intake.js";
 import { structured } from "./remote-mcp-client.js";
 import { archiveForManifest, putMultipart } from "./upload.js";
 import { CliError } from "./output.js";
-import { confirmAudience, confirmProfile, follow, getAppSetup, pickSourceFailure, readLine, fetchStatus, outcomeFor } from "./operations.js";
+import { confirmAudience, confirmProfile, follow, pickSourceFailure, fetchStatus, outcomeFor } from "./operations.js";
 import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
-import { assertAiReady, assertPreviewIntegrationsReady } from "./integrations.js";
-import { describeSourceChange, kitPaths, readKitLock, recordKitAppId, sourceDigest } from "./kit.js";
-import { FLOW_CHECK, preflightKitGate, readReport } from "./check.js";
-/** What the maker types at the save prompt; `--confirm-save` supplies this same literal, so the
- * `isomorph.stage-approval/1.0` attestation governance receives is unchanged, byte for byte. */
+import { assertDeployReady, ensureLinkedApp } from "./integrations.js";
+import { describeSourceChange, readAppProfile, readKitLock, recordKitAppId, sourceDigest } from "./kit.js";
+import { CHECKS_FAILED_HINT, checksFailedMessage, FLOW_CHECK, readReport, runChecks } from "./check.js";
+import { runCommand } from "./local-runtime.js";
+import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
+/**
+ * The save attestation governance records (`isomorph.stage-approval/1.0`). The
+ * CLI is run by an agent, so no terminal prompt stands between the command and
+ * this reply: the person's confirmation is the `.isomorph/app.json` review the
+ * agent shows them before running `deploy`, and the wire schema is unchanged.
+ */
 export const SAVE_APPROVAL = "Approved.";
-export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
-    const deployment = await deploy(rootArg, client, output, tenantId, includePaths, options);
+export async function deploy(rootArg, client, output, tenantId, options = {}) {
+    const deployment = await runDeploy(rootArg, client, output, tenantId, options);
     await reportSession(rootArg, deployment.operationRef, options);
     return deployment;
 }
@@ -42,11 +48,20 @@ async function reportSession(rootArg, operationRef, options) {
     }
     catch { /* never surfaced: the deployment is what the builder asked for. */ }
 }
-async function deploy(rootArg, client, output, tenantId, includePaths = [], options = {}) {
+async function runDeploy(rootArg, client, output, tenantId, options = {}) {
     const root = resolve(rootArg);
     output(`Isomorph is checking ${basename(root)}.`);
     if (root === parse(root).root || root === resolve(homedir()))
         throw new CliError("PREFLIGHT_APP_ROOT", "The selected app boundary is unsafe.");
+    // Only a kit app deploys from here: the checks, the gate and the profile all
+    // live in `.isomorph/`. Anything else deploys from the console.
+    if (!(await readKitLock(root)))
+        throw new CliError("KIT_REQUIRED", "This folder is not an Isomorph app: it has no .isomorph/kit.lock.json.", undefined, "Run `isomorph init --app-root .` first.");
+    // The three values the person confirmed, printed so the transcript shows what
+    // was recorded; recorded on the operation before anything is uploaded.
+    const profile = await readAppProfile(root);
+    for (const line of describeProfile(profile))
+        output(line);
     let pending = await readPending(root, tenantId, client.endpoint);
     let prior;
     if (pending) {
@@ -72,7 +87,7 @@ async function deploy(rootArg, client, output, tenantId, includePaths = [], opti
                 throw new CliError("RECOVERY_UNAVAILABLE", "This company needs Isomorph's deployment recovery update before shipping. No new deployment was started.");
             if (recovered.operation?.operationId && !operationFinished(recovered)) {
                 prior = recovered;
-                pending = { tenantId, endpoint: client.endpoint, operationRef: recovered.operation.operationId, sourceDigest: (await sourceDigest(root)).digest, uploaded: Boolean(recovered.sourceSave || recovered.deployment || recovered.waiting || recovered.operation.stage === "awaiting-approval"), graph: await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) }), appId };
+                pending = { tenantId, endpoint: client.endpoint, operationRef: recovered.operation.operationId, sourceDigest: (await sourceDigest(root)).digest, uploaded: Boolean(recovered.sourceSave || recovered.deployment || recovered.waiting || recovered.operation.stage === "awaiting-approval"), graph: await scanWorkspace(root, { sourceBoundary: "root" }), appId };
                 await writePending(root, pending);
             }
         }
@@ -86,55 +101,34 @@ async function deploy(rootArg, client, output, tenantId, includePaths = [], opti
     if (pending && !pending.uploaded && pending.sourceDigest !== (await sourceDigest(root)).digest) {
         throw new CliError("UPLOAD_SOURCE_CHANGED", "The app changed before its upload finished. Restore the submitted files before continuing this operation.", pending.operationRef);
     }
-    const scan = () => scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) });
-    let graph = pending?.graph ?? await scan();
+    // Link first: the app's identity lands in `.isomorph/kit.lock.json`, which is
+    // one of the deployable files, so a report pinned after the link stays fresh
+    // through the pre-flight and a refusal there does not cost a second gate run.
+    if (!pending?.uploaded && options.integrations)
+        await ensureLinkedApp(root, options.integrations.governance, tenantId, options.integrations.bundle);
+    // The app's own checks are the cheapest gate Isomorph has and the most
+    // expensive one to discover in the cloud. Measured: a builder shipped without
+    // running `isomorph check`, the retained checks no longer matched the code,
+    // and the pipeline's `flow` gate refused it twice — 2m23s and 2m12s per
+    // discovery — for a mismatch `isomorph check` names locally in seconds. A
+    // report that passed for these exact bytes is trusted as it stands; anything
+    // else runs the checks here, once, before the tree is read into memory and
+    // long before any grant lookup, operation or upload. The gate writes into
+    // `.isomorph/` as it runs, so the tree is scanned only after it.
+    if (!pending?.uploaded)
+        await ensureChecksPassed(root, output, options);
+    const graph = pending?.graph ?? await scanWorkspace(root, { sourceBoundary: "root" });
     if (!graph.deploymentScope.includedFiles.length)
         throw new CliError("PREFLIGHT_EMPTY", "The selected app boundary contains no eligible files.");
     if (graph.deploymentScope.includedFiles.some(isProhibitedSecretPath))
         throw new CliError("PREFLIGHT_SECRET_PATH", "The selected app boundary contains a prohibited secret file.");
-    // The app's own retained checks are the cheapest gate Isomorph has and the
-    // most expensive one to discover in the cloud. Measured: a builder shipped
-    // without running `isomorph check`, the retained checks no longer matched the
-    // code, and the pipeline's `flow` gate refused it twice — 2m23s and 2m12s per
-    // discovery — for a mismatch `isomorph check` names locally in about five
-    // seconds. Refuse here, before the tree is even read into memory, and long
-    // before any grant lookup, database replay, operation or upload.
-    if (!pending?.uploaded)
-        await assertChecksPassedForTree(root, output);
-    const readTree = async () => pending?.uploaded ? [] : await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
-    let files = await readTree();
+    const files = pending?.uploaded ? [] : await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
     output(`Isomorph found ${graph.deploymentScope.includedFiles.length} app files.`);
-    // A declared connection IT has not approved yet would only park the
-    // deployment after the save; file the request and refuse here, before any operation exists.
-    const kitAppId = pending?.appId ?? (options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId);
-    // An app that calls governed AI needs the company's AI setup to pass the
-    // deployment PLAN; ask governance now rather than discover it on the deployed button.
-    if (!pending?.uploaded && options.integrations && kitAppId && await appCallsAi(root))
-        await assertAiReady(kitAppId, "preview", options.integrations.governance, output);
-    // A kit app the pipeline's gate would refuse (a table without RLS, an
-    // operation no journey exercises, a cross-user leak) is refused here,
-    // before the save, by the same gate with the same wording.
-    const gate = options.kitGate === false ? undefined : options.kitGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
-    if (gate && !pending?.uploaded) {
-        await preflightKitGate(root, gate.bundle, output, gate.run);
-        // The gate AUTHORS `.isomorph/checks/*.mjs` — the retained journeys the cloud replays. On an app
-        // that has never run `isomorph check` on its own they did not exist when the tree was scanned
-        // above, so the package shipped without them and the cloud gate, which has no journeys to run,
-        // refused every write the source performs as unexercised. Locally the same gate had just
-        // generated and passed them, so the app looked ready and the refusal named `src/App.tsx` rather
-        // than the missing files (2026-09-15). Re-read the tree the gate leaves behind.
-        if (!pending) {
-            graph = await scan();
-            files = await readTree();
-        }
-    }
-    // The journeys are the app's proof for the cloud gate; a package without the ones on disk is
-    // refused there, minutes later, in terms that point at the app instead of the package.
-    const packaged = new Set(graph.deploymentScope.includedFiles);
-    const unpackaged = (await retainedChecks(root)).filter(name => !packaged.has(`.isomorph/checks/${name}`));
-    if (!pending?.uploaded && unpackaged.length) {
-        throw new CliError("CHECKS_NOT_PACKAGED", `The app package does not carry its retained check${unpackaged.length === 1 ? "" : "s"} (${nameList(unpackaged)}), so the deployment would have nothing to replay.`, undefined, "Run `isomorph check --app-root .`, then run this again.");
-    }
+    // A declared connection IT has not approved, a company whose AI setup is not
+    // ready for an app that calls it, or a CLI the platform no longer accepts would
+    // only park the deployment after the save: ask governance once, here, before
+    // any operation exists, and refuse with every blocker at once.
+    const kitAppId = pending?.appId ?? (options.integrations ? await assertDeployReady(root, options.integrations.governance, tenantId, options.integrations.bundle, "preview", output, await appCallsAi(root)) : options.appId);
     // A `CliError` is Isomorph's own answer (`AUTH_REQUIRED` after two 401s, a
     // JSON-RPC refusal) and reaches the builder as it is; only a plain Error from
     // the transport — Isomorph out of reach — is "not started". Reporting a
@@ -149,13 +143,16 @@ async function deploy(rootArg, client, output, tenantId, includePaths = [], opti
     }
     let start;
     const linked = kitAppId ? { appId: kitAppId } : {};
+    // TODO(kit-band-a): every call below sends `surface: "codex"`. `src/mcp.ts` validates `surface`
+    // against its SURFACES enum (codex, claude_code, lovable, replit, v0, other), which has no "cli"
+    // member yet; send "cli" once the server accepts it.
     try {
         start = pending ? { operation: { operationId: pending.operationRef } } : structured(await client.call("isomorph_start_productionization", { appPath: basename(root), appName: basename(root), surface: "codex", ...linked }));
     }
     catch (error) {
         if (error instanceof CliError)
             throw error;
-        throw new CliError("START_UNCONFIRMED", "Isomorph did not confirm the start response. Run productionise again to recover the app operation before starting another deployment.");
+        throw new CliError("START_UNCONFIRMED", "Isomorph did not confirm the start response. Run deploy again to recover the app operation before starting another deployment.");
     }
     const operationRef = start.operation?.operationId;
     if (!operationRef)
@@ -176,9 +173,10 @@ async function deploy(rootArg, client, output, tenantId, includePaths = [], opti
                 throw new CliError("APP_IDENTITY_MISMATCH", "Isomorph returned a different app identity than the one linked in .isomorph/kit.lock.json.", operationRef);
             pending = { ...pending, appId };
             await writePending(root, pending);
-            if (options.confirmedAppSetup && !pending.appSetupConfirmed) {
-                await confirmProfile(client, operationRef, options.confirmedAppSetup, output);
-                await confirmAudience(client, operationRef, options.confirmedAppSetup.audienceEmails, output);
+            if (!pending.appSetupConfirmed) {
+                // An empty description defers to Isomorph's suggestion; a blank name never reaches here (readAppProfile).
+                await confirmProfile(client, operationRef, { displayName: profile.name, ...(profile.description ? { description: profile.description } : {}) }, output);
+                await confirmAudience(client, operationRef, profile.audience, output);
                 pending = { ...pending, appSetupConfirmed: true };
                 await writePending(root, pending);
             }
@@ -223,11 +221,8 @@ async function deploy(rootArg, client, output, tenantId, includePaths = [], opti
             await waitForIntake(client, operationRef);
         let execution = prior?.sourceSave?.status && prior.sourceSave.status !== "AWAITING_APPROVAL" ? { status: prior.sourceSave.status } : await execute(client, operationRef, appId, graph);
         if (execution.status === "APPROVAL_REQUIRED" || execution.approvalRequiredBeforeExternalAction === true) {
-            output(`Approval required: Isomorph can copy ${graph.deploymentScope.includedFiles.length} app files to the approved company code system. Nothing will be deployed or released. Type Approved. then press Enter.`);
-            const approval = await (options.readApproval ?? readLine)();
-            if (approval !== SAVE_APPROVAL)
-                throw new CliError("APPROVAL_NOT_GRANTED", "The Isomorph save was not approved. Approve copying the app files with --confirm-save instead.", operationRef);
-            execution = await execute(client, operationRef, appId, graph, { schema: "isomorph.stage-approval/1.0", step: "save_source_baseline", approved: true, approvedByUser: true, userApprovalText: approval, userVisibleProgress: "Approved.", nextStepSummary: "Isomorph can safely save the app.", dataOrActions: ["Save the app in the company code system."] });
+            output(`Isomorph is copying ${graph.deploymentScope.includedFiles.length} app files to the approved company code system. Nothing is deployed or released by that.`);
+            execution = await execute(client, operationRef, appId, graph, { schema: "isomorph.stage-approval/1.0", step: "save_source_baseline", approved: true, approvedByUser: true, userApprovalText: SAVE_APPROVAL, userVisibleProgress: SAVE_APPROVAL, nextStepSummary: "Isomorph can safely save the app.", dataOrActions: ["Save the app in the company code system."] });
         }
         if (execution.status === "ADMIN_SETUP_REQUIRED")
             throw new CliError("ADMIN_SETUP_REQUIRED", "The company code connection needs one-time administrator setup.", operationRef);
@@ -247,14 +242,8 @@ async function deploy(rootArg, client, output, tenantId, includePaths = [], opti
         throw await operationFailure(client, operationRef, error);
     }
 }
-/**
- * What a builder is told to do when the checks have not passed. `isomorph check`
- * exercises the retained journeys and the pipeline's operation-coverage gate
- * against the running app, so both commands are named: the app has to be up
- * before the checks that matter can run at all.
- */
-const RUN_THE_CHECKS = "Run `isomorph check --app-root .` (it starts the local Isomorph services itself when `isomorph dev` is not running). Fix whatever it reports, then run this again.";
-const FIX_THE_CHECKS = "Fix what the checks reported (the detail is in .isomorph/local/check-report.json), then run `isomorph check --app-root .` again.";
+/** What a builder is told to do when the checks failed here: the detail is in the report; fix, then run again. */
+const FIX_THE_CHECKS = "Fix what the checks reported, then run this again.";
 /**
  * The checks the deployment pipeline replays in the cloud: each retained
  * journey under its own `journey:<file>` name and the operation-coverage gate
@@ -265,71 +254,70 @@ const FIX_THE_CHECKS = "Fix what the checks reported (the detail is in .isomorph
 function isReplayedGate(name) {
     return name === FLOW_CHECK || name.startsWith("journey:");
 }
-/** The retained checks this app keeps, enumerated exactly as `isomorph check` and the pipeline enumerate them. */
-async function retainedChecks(root) {
-    return (await readdir(kitPaths(root).checks).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
-}
-/** At most three names, so one long list of journey files cannot push the reason itself past the report cap. */
-function nameList(names) {
-    return names.length > 3 ? `${names.slice(0, 3).join(", ")} and ${names.length - 3} more` : names.join(", ");
+/**
+ * The gates that matter, as a report records them: the replayed gates that did
+ * not pass (`not_run` is a skip, never a pass), or none.
+ */
+function skippedGates(report) {
+    const checks = Array.isArray(report.checks) ? report.checks : [];
+    const notRun = checks.filter(check => isReplayedGate(check.name) && check.status !== "pass").map(check => check.name);
+    const flowRan = checks.some(check => check.name === FLOW_CHECK && check.status === "pass");
+    return notRun.length || flowRan ? notRun : [FLOW_CHECK];
 }
 /**
- * Refuses a tree whose own retained checks have not passed *for that tree*.
+ * Makes sure the checks have passed *for this tree*, running them when they
+ * have not.
  *
  * `isomorph check` writes `.isomorph/local/check-report.json` with the digest of
- * the source it ran against, so three different things have to be true before a
- * deployment is worth anyone's time: the checks ran, they ran against these
- * bytes, and the ones that matter actually ran rather than being skipped.
- *
- * Scope: an app that keeps no retained checks is not gated. This is not a
- * loophole — `.isomorph/checks/` is what the pipeline replays, and an app that
- * keeps none is refused there by the same coverage gate the moment its code
- * performs any operation. Gating it here would only refuse, with a fix it
- * cannot carry out, every app that never adopted the kit.
+ * the source it ran against. A report is trusted when three things are true:
+ * the checks ran, they ran against these bytes, and the ones that matter
+ * actually ran rather than being skipped. Then nothing is run again — the gate
+ * takes 30–60 s and its answer for the same bytes is the same. Any other state
+ * (no report, a different tree, a skipped gate) runs the same checks `isomorph
+ * check` runs and carries on in this invocation; a report that ran and failed
+ * is refused as it stands, since running it again changes nothing.
  *
  * The digest is recomputed by the same `sourceDigest` `isomorph check` used, so
  * a match means one function saw the same bytes twice and no parallel
- * implementation can drift into refusing a checked tree. It spans the whole app
- * boundary, so a `--include` submission is compared against the tree the checks
- * actually ran on: conservative where the two differ, never permissive.
+ * implementation can drift into refusing a checked tree.
  */
-async function assertChecksPassedForTree(root, output) {
-    const retained = await retainedChecks(root);
-    if (!retained.length)
-        return;
-    const plural = retained.length === 1 ? "" : "s";
-    const report = await readReport(root);
-    if (!report)
-        throw new CliError("CHECKS_NOT_RUN", `This app keeps ${retained.length} check${plural} that say whether it still works, and ${retained.length === 1 ? "it has" : "they have"} never been run against this code. Isomorph does not deploy an app whose own checks have not passed.`, undefined, RUN_THE_CHECKS);
+async function ensureChecksPassed(root, output, options) {
+    const previous = await readReport(root);
     const tree = await sourceDigest(root);
-    if (report.sourceDigest !== tree.digest) {
-        // Name the paths. Without them the refusal is true but unactionable: a
+    if (previous && previous.sourceDigest === tree.digest) {
+        const checks = Array.isArray(previous.checks) ? previous.checks : [];
+        const failed = checks.filter(check => check.status === "fail").map(check => check.name);
+        if (failed.length || previous.passed !== true)
+            throw new CliError("CHECKS_FAILED", `The app's own checks last ran and did not pass${failed.length ? ` (${failed.length} check${failed.length === 1 ? "" : "s"})` : ""}. Isomorph does not deploy an app whose checks are failing; the deployment pipeline would refuse it too.`, undefined, FIX_THE_CHECKS, undefined, { paths: failed });
+        const skipped = skippedGates(previous);
+        if (!skipped.length) {
+            output(`The app's own checks passed for this exact code (last run ${previous.createdAt}).`);
+            return;
+        }
+        output(`The last check run skipped ${skipped.join(", ")}; running the checks again.`);
+    }
+    else if (previous) {
+        // Name the paths. Without them the line is true but unactionable: a
         // builder whose agent wrote scratch files into a gitignored folder inside
         // the app root hit this three times before finding the folder, because
         // everything inside the root is inside the deployment boundary whether git
-        // tracks it or not. Reports written before CLI 0.3.4 carry no file hashes,
-        // so the sentence degrades to what it always said.
-        // The paths lead, and the whole sentence stays inside output.ts's
-        // DETAIL_BOUND. That bound keeps both ENDS and elides the middle, precisely
-        // because a filename once sat at index 266 and was never printed — so a
-        // path placed mid-sentence is put in the one position the bounding deletes.
-        const moved = describeSourceChange(report.sourceFiles, tree.entries);
-        throw new CliError("CHECKS_STALE", `The app's code has changed since its checks last ran${moved ? ` (${moved})` : ""}. Isomorph does not deploy an app whose checks have not passed for this exact code; everything inside the app folder counts, including files git ignores.`, undefined, RUN_THE_CHECKS);
-    }
-    const checks = Array.isArray(report.checks) ? report.checks : [];
-    const failed = checks.filter(check => check.status === "fail").map(check => check.name);
-    if (failed.length || report.passed !== true)
-        throw new CliError("CHECKS_FAILED", `The app's own checks last ran and did not pass${failed.length ? ` (${nameList(failed)})` : ""}. Isomorph does not deploy an app whose checks are failing; the deployment pipeline would refuse it too.`, undefined, FIX_THE_CHECKS);
-    // "Skipped" is not "passed". A report whose journeys and coverage gate never
-    // ran says nothing about whether the app works, and accepting it would hand
-    // the discovery straight back to the pipeline.
-    const notRun = checks.filter(check => isReplayedGate(check.name) && check.status !== "pass").map(check => check.name);
-    const flowRan = checks.some(check => check.name === FLOW_CHECK && check.status === "pass");
-    if (notRun.length || !flowRan) {
-        const names = notRun.length ? notRun : [FLOW_CHECK];
-        throw new CliError("CHECKS_NOT_RUN", `The last check run skipped ${nameList(names)} instead of passing ${names.length === 1 ? "it" : "them"}. The deployment pipeline runs the same ones in the cloud, so skipping them here only moves the failure.`, undefined, RUN_THE_CHECKS);
+        // tracks it or not.
+        const moved = describeSourceChange(previous.sourceFiles, tree.entries);
+        output(`The app's code has changed since its checks last ran${moved ? ` (${moved})` : ""}; running the checks first.`);
     }
-    output(`The app's own checks passed for this exact code (${retained.length} retained check${plural}, last run ${report.createdAt}).`);
+    else
+        output("The app's checks have not run for this code yet; running them first.");
+    const report = await (options.checks?.runChecks ?? defaultRunChecks(options))(root, output);
+    if (!report.passed)
+        throw new CliError("CHECKS_FAILED", checksFailedMessage(report), undefined, CHECKS_FAILED_HINT, undefined, { paths: report.checks.filter(check => check.status === "fail").map(check => check.name) });
+    const skipped = skippedGates(report);
+    if (skipped.length)
+        throw new CliError("CHECKS_NOT_RUN", `The checks skipped ${skipped.length} gate${skipped.length === 1 ? "" : "s"} instead of passing ${skipped.length === 1 ? "it" : "them"}. The deployment pipeline runs the same ones in the cloud, so skipping them here only moves the failure.`, undefined, "Start `isomorph dev --app-root .`, run `isomorph check --app-root .`, then run this again.", undefined, { paths: skipped });
+}
+/** The checks as `isomorph check` runs them, with the bundle this deploy carries. */
+function defaultRunChecks(options) {
+    const bundle = options.integrations?.bundle ?? EMBEDDED_KIT_BUNDLE;
+    return (root, output) => runChecks(root, { run: options.checks?.run ?? runCommand, bundle, output });
 }
 async function waitForIntake(client, operationRef) {
     for (let attempt = 0; attempt < 60; attempt += 1) {
@@ -359,7 +347,7 @@ function intakeRejection(status, operationRef) {
  * generic pair only where it gave nothing, and the operation reference always.
  */
 function refusal(failure, fallbackCode, fallbackMessage, operationRef) {
-    return new CliError(failure?.code ?? fallbackCode, failure?.message ?? fallbackMessage, operationRef, failure?.remediationHint);
+    return new CliError(failure?.code ?? fallbackCode, failure?.message ?? fallbackMessage, operationRef, failure?.remediationHint, undefined, { layer: "governance" });
 }
 /**
  * Why the whole operation stopped. The outer catch used to answer this with one
@@ -370,24 +358,14 @@ function refusal(failure, fallbackCode, fallbackMessage, operationRef) {
  *
  *  1. A `CliError` already carries a reason; keep it, and only make sure it
  *     names the operation, since by here one exists.
- *  2. The operation is not failed at all but waiting for its profile, audience
- *     or secrets — say what is pending and which commands supply it.
- *  3. Otherwise the thrown value's own detail, then the refusal intake recorded
+ *  2. Otherwise the thrown value's own detail, then the refusal intake recorded
  *     on the operation, and only then the generic line.
  */
 async function operationFailure(client, operationRef, error) {
     if (error instanceof CliError)
-        return error.operationRef ? error : new CliError(error.code, error.message, operationRef, error.remediationHint, error.result);
+        return error.operationRef ? error : withOperation(error, operationRef);
     const detail = errorDetail(error);
-    const state = await probeOperation(client, operationRef);
-    // A pending-setup operation is not a failed operation: nothing is wrong with
-    // it and re-running `productionise` after the setup commands carries it on.
-    // It is still a failed *command* — no app was saved, verified or deployed —
-    // so it keeps a non-zero exit rather than reporting a success that did not
-    // happen, and carries the real next step instead of a bare code.
-    if (state.pending.length)
-        return new CliError(detail?.code ?? "SETUP_REQUIRED", state.plainEnglish ?? pendingSentence(state.pending), operationRef, setupRemediation(operationRef));
-    return refusal(detail ?? state.failure, "OPERATION_FAILED", "Isomorph could not complete the started operation.", operationRef);
+    return refusal(detail ?? await recordedFailure(client, operationRef), "OPERATION_FAILED", "Isomorph could not complete the started operation.", operationRef);
 }
 /**
  * What the thrown value itself says. A refusal reaches us as a bare `Error`
@@ -412,42 +390,18 @@ function text(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 /**
- * What the server says about the operation once a call has failed. Both reads
- * are best-effort: the reason the builder gets must never depend on a second
- * call succeeding, so a probe that fails simply contributes nothing.
+ * The refusal intake recorded on the operation, if any. Best-effort: the reason
+ * the builder gets must never depend on a second call succeeding, so a probe
+ * that fails simply contributes nothing.
  */
-async function probeOperation(client, operationRef) {
-    let failure;
+async function recordedFailure(client, operationRef) {
     try {
-        failure = pickSourceFailure(structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds: 0 })));
-    }
-    catch { /* no status: fall back to what the error said */ }
-    try {
-        const setup = await getAppSetup(client, operationRef);
-        return { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}), ...(failure ? { failure } : {}) };
+        return pickSourceFailure(structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds: 0 })));
     }
     catch {
-        return { pending: [], ...(failure ? { failure } : {}) };
+        return undefined;
     }
 }
-/** The console's post-save steps, in the words the CLI already uses for them. */
-const SETUP_STEPS = {
-    confirm_app_profile: "its name and description confirmed",
-    confirm_app_audience: "its audience confirmed",
-    provide_secrets: "the secrets it asked for"
-};
-function pendingSentence(pending) {
-    return `The app still needs: ${pending.map(step => SETUP_STEPS[step] ?? step).join("; ")}.`;
-}
-/**
- * `isomorph retry` is what the help offers for resuming an operation, but it
- * restarts a deployment — on an operation still waiting for its setup there is
- * no deployment to restart, and running `productionise` again is what carries
- * it on. Name the commands that actually work, and say which one does not.
- */
-function setupRemediation(operationRef) {
-    return `Run \`isomorph profile\` and \`isomorph audience\`, then \`isomorph productionise\` again — not \`isomorph retry\`. Full list: \`isomorph setup --operation ${operationRef}\`.`;
-}
 async function execute(client, operationRef, appId, graph, approval) {
     const args = { operationId: operationRef, appId, surface: "codex", graph, action: "save_baseline", mode: "EXECUTE" };
     if (approval)
@@ -478,9 +432,9 @@ async function waitForSave(client, operationRef, graph, first, output) {
 function boundedWait(value) {
     return Math.min(15, Math.max(0, Number.isFinite(value) ? Math.floor(value) : 15));
 }
-/** Isomorph accepts dotted MCP names (its handler keys) while publishing portable underscore names. */
+/** Isomorph publishes and accepts exactly one tool spelling, `isomorph_<verb>`; a next step is compared as it is. */
 function matchesTool(actual, expected) {
-    return actual.replaceAll(".", "_") === expected;
+    return actual === expected;
 }
 function safeVerificationResult(value, statusEvidence) {
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -538,18 +492,11 @@ async function finishDeployment(client, operationRef, output, options, verificat
         throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Isomorph could not follow the existing operation (${error instanceof Error ? error.message.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").slice(0, 160) : "unknown error"}). Check again with \`isomorph status\`.`, operationRef);
     }
     output(outcomeLine(summary));
-    // The console asks for the app's name, audience and secrets before it
-    // offers promotion; say what is still open so a CLI-only builder knows.
-    let setup;
-    try {
-        setup = await getAppSetup(client, operationRef);
-    }
-    catch {
-        setup = undefined;
-    }
-    if (setup?.pending?.length)
-        output(`${setup.nextAction?.plainEnglish ?? "The app still needs setup."} Run \`isomorph setup --operation ${operationRef}\`.`);
-    return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...summary, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
+    return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...summary } };
+}
+/** The three values as the command prints them before it starts. */
+export function describeProfile(profile) {
+    return [`App name: ${profile.name}`, `Description: ${profile.description || "(none yet; Isomorph suggests one)"}`, `Audience: ${profile.audience.length ? profile.audience.join(", ") : "only you"}`];
 }
 function operationFinished(status) {
     if (status.production)
@@ -586,5 +533,5 @@ async function writePending(root, record) {
     }
 }
 function withOperation(error, operationRef) {
-    return new CliError(error.code, error.message, operationRef, error.remediationHint, error.result);
+    return new CliError(error.code, error.message, operationRef, error.remediationHint, error.result, { layer: error.layer, ...(error.paths ? { paths: error.paths } : {}) });
 }

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

@@ -1,13 +1,17 @@
 import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { createForwarder } from "./forwarder.js";
 import { readKitLock } from "./kit.js";
 import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
-import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, nodePackageCommand, releaseDevLock, runCommand } from "./local-runtime.js";
+import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
+import { kitPaths } from "./kit.js";
 import { CliError, safeError } from "./output.js";
 /**
  * Signed in at startup: link the app and file the access request for every
  * declared connection — one per connection, approved by IT once for every
- * environment; the same filing `productionise` does — so IT's queue holds the
+ * environment; the same filing `deploy` does — so IT's queue holds the
  * ask from the first run and no command stands between the builder and the
  * approval. Returns the banner lines saying where each connection stands.
  * Never throws: `isomorph dev` runs without company access.
@@ -123,3 +127,78 @@ export async function startDev(root, options) {
         throw error instanceof CliError ? error : new CliError("DEV_FAILED", error instanceof Error ? error.message : "isomorph dev could not start.");
     }
 }
+/** Where a detached `isomorph dev` writes what the foreground one would have printed. */
+export function devLogPath(root) { return join(kitPaths(root).local, "dev.log"); }
+/**
+ * `isomorph dev --detach`: starts the services in a child that outlives this
+ * process, waits until the app answers on its origin, and returns `{origin,
+ * pid}` so the caller can print it and exit. Every bench run before this
+ * showed the same 3–5 turn stall — start dev in the background, sleep, tail a
+ * log to find the port — for information `dev.lock` already held.
+ *
+ * The child is the ordinary foreground `dev` (same code path, same lock, same
+ * `isomorph stop`); it only has its stdio pointed at `.isomorph/local/dev.log`
+ * and is unref'd so this process can exit. An app already running is answered
+ * from its lock rather than started twice. The origin is "up" when
+ * `/_harbour/identity/current` answers: the forwarder is listening and the
+ * gateway behind it has the session identity, which is what the app's first
+ * request needs.
+ */
+export async function detachDev(root, options) {
+    const readLock = options.readLock ?? readDevLock;
+    const isAlive = options.isAlive ?? pidAlive;
+    const fetchImpl = options.fetch ?? fetch;
+    const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const appId = async () => (await readKitLock(root).catch(() => undefined))?.appId || undefined;
+    const answered = async (origin) => { try {
+        return (await fetchImpl(`${origin}/_harbour/identity/current`)).status < 500;
+    }
+    catch {
+        return false;
+    } };
+    const running = await readLock(root);
+    if (running && isAlive(running.pid) && await answered(running.origin)) {
+        options.output(`Isomorph dev is already running: ${running.origin} (pid ${running.pid}).`);
+        const linked = await appId();
+        return { origin: running.origin, pid: running.pid, ...(linked ? { appId: linked } : {}) };
+    }
+    await mkdir(kitPaths(root).local, { recursive: true });
+    const logFd = openSync(devLogPath(root), "w");
+    let exited;
+    let child;
+    try {
+        child = (options.spawnDev ?? spawnForegroundDev(options.reset ?? false))(root, logFd);
+        child.on("exit", code => { exited = code ?? -1; });
+        child.unref();
+    }
+    finally {
+        closeSync(logFd);
+    }
+    options.output(`Starting Isomorph dev in the background (pid ${child.pid ?? "?"}); its output goes to .isomorph/local/dev.log.`);
+    const deadline = Date.now() + (options.timeoutMs ?? 5 * 60_000);
+    while (Date.now() < deadline) {
+        const lock = await readLock(root);
+        if (lock && (lock.pid === child.pid || isAlive(lock.pid)) && await answered(lock.origin)) {
+            const linked = await appId();
+            return { origin: lock.origin, pid: lock.pid, ...(linked ? { appId: linked } : {}) };
+        }
+        if (exited !== undefined)
+            throw new CliError("DEV_FAILED", `isomorph dev stopped before the app answered (exit ${exited}). ${await logTail(root)}`, undefined, "Read .isomorph/local/dev.log, fix what it reports, then run this again.");
+        await sleep(options.pollMs ?? 500);
+    }
+    throw new CliError("DEV_FAILED", "isomorph dev did not answer within the wait; it may still be starting.", undefined, `Read .isomorph/local/dev.log; run \`isomorph stop --app-root .\` and then this again.`);
+}
+/** The foreground `dev` of this same CLI, detached, with its output in the log file. */
+function spawnForegroundDev(reset) {
+    return (root, logFd) => {
+        const child = spawn(process.execPath, [...process.execArgv, process.argv[1], "dev", "--app-root", root, ...(reset ? ["--reset"] : [])], { cwd: root, detached: true, stdio: ["ignore", logFd, logFd], windowsHide: true, env: process.env });
+        child.on("error", () => undefined);
+        return child;
+    };
+}
+/** The last few lines of the detached child's log, for a refusal that has nothing else to say. */
+async function logTail(root) {
+    const text = await readFile(devLogPath(root), "utf8").catch(() => "");
+    const lines = text.trim().split("\n").filter(Boolean).slice(-3).join(" | ");
+    return lines ? `Last lines: ${lines}` : "";
+}