@fourier-labs/harbour 0.1.23 → 0.1.24

package/dist/packages/harbour-cli/src/agent-setup.js

@@ -144,23 +144,25 @@ description: Build, run, check and ship a company app on Isomorph (Harbour) from
 /** One guide, shared by the Claude Code skill and the Codex AGENTS.md block. Written for an agent working with a non-developer. */
 export const AGENT_GUIDE = `# Isomorph app kit
 
-The person you are working with may not be a developer. They say what they want in plain English; you build it with the Harbour kit and run every command yourself. Never ask them to type a terminal command (the one exception is sign-in, below). Never paste JSON, logs, stack traces or file contents at them. Turn every failure into one sentence about what happened and one about what happens next. Prefer \`--json\` output and read it yourself.
+The person you are working with may not be a developer. They say what they want in plain English; you build it with the Harbour kit and run every command yourself. Never ask them to type a terminal command (the one exception is sign-in, below). Turn every failure into one sentence about what happened and one about what happens next. Prefer \`--json\` output and read it yourself; never paste JSON, logs, stack traces or file contents at them.
 
 ## Getting ready (do this yourself, once per machine and folder)
 
-1. CLI, before \`harbour init\` or anything else: compare the installed CLI with the current release and upgrade it whenever it is behind. A CLI that merely runs is not good enough — only a current one is. \`harbour agent-setup\` prints both versions and says plainly when the installed one is missing or older (its \`--json\` result carries \`cli.upgradeRequired\` and \`cli.remediation\`); without that output, compare \`harbour --version\` with \`npx -y @fourier-labs/harbour --version\` yourself. If either says the installed one is missing or older, run \`npm i -g @fourier-labs/harbour\` and confirm \`harbour --version\` now matches, then continue. Every later command runs the *installed* CLI, so a stale one builds an app that passes every local check and is then refused by the deployment pipeline (\`kit_bundle_incompatible\`) minutes later, with nothing in the app to fix. The kit needs Node 22+ and Docker Desktop running; if Docker is missing, that is the one thing to tell them to install, in one line.
+1. CLI, before \`harbour init\` or anything else: compare the installed CLI with the current release and upgrade it whenever it is behind — a CLI that merely runs is not good enough, only a current one is. \`harbour agent-setup\` prints both versions and says plainly when the installed one is missing or older (its \`--json\` result carries \`cli.upgradeRequired\` and \`cli.remediation\`); without that output, compare \`harbour --version\` with \`npx -y @fourier-labs/harbour --version\` yourself. If either says the installed one is missing or older, run \`npm i -g @fourier-labs/harbour\` and confirm \`harbour --version\` now matches, then continue. Every later command runs the *installed* CLI, so a stale one builds an app that passes every local check and is then refused by the deployment pipeline (\`kit_bundle_incompatible\`) minutes later, with nothing in the app to fix. The kit needs Node 22+ and Docker Desktop running; if Docker is missing, that is the one thing to tell them to install, in one line.
 2. Folder: if the current folder has no \`.harbour/\` directory, run \`harbour init --app-root .\` — an empty folder gets a small starter app, an existing Vite + React app gets the kit files added and nothing overwritten. Then read the "Harbour development kit" block in CLAUDE.md / AGENTS.md; it holds the per-app rules.
 3. Sign-in, needed only for company systems and shipping: run \`harbour login\`. It opens the browser and the person finishes the sign-in there — the one step they do themselves; tell them so in one line. If login says the company is not connected yet, ask them for the Harbour link their IT/admin gave them and run \`harbour connect <link>\` first.
 
 ## What they say → what you do
 
 - "run it", "show me", "let me try it" → start \`harbour dev --app-root .\` in the background (it keeps running; the first start pulls images and takes a minute or two). Wait for the line \`Harbour dev is running: http://127.0.0.1:<port>\` and give them that link. Locally they are a fixture user; no company sign-in is needed.
-- "check it", "is it ok?", "is it ready?" → with dev running, \`harbour check --app-root . --json\`, then read \`.harbour/local/check-report.json\`. Say in plain words what passed, what failed, and the one thing to do. Failures in the app's code are yours to fix — fix, then check again.
+- "check it", "is it ok?", "is it ready?" → with dev running, \`harbour check --app-root . --json\`, then read \`.harbour/local/check-report.json\`. Failures in the app's code are yours to fix — fix, then check again until it is clean. Run the checks yourself after every change and before every ship, without being asked and without offering them as a choice.
 - "I need Slack / Gmail / the warehouse / company data" → a fresh \`harbour init\` declares no connection at all, which is why a new app ships with nothing waiting on IT. Declare the connection and only the operations the app really calls in \`.harbour/integrations.json\` (the closed set is in the per-app block), then \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\`. READY means use it now. PENDING means IT has to approve it: say "IT has to approve this; the app works without it until then", and check later with \`harbour integrations status --app-root . --json\`. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
-- "ship it", "put it online", "let my team try it" → each declared connection first needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`). Then \`harbour productionise --app-root . --wait --json\` and give them \`result.deployment.protectedUrl\`: a private preview that they, and the people they name, open after company sign-in. Keep \`operationRef\`; \`harbour setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`harbour profile\` / \`harbour audience\` / \`harbour secrets set\` fill it in. Tell them shipping takes a few minutes and what it is doing.
+- "ship it", "put it online", "let my team try it" → run \`harbour check --app-root . --json\` first and fix everything it finds, every time, unasked: the same gates run again in the cloud, where each failed attempt costs minutes instead of the seconds it costs here. Then each declared connection needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`), and \`harbour productionise --app-root . --wait --json\` gives them \`result.deployment.protectedUrl\`: a private preview that they, and the people they name, open after company sign-in. Keep \`operationRef\`; \`harbour setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`harbour profile\` / \`harbour audience\` / \`harbour secrets set\` fill it in.
 - "make it live for everyone", "go to production" → only after they have tried the preview: \`harbour promote --operation <ref> --json\` with the operation reference from productionise. Report the production link, or that an operator approval is pending.
 - "stop it" → \`harbour stop --app-root .\` (local data kept). \`harbour dev --reset --app-root .\` deletes local data — only when they explicitly ask to start over.
 
+When a command refuses, the refusal names its own reason and its own fix: change that one thing, then run it again. Sending the same app again unchanged gets the same answer every time, so a repeat attempt is never the next step — and never start a second deploy of an app while one is running, because concurrent deploys of one app cancel each other.
+
 ## Building the app
 
 - Identity, data and files go through \`@harbour/app-sdk\` only: \`harbour.identity.current()\`, \`harbour.data.from(table)\`, \`harbour.files.*\`. Company systems go only through \`harbour.integrations.execute\` with declared operations. Never open a database, bucket or company URL from browser code, and never add another backend, auth library or deployment config: the kit is the whole path.
@@ -172,4 +174,5 @@ The person you are working with may not be a developer. They say what they want
 ## Talking to the person
 
 - Plain words, short: "Your app is running at <link>.", "All 6 checks passed.", "One check failed: votes were not being saved — fixed, checking again.", "IT has to approve Slack; the app works without it until then."
-- Say what happens next and roughly how long it takes. Report only what you observed; if something is unknown, say so.`;
+- Say what happens next and roughly how long it takes. Report only what you observed; if something is unknown, say so.
+- End a turn with at most one question, and only when a decision is genuinely theirs to make and you cannot go on without it. Never offer to do something this guide already tells you to do unasked — do it and report what happened.`;

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

@@ -1,14 +1,96 @@
+/** The one line for a failure that arrived with no detail at all. It is a
+ * statement about what this CLI knows, not a claim about what happened, so it
+ * is safe to print when — and only when — there is genuinely nothing to show. */
+export const NO_DETAIL = "Harbour could not complete the request.";
+/**
+ * The failure as it was actually reported: the code it came with and the words
+ * it came with, redacted and capped. Nothing here infers what went wrong.
+ *
+ * Every non-`CliError` used to go through a keyword classifier over the message
+ * text, which did not merely lose the reason — it asserted false ones. A refusal
+ * reading "Harbour has no saved app for this operation yet" matched on `save`
+ * and printed as "Saving to company code storage failed safely; nothing was
+ * deployed", sending a human after a code-storage failure that never happened
+ * and leaving an agent with nothing true to act on. Detail we do not have is
+ * now reported as detail we do not have.
+ */
 export function safeError(error) {
     const code = error instanceof CliError ? error.code : "CLI_FAILED";
-    const original = error instanceof Error ? error.message : "";
-    const raw = error instanceof CliError ? error.message : friendlyMessage(original);
+    const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
     // The hint is a separate field rather than more sentence: it is often as long
     // as the message, and appending it would push the reason itself past the cap.
     const hint = error instanceof CliError && error.remediationHint ? redact(error.remediationHint) : "";
-    return { code, message: redact(raw) || "Harbour could not complete the request.", ...(hint ? { remediationHint: hint } : {}) };
+    return { code, message: redact(raw) || NO_DETAIL, ...(hint ? { remediationHint: hint } : {}) };
 }
+/** 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;
+/** The bound on one reported string. It is the width of a terminal paragraph
+ * and of a field an agent has to read in full, and it is what
+ * `tests/cli-server-failure-detail.test.ts` holds the envelope to. This change
+ * does not raise it: a bigger fixed head-cap fails again on a longer message,
+ * because the problem is which end is kept, not how much. */
+const DETAIL_BOUND = 240;
+/** Marks where this CLI cut, so neither a human nor an agent reads the two
+ * retained halves as one continuous sentence. */
+const ELISION = " \u2026 ";
+/**
+ * Redact, then bound — keeping both ends.
+ *
+ * Bounding used to be `.slice(0, DETAIL_BOUND)`: keep the head, drop the tail.
+ * Server failure text is built the other way round. The boilerplate and the
+ * error class lead; the identifying token — the file, the command, the exit
+ * status — is last. Measured 2026-09-11 on one vibecoder session: a 317-char
+ * `transform.non-retryable: kit.check-failed:` refusal named `files-journey.mjs`
+ * at index 266, and a second, independently reproduced refusal the same day put
+ * it at index 278 of 295. Both sat past 240; neither filename was ever printed.
+ * The builder repaired the wrong file twice, at 2m23s and 2m12s of pipeline.
+ *
+ * The cap did not merely shorten those messages, it removed the answer and left
+ * a grammatical sentence behind, so two engineers with full log access read
+ * "...(real App Gateway" and went hunting in CloudWatch rather than registering
+ * that the CLI had cut it.
+ *
+ * So an over-long string now keeps BOTH ends — the head carries the error class,
+ * the tail carries the file and the exit status — with `ELISION` marking the
+ * gap. `DETAIL_BOUND` is unchanged, so nothing larger reaches a terminal or an
+ * envelope than before; the same characters are spent on both ends instead of
+ * one. Every string `safeError` reports goes through here, `remediationHint`
+ * included: hints have the same shape, and the command a builder has to run is
+ * the last one in them.
+ *
+ * This reads nothing and decides nothing from the words themselves — the split
+ * is positional. Stripping "known boilerplate prefixes" was considered and
+ * rejected for exactly that reason: it needs a maintained list of the server's
+ * phrasings, it deletes words the server actually said, and it is the kind of
+ * meaning-guessing the classifier deleted above was deleted for.
+ */
 function redact(value) {
-    return value.replace(/https?:\/\/\S+|Bearer\s+\S+|(?:x-harbour|authorization|content-type)[^\n]*/gi, "").replace(/\s+/g, " ").trim().slice(0, 240);
+    const said = value.replace(SECRETS, "").replace(/\s+/g, " ").trim();
+    if (said.length <= DETAIL_BOUND)
+        return said;
+    const keep = DETAIL_BOUND - ELISION.length;
+    const headEnd = Math.floor(keep / 2);
+    return `${wholeWordsBefore(said, headEnd)}${ELISION}${wholeWordsAfter(said, said.length - (keep - headEnd))}`;
+}
+/** How far from a seam this will look for a word boundary. Bounded, so text
+ * with no spaces near the seam keeps its full share either way. */
+const SNAP = 24;
+/** `said.slice(0, end)` and `said.slice(start)`, backed off to a word boundary
+ * when the seam falls inside a word. The elision has to read as a cut: the
+ * engineer who read "(real App Gateway " went to CloudWatch rather than
+ * noticing the CLI had truncated it, and a seam that reads as a typo is the
+ * same failure in miniature. */
+function wholeWordsBefore(said, end) {
+    if (said[end] === " ")
+        return said.slice(0, end);
+    const at = said.lastIndexOf(" ", end);
+    return at > 0 && end - at <= SNAP ? said.slice(0, at) : said.slice(0, end);
+}
+function wholeWordsAfter(said, start) {
+    if (said[start - 1] === " ")
+        return said.slice(start);
+    const at = said.indexOf(" ", start);
+    return at >= 0 && at - start <= SNAP ? said.slice(at + 1) : said.slice(start);
 }
 /**
  * What a failed command reports: the JSON envelope on stdout and the line on
@@ -21,7 +103,7 @@ export function failureEnvelope(error, cliVersion) {
 }
 export function renderFailure(envelope) {
     const error = envelope.error;
-    return `${error?.message ?? "Harbour could not complete the request."}${error?.remediationHint ? ` ${error.remediationHint}` : ""}\n`;
+    return `${error?.message ?? NO_DETAIL}${error?.remediationHint ? ` ${error.remediationHint}` : ""}\n`;
 }
 /** Human-readable stdout for runs without `--json`: the operation reference and
  * whatever link or next step Harbour reported, nothing internal. */
@@ -85,14 +167,3 @@ export class CliError extends Error {
         this.remediationHint = remediationHint;
     }
 }
-function friendlyMessage(message) {
-    if (/connect|connection profile|tenant|company/i.test(message))
-        return "This company is not connected to Harbour yet.";
-    if (/sign-in|oauth|authorize|token|invalid_scope|redirect|callback|403|401/i.test(message))
-        return "Please sign in to Harbour. If sign-in still fails, your account may not be allowed for this company yet.";
-    if (/unsafe|secret|changed|digest|manifest|archive/i.test(message))
-        return "Harbour found unsafe or changed files and stopped safely.";
-    if (/source|save|worker|provider|github/i.test(message))
-        return "Saving to company code storage failed safely; nothing was deployed.";
-    return "Harbour could not complete the request.";
-}

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

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { basename, parse, resolve } from "node:path";
-import { readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { scanWorkspace } from "../../../src/analyzer.js";
 import { createSourceManifest } from "../../../src/source-intake.js";
 import { structured } from "./remote-mcp-client.js";
@@ -10,8 +10,8 @@ import { getAppSetup, outcomeFor, pickSourceFailure, readLine, waitForSettled }
 import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertPreviewIntegrationsReady } from "./integrations.js";
-import { recordKitAppId } from "./kit.js";
-import { preflightDatabaseGate } from "./check.js";
+import { kitPaths, recordKitAppId, sourceDigest } from "./kit.js";
+import { preflightDatabaseGate, readReport } from "./check.js";
 export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
     const root = resolve(rootArg);
     output(`Harbour is checking ${basename(root)}.`);
@@ -22,6 +22,14 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         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 Harbour has and the
+    // most expensive one to discover in the cloud. Measured: a builder shipped
+    // without running `harbour 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 `harbour 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.
+    await assertChecksPassedForTree(root, output);
     const files = await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
     output(`Harbour found ${files.length} app files.`);
     // A declared connection without its preview grant would only park the
@@ -123,11 +131,82 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...outcome.summary, outcome: outcome.kind, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
     }
     catch (error) {
-        if (error instanceof CliError || (error && typeof error === "object" && "code" in error))
-            throw error;
-        throw new CliError("OPERATION_FAILED", "Harbour could not complete the started operation.", operationRef);
+        throw await operationFailure(client, operationRef, error);
     }
 }
+/**
+ * What a builder is told to do when the checks have not passed. `harbour 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 = "Start the app with `harbour dev --app-root .`, then run `harbour check --app-root .` in a second terminal. Fix whatever it reports, then run this again.";
+const FIX_THE_CHECKS = "Fix what the checks reported (the detail is in .harbour/local/check-report.json), then run `harbour check --app-root .` again with `harbour dev --app-root .` running.";
+/**
+ * The checks the deployment pipeline replays in the cloud, and the only ones
+ * `harbour check` cannot run without `harbour dev` up. They are recorded as
+ * `not_run` — not as a pass — when the app was not running, which is exactly
+ * the state that used to reach the pipeline and fail there. `journeys` is the
+ * placeholder name the report uses when none of them ran; each journey that did
+ * run is recorded under its own `journey:<file>` name.
+ */
+function isReplayedGate(name) {
+    return name === "flow" || name === "journeys" || name.startsWith("journey:");
+}
+/** The retained checks this app keeps, enumerated exactly as `harbour 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(", ");
+}
+/**
+ * Refuses a tree whose own retained checks have not passed *for that tree*.
+ *
+ * `harbour check` writes `.harbour/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 — `.harbour/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 digest is recomputed by the same `sourceDigest` `harbour 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.
+ */
+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. Harbour does not deploy an app whose own checks have not passed.`, undefined, RUN_THE_CHECKS);
+    const tree = await sourceDigest(root);
+    if (report.sourceDigest !== tree.digest)
+        throw new CliError("CHECKS_STALE", "The app's code has changed since its checks last ran, so that result no longer describes what would be deployed. Harbour does not deploy an app whose own checks have not passed for this exact code.", undefined, RUN_THE_CHECKS);
+    const checks = Array.isArray(report.checks) ? report.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" && check.status !== "fail").map(check => check.name);
+    const flowRan = checks.some(check => check.name === "flow" && (check.status === "pass" || check.status === "fail"));
+    if (notRun.length || !flowRan) {
+        const names = notRun.length ? notRun : ["flow"];
+        throw new CliError("CHECKS_NOT_RUN", `The last check run skipped ${nameList(names)} instead of passing ${names.length === 1 ? "it" : "them"}: ${names.length === 1 ? "that check needs" : "those checks need"} the app running. The deployment pipeline runs the same ones in the cloud, so skipping them here only moves the failure.`, undefined, RUN_THE_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)})` : ""}. Harbour does not deploy an app whose checks are failing; the deployment pipeline would refuse it too.`, undefined, FIX_THE_CHECKS);
+    output(`The app's own checks passed for this exact code (${retained.length} retained check${plural}, last run ${report.createdAt}).`);
+}
 async function waitForIntake(client, operationRef) {
     for (let attempt = 0; attempt < 60; attempt += 1) {
         const status = structured(await client.call("harbour_get_operation_status", { operationId: operationRef, waitSeconds: 3 }));
@@ -147,8 +226,102 @@ async function waitForIntake(client, operationRef) {
  * any detail at all.
  */
 function intakeRejection(status, operationRef) {
-    const failure = pickSourceFailure(status);
-    return new CliError(failure?.code ?? "PACKAGE_REJECTED", failure?.message ?? "Harbour could not safely accept this app package.", operationRef, failure?.remediationHint);
+    return refusal(pickSourceFailure(status), "PACKAGE_REJECTED", "Harbour could not safely accept this app package.", operationRef);
+}
+/**
+ * The one way this file turns "the server refused" into 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 reference always.
+ */
+function refusal(failure, fallbackCode, fallbackMessage, operationRef) {
+    return new CliError(failure?.code ?? fallbackCode, failure?.message ?? fallbackMessage, operationRef, failure?.remediationHint);
+}
+/**
+ * Why the whole operation stopped. The outer catch used to answer this with one
+ * fixed sentence for everything that was not already a `CliError`, which is
+ * every plain refusal the server raises — so the reason stayed on the server
+ * and the builder was told only that something failed. Read the reason from
+ * three places, in the order that serves the builder:
+ *
+ *  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
+ *     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);
+    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", "Harbour could not complete the started operation.", operationRef);
+}
+/**
+ * What the thrown value itself says. A refusal reaches us as a bare `Error`
+ * carrying the server's sentence, and — once errors carry them — the server's
+ * stable code and remediation too; all of it must survive to the builder. A
+ * runtime fault (`TypeError` and friends) is a defect in this CLI rather than
+ * an answer for the builder, so its message is not borrowed as the reason
+ * unless it also carries a code.
+ */
+function errorDetail(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const raw = error;
+    const code = text(raw.code);
+    const remediationHint = text(raw.remediationHint);
+    const message = code || (error instanceof Error && error.constructor === Error) ? text(raw.message) : undefined;
+    if (!code && !message && !remediationHint)
+        return undefined;
+    return { ...(code ? { code } : {}), ...(message ? { message } : {}), ...(remediationHint ? { remediationHint } : {}) };
+}
+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.
+ */
+async function probeOperation(client, operationRef) {
+    let failure;
+    try {
+        failure = pickSourceFailure(structured(await client.call("harbour_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 } : {}) };
+    }
+    catch {
+        return { pending: [], ...(failure ? { failure } : {}) };
+    }
+}
+/** 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("; ")}.`;
+}
+/**
+ * `harbour 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 \`harbour profile\` and \`harbour audience\`, then \`harbour productionise\` again — not \`harbour retry\`. Full list: \`harbour setup --operation ${operationRef}\`.`;
 }
 async function execute(client, operationRef, appId, graph, approval) {
     const args = { operationId: operationRef, appId, surface: "codex", graph, action: "save_baseline", mode: "EXECUTE" };

package/dist/packages/harbour-cli/src/remote-mcp-client.js

@@ -1,5 +1,50 @@
 import { CLI_VERSION } from "./version.js";
 import { CliError } from "./output.js";
+/** The code for a refusal the server did not label. Its own words still reach
+ * the builder; only the machine label is ours, and it says exactly that. */
+const UNLABELLED_REFUSAL = "HARBOUR_REFUSED";
+/**
+ * Harbour labels part of its refusals `CODE: sentence` on the wire — `src/mcp.ts`
+ * raises `APP_NOT_REGISTERED: …`, `SOURCE_UPLOAD_REQUIRED: …`, and the tool
+ * result carries that text and nothing else. Lifting the prefix into `code` is
+ * not classification: the label is the server's own, the sentence is kept
+ * whole either way, and a miss only means the refusal goes out unlabelled.
+ */
+const LABELLED = /^([A-Z][A-Z0-9_]{2,63}):[ \t]+(\S[\s\S]*)$/;
+function refusalText(result) {
+    return (result.content ?? []).map(item => item.text ?? "").join("\n").trim();
+}
+/**
+ * A tool refusal, carried whole: the server's own code, its own sentence and
+ * its own fix. `structuredContent` is read first because that is where a code
+ * belongs and where the server will put one once `toolError` carries one; today
+ * only the labelled prefix is available.
+ */
+export function serverRefusal(result) {
+    const text = refusalText(result);
+    const detail = result.structuredContent && typeof result.structuredContent === "object" ? result.structuredContent : undefined;
+    const declared = typeof detail?.code === "string" ? detail.code.trim() : "";
+    const hint = typeof detail?.remediationHint === "string" && detail.remediationHint.trim() ? detail.remediationHint.trim() : undefined;
+    const labelled = declared ? null : LABELLED.exec(text);
+    return new CliError(declared || labelled?.[1] || UNLABELLED_REFUSAL, (labelled?.[2] ?? text) || "Harbour rejected the request.", undefined, hint);
+}
+/** A JSON-RPC error is Harbour refusing the call itself (an unknown method, a
+ * body it could not parse). Its numeric code is the only one it has, so it is
+ * reported as such rather than flattened away. */
+function rpcRefusal(error, status) {
+    const text = error.message?.trim() ?? "";
+    const labelled = LABELLED.exec(text);
+    const code = labelled?.[1] ?? (typeof error.code === "number" ? `HARBOUR_RPC_${error.code}` : `HARBOUR_HTTP_${status}`);
+    return new CliError(code, (labelled?.[2] ?? text) || `Harbour refused the request (HTTP ${status}).`);
+}
+async function readRpc(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new Error(`Harbour returned a response that was not JSON (HTTP ${response.status}).`);
+    }
+}
 export class RemoteMcpClient {
     url;
     tenant;
@@ -22,7 +67,7 @@ export class RemoteMcpClient {
         const response = await this.request("tools/call", { name, arguments: args });
         const result = response;
         if (result.isError)
-            throw new Error(result.content?.map(item => item.text ?? "").join("\n") || "Harbour rejected the request.");
+            throw serverRefusal(result);
         return result;
     }
     async request(method, params, expectResponse = true) {
@@ -37,9 +82,16 @@ export class RemoteMcpClient {
             throw new CliError("AUTH_REQUIRED", "Harbour sign-in expired or was revoked. Run `harbour login` again.");
         if (!expectResponse)
             return undefined;
-        const parsed = await response.json();
-        if (!response.ok || parsed.error)
-            throw new Error(parsed.error?.message ?? `Harbour request failed (${response.status}).`);
+        const parsed = await readRpc(response);
+        if (parsed.error)
+            throw rpcRefusal(parsed.error, response.status);
+        // A non-ok response with no JSON-RPC error in it is the network between us
+        // and Harbour, not Harbour's answer, so it stays a plain Error: a long poll
+        // treats plain Errors as transient and tries again (see `waitForSettled`),
+        // and only `CliError` stops it. The wording is decided here rather than
+        // guessed from this string downstream.
+        if (!response.ok)
+            throw new Error(`Harbour request failed (HTTP ${response.status}).`);
         return parsed.result;
     }
     async post(body) {
@@ -47,12 +99,20 @@ export class RemoteMcpClient {
         const token = await this.token();
         if (token)
             headers.authorization = `Bearer ${token}`;
-        return fetch(this.url, { method: "POST", headers, body });
+        try {
+            return await fetch(this.url, { method: "POST", headers, body });
+        }
+        catch (error) {
+            // Plain Error for the same reason as the non-ok branch: a dropped
+            // connection mid-deployment is transient and the poll must be free to
+            // retry. `redact()` strips the URL before any of this is printed.
+            throw new Error(`Harbour could not be reached (${error instanceof Error ? error.message : "no details"}).`);
+        }
     }
 }
 export function structured(result) {
     if (result.isError)
-        throw new Error(result.content?.map(item => item.text ?? "").join("\n") || "Harbour rejected the request.");
+        throw serverRefusal(result);
     return result.structuredContent;
 }
 export function plainText(result) {

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

@@ -99,6 +99,8 @@ export function managedBlock() {
         "- Every route needs a signed-in human by default; do not add public routes or wildcard exceptions to make something work.",
         "- No secrets, tokens, `.env` values or fetched company content in source. `.harbour/local/` is ignored and never committed; `.harbour/integrations.json` and `.harbour/kit.lock.json` are committed.",
         "- Schema changes are SQL files in `migrations/`, applied by `harbour dev` and `harbour check`. Every table: ENABLE ROW LEVEL SECURITY + a policy; GRANT every verb a policy allows to `harbour_app_gateway` and to no other role — `harbour check` runs the pipeline's database gate and names any table/policy/grant that breaks this, with the fix.",
+        "- `.harbour/checks/` holds the app's retained journeys: one per capability the app's own code uses (`harbour.data.*`, `harbour.files.*`, actions, realtime, telemetry), plus a cross-user denial per owner-scoped table. The pairing is two-way and the `flow` gate refuses the deploy in both directions, so an edit that changes what the app does changes its checks in the same edit. Start using a capability and it needs its own retained check, written in that edit. Stop using one — a deleted section, a dropped table, a feature the app no longer has — and its retained check must be deleted in that same edit, because `harbour check` and the deployment pipeline replay `.harbour/checks/` against a real App Gateway and refuse the app (`flow.check-failed: the candidate's own retained checks no longer pass`) when a check exercises something the code no longer does.",
+        "- The starter's pairing is: `notes-journey.mjs` + `notes-cross-user.mjs` with the `notes` table and the Notes section of `src/App.tsx`; `files-journey.mjs` with the \"Private files\" section, the only code that calls `harbour.files.*`. Replacing the notes table with the app's own means rewriting both notes checks for that table; removing the \"Private files\" section means deleting `.harbour/checks/files-journey.mjs` in that same edit. An inherited check for a feature the app replaced or dropped is the most common reason a first deploy is refused.",
         "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (declaration, types, build, migrations + the pipeline's database gate, journeys), `harbour integrations request <connection> --reason <text> --app-root .`, `harbour integrations status --app-root .`, `harbour productionise --app-root .`. Company calls in `dev` use the account from `harbour login`; the local fixture user is only the app's identity.",
         "- Codex reads this AGENTS.md block; Claude Code also reads `.claude/skills/harbour-kit/SKILL.md`. The plain-English workflow (what to run when the person says \"run it\", \"check it\", \"ship it\") is in the user-level `isomorph` skill / `~/.codex/AGENTS.md` block installed by `harbour agent-setup`.",
         MANAGED_END
@@ -112,10 +114,11 @@ description: Build, run and check this Harbour app with the Harbour CLI (dev, ch
 Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
 
 1. \`harbour dev --app-root .\` starts Postgres, storage and one Harbour gateway (session identities, fixtures, realtime) plus Vite behind one loopback origin printed in the banner.
-2. Edit \`src/\` and \`migrations/\`. Use the SDK only. \`.harbour/integrations.json\` starts with no connections and gains one only when the app really calls a company system: declare it with only the operations the app calls, then request access (step 4). A declared connection the app does not call blocks every deploy until IT grants it; an undeclared one cannot be requested, so it never gets a grant. README.md has the worked Slack and warehouse examples — the file itself is strict JSON and cannot hold comments.
-3. \`harbour check --app-root .\` before every hand-off; read \`.harbour/local/check-report.json\`. Real integrations are reported as not tested unless \`--integrations\` is passed (read operations only).
-4. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
-5. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
+2. Edit \`src/\` and \`migrations/\`. Use the SDK only. \`.harbour/integrations.json\` starts with no connections and gains one only when the app really calls a company system: declare it with only the operations the app calls, then request access (step 5). A declared connection the app does not call blocks every deploy until IT grants it; an undeclared one cannot be requested, so it never gets a grant. README.md has the worked Slack and warehouse examples — the file itself is strict JSON and cannot hold comments.
+3. Keep \`.harbour/checks/\` paired with the code, in the same edit that changes it: one retained journey per capability the app's own code uses, and none for a capability it no longer uses. A new feature needs a new check; a feature you delete or replace (a dropped table, a removed section) means deleting or rewriting its check right then. \`harbour check\` and the deployment pipeline replay these checks against a real App Gateway and refuse the app (\`flow.check-failed\`) in both directions — a capability no check exercises, and a check that exercises something the code no longer does.
+4. \`harbour check --app-root .\` before every hand-off; read \`.harbour/local/check-report.json\`. Real integrations are reported as not tested unless \`--integrations\` is passed (read operations only).
+5. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
+6. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
 `;
 /**
  * Kit infrastructure: structural files every kit app needs, on every path —
@@ -148,8 +151,13 @@ function kitFiles() {
 function starterFiles(bundle) {
     return {
         "migrations/0001_notes.sql": MIGRATION,
-        // One retained check per capability the starter's UI uses: the pipeline's
-        // flow gate refuses an app whose checks never exercise a declared capability.
+        // Exactly one retained check per capability the starter's UI uses, and none for a
+        // capability it does not: the flow gate runs both ways — it refuses an app whose
+        // checks never exercise a declared capability, and it refuses an app whose checks
+        // no longer pass because the code behind them is gone. The starter's own UI still
+        // calls `harbour.files.*` in its "Private files" section, so `files-journey.mjs`
+        // belongs here; an app that drops that section deletes the check with it (the
+        // pairing is stated in the generated App.tsx, README.md and the CLAUDE.md block).
         ".harbour/checks/notes-journey.mjs": JOURNEY_CHECK,
         ".harbour/checks/files-journey.mjs": FILES_JOURNEY_CHECK,
         // The pipeline's cross-user denial, run locally: the last gate class that
@@ -178,7 +186,12 @@ const STARTER_README = `# Harbour app
 
 Created by \`harbour init\`. Run \`harbour dev --app-root .\` and open the printed origin. See CLAUDE.md / AGENTS.md for the kit rules.
 
-\`.harbour/checks/\` holds one journey per capability the app uses (\`notes-journey.mjs\` for data, \`files-journey.mjs\` for files) and \`notes-cross-user.mjs\`, which proves a second signed-in person cannot read, update or delete another person's note — the same denial the deployment pipeline's write probe asserts; \`harbour check\` and the deployment pipeline refuse an app whose checks never exercise an operation its own code performs, so a new feature needs its own retained check.
+\`.harbour/checks/\` holds one journey per capability the app uses (\`notes-journey.mjs\` for data, \`files-journey.mjs\` for files) and \`notes-cross-user.mjs\`, which proves a second signed-in person cannot read, update or delete another person's note — the same denial the deployment pipeline's write probe asserts.
+
+The checks and the code are one pair, and \`harbour check\` and the deployment pipeline's \`flow\` gate enforce the pair in both directions against a real App Gateway. Both directions refuse the deploy:
+
+- **A capability with no check.** They refuse an app whose checks never exercise an operation its own code performs, so a new feature needs its own retained check.
+- **A check with no capability.** They refuse an app whose retained checks no longer pass against its own code, so a feature you delete or replace means deleting or rewriting its check in the same edit. Replacing the starter's \`notes\` table with your own means rewriting \`notes-journey.mjs\` and \`notes-cross-user.mjs\` for that table. Removing the "Private files" section — the only code here that calls \`harbour.files.*\` — means \`rm .harbour/checks/files-journey.mjs\` right then; left behind, it exercises a capability the app no longer has and the deploy is refused with \`flow.check-failed: files-journey.mjs: exit status 1\`.
 
 ## Adding a company system (Slack, Gmail, a warehouse view)
 
@@ -214,7 +227,7 @@ const report = await integrations().execute<{ rows: Array<{ week: string; total:
 });
 \`\`\`
 
-A send (\`slack.message.post\`) runs only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a timer or a check. Consent is a user action: \`integrations().connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`. Anything the app calls needs its own retained check under \`.harbour/checks/\`.
+A send (\`slack.message.post\`) runs only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a timer or a check. Consent is a user action: \`integrations().connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`. Anything the app calls needs its own retained check under \`.harbour/checks/\`, and anything it stops calling loses its check in the same edit.
 `;
 const VITE_CONFIG = `import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
@@ -282,6 +295,7 @@ export function App() {
     const { data } = await harbour.data.from<Note>("notes").select("*").order("created_at", { ascending: false });
     setNotes(data);
   }, []);
+  // files capability — this call and \`upload\` below are what .harbour/checks/files-journey.mjs exercises.
   const loadFiles = useCallback(async () => { setFiles((await harbour.files.list("private/")) as StoredFile[]); }, []);
 
   useEffect(() => {
@@ -299,7 +313,7 @@ export function App() {
   };
   const toggle = async (note: Note) => { await harbour.data.from("notes").update({ done: !note.done }).eq("id", note.id); await loadNotes(); };
   const remove = async (note: Note) => { await harbour.data.from("notes").delete().eq("id", note.id); await loadNotes(); };
-  const upload = async (file: File) => { await harbour.files.upload(\`private/\${file.name}\`, file); await loadFiles(); };
+  const upload = async (file: File) => { await harbour.files.upload(\`private/\${file.name}\`, file); await loadFiles(); }; // .harbour/checks/files-journey.mjs
 
   // Company systems are not part of the starter: .harbour/integrations.json declares
   // nothing, so nothing about this app waits on IT. Add one only when the app really
@@ -324,6 +338,9 @@ export function App() {
       <p>Signed in as <strong>{user ? user.email : "…"}</strong> (identity from Harbour; locally the fixture user).</p>
       {error && <p role="alert" style={{ color: "crimson" }}>{error}</p>}
 
+      {/* Notes — paired with .harbour/checks/notes-journey.mjs (data) and
+          .harbour/checks/notes-cross-user.mjs. Replacing this table with the app's own
+          means rewriting both checks for that table in the same edit. */}
       <section>
         <h2>Notes</h2>
         <form onSubmit={event => { event.preventDefault(); void addNote(); }}>
@@ -340,6 +357,11 @@ export function App() {
         </ul>
       </section>
 
+      {/* Private files — the only code in this app that calls harbour.files.*, and so the
+          only reason .harbour/checks/files-journey.mjs exists. Delete this section and delete
+          that check in the same edit: the deploy's flow gate replays .harbour/checks/ against a
+          real App Gateway and refuses an app whose checks exercise a capability its code no
+          longer has ("flow.check-failed: files-journey.mjs: exit status 1"). */}
       <section>
         <h2>Private files</h2>
         <input type="file" aria-label="Upload file" onChange={event => { const file = event.target.files?.[0]; if (file) void upload(file); }} />
@@ -369,6 +391,11 @@ GRANT USAGE, SELECT ON SEQUENCE notes_id_seq TO harbour_app_gateway;
 const JOURNEY_CHECK = `// Journey check: the signed-in identity can create, read, tick and delete a note through
 // the running app (HARBOUR_APP_URL). Runs under \`harbour check\` while \`harbour dev\`
 // is up, and in the deployment pipeline's retained-check container.
+//
+// Paired with the \`notes\` table (migrations/0001_notes.sql) and the Notes section of
+// src/App.tsx. Replace that table with the app's own and this check is rewritten for the
+// new table in the same edit; drop the feature entirely and this file is deleted. A check
+// left behind for code the app no longer has fails the deploy's flow gate.
 import assert from "node:assert/strict";
 
 const appUrl = process.env.HARBOUR_APP_URL;
@@ -400,6 +427,10 @@ const CROSS_USER_CHECK = `// Cross-user check: a second signed-in person cannot
 // owner-scoped table; this is the same check run locally, so user isolation can no longer
 // be green under \`harbour check\` and red in CodeBuild. Runs while \`harbour dev\` is up,
 // and in the pipeline's retained-check container.
+//
+// Paired with the \`notes\` table: an app that replaces \`notes\` with its own owner-scoped
+// table rewrites this check for that table in the same edit, and one that drops the table
+// deletes this file. A check left behind for code the app no longer has fails the flow gate.
 import assert from "node:assert/strict";
 
 const appUrl = process.env.HARBOUR_APP_URL;
@@ -448,6 +479,12 @@ const FILES_JOURNEY_CHECK = `// Journey check: the signed-in identity can upload
 // The deployment pipeline refuses an app whose checks never exercise a capability
 // its own code uses, so this runs under \`harbour check\` while \`harbour dev\` is up,
 // and in the pipeline's retained-check container.
+//
+// This file exists only for that "Private files" section — the only code in the app that
+// calls \`harbour.files.*\`. If the app stops offering file upload, DELETE THIS FILE in the
+// same edit that removes the section: the gate runs both ways, and a retained check for a
+// capability the code no longer has refuses the deploy with
+// "flow.check-failed: files-journey.mjs: exit status 1".
 import assert from "node:assert/strict";
 
 const appUrl = process.env.HARBOUR_APP_URL;

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.23";
+export const CLI_VERSION = "0.1.24";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {