@fourier-labs/harbour 0.1.30 → 0.1.31

package/README.md

@@ -32,6 +32,7 @@ harbour init --app-root <path> [--upgrade]                 starter app in an emp
 harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin
 harbour stop --app-root <path>                             stop local services, keep data
 harbour check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations, journeys; report in .harbour/local/check-report.json
+harbour integrations catalog --app-root <path> [--json]   the company's connections as .harbour/integrations.json names them, with approved channels/views per environment
 harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>]
 harbour integrations status --app-root <path> [--json]
 harbour connect <company-start-url>                        once per company; then harbour login | logout
@@ -39,6 +40,8 @@ harbour productionise --app-root <path> [--wait] [--json]  save + preview deploy
 harbour status | retry | promote | setup | profile | audience | secrets … --operation <reference>
 ```
 
+`productionise`, `status --wait`, `retry` and `promote` follow the deployment for up to `--max-wait <seconds>` (default 30 minutes). Past that they exit 0 with `status: "RUNNING"` and the `harbour status --operation <reference> --wait --max-wait 120 --json` that continues the same deployment — a bounded wait is not a failure, and never a reason to start another deploy.
+
 `harbour --help` prints the full usage. Local commands need no company sign-in; integrations and shipping do.
 
 ## Development

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

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { CLI_VERSION } from "./version.js";
+import { continueCommand } from "./operations.js";
 const execFileAsync = promisify(execFile);
 export const MANAGED_START = "<!-- harbour:kit:start -->";
 export const MANAGED_END = "<!-- harbour:kit:end -->";
@@ -157,9 +158,9 @@ The person you are working with may not be a developer. They say what they want
 - "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. Do this unasked as soon as the first check is green — they should always have the 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\`. 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.
 - "does it work?", and before you report anything as working → open the dev link in your own browser when you have one, press the control you built or changed, and read what the app shows. A green \`harbour check\` is not that proof: it answers governed AI and company systems from fixtures, so the refusals that matter (a field the company's AI route does not accept, a consent the operation does not need, a channel that is not approved) appear only when the control is really pressed. In development a Send posts for real to the approved channel — press it once to verify and tell them you did. If you have no browser, say that the button itself is untested.
-- "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. Never guess a connection, channel, view or mailbox name — a guessed one is refused before IT's queue ever sees it, so nothing appears for IT to approve; use the exact names the person or IT gave you, and if you have none, that is the one question to ask before declaring anything. 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\`. Request the preview grant in the same turn (\`--environment preview\`) so shipping does not wait on a second IT decision. 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\`. A refusal with \`RESOURCE_NOT_APPROVED\` means the channel, view or mailbox is not on the connection yet: IT adds it in the Harbour console under Controls & integrations → API integrations → the provider tile → Configure → Channels (a warehouse view: Controls & integrations → Databases → the source → Views for the environment), and then you run the same request command again. Say "IT has to add <name> to the Slack connection first; the app works without it until then" and nothing more. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
+- "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. Never guess a connection, channel, view or mailbox name — a guessed one is refused before IT's queue ever sees it, so nothing appears for IT to approve; use the exact names the person or IT gave you, and if you have none, that is the one question to ask before declaring anything. Before asking, run \`harbour integrations catalog --app-root . --json\` — it lists the company's connections by the exact identifier \`.harbour/integrations.json\` uses, the operations IT allows on each and the approved channels, views and mailboxes per environment — and declare only identifiers and approved names it lists. 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\`. Request the preview grant in the same turn (\`--environment preview\`) so shipping does not wait on a second IT decision. 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\`. A refusal with \`RESOURCE_NOT_APPROVED\` means the channel, view or mailbox is not on the connection yet: IT adds it in the Harbour console under Controls & integrations → API integrations → the provider tile → Configure → Channels (a warehouse view: Controls & integrations → Databases → the source → Views for the environment), and then you run the same request command again. Say "IT has to add <name> to the Slack connection first; the app works without it until then" and nothing more. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
 - "summarise", "draft", "explain", "AI" → one \`harbour.ai.chat\` call (through \`ai()\` in \`src/harbour.client.ts\`) behind a control the person presses; never an OpenAI/Anthropic key, SDK or URL. \`harbour check\` writes its journey. Send \`messages\` and \`maxTokens\` and nothing else: a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has to enable an AI provider: say so in one line and keep the app working without it.
-- "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. If your tool cuts the command off before it finishes, \`harbour status --operation <ref> --wait --json\` continues the same deployment — never start another one to find out what happened. 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.
+- "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. If your tool cuts the command off before it finishes, \`${continueCommand("<ref>")}\` continues the same deployment — never start another one to find out what happened. 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.
 

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

@@ -37,15 +37,34 @@ export async function runChecks(root, options) {
     for (const check of gate.checks)
         record(check);
     let integrations = "not tested";
-    const lock = await readKitLock(root).catch(() => undefined);
-    const declaration = await readDeclaration(root);
-    if (options.governance && lock?.appId && !declaration.errors.length) {
-        integrations = await testIntegrationReads(lock.appId, options.governance, declaration.declaration, output);
-        if (!integrations.length)
-            output("No READY development grants with read operations; real integrations were not exercised.");
+    if (options.governance) {
+        // Reads that could not run are one check the report carries as not_run with
+        // the reason, beside the gate's own skipped checks where an agent reads
+        // outcomes — not exit 1 with the reason dropped, and not a stderr line beside
+        // `"not tested"`, the shape of a run that never asked. Observed 2026-09-12
+        // (CLI 0.1.29): every gate check passed, then the grant list's transport
+        // failure ended the run as `fetch failed` (CLI_FAILED) with no report written.
+        const skipped = (why) => record({ name: "integrations", status: "not_run", detail: why });
+        const lock = await readKitLock(root).catch(() => undefined);
+        const { declaration, errors } = await readDeclaration(root);
+        if (!lock?.appId)
+            skipped("the app is not linked yet; `harbour integrations request` links it");
+        else if (errors.length)
+            skipped(`.harbour/integrations.json is invalid: ${errors[0]}`);
+        else {
+            try {
+                integrations = await testIntegrationReads(lock.appId, options.governance, declaration, output);
+                if (!integrations.length)
+                    output("No READY development grants with read operations; real integrations were not exercised.");
+            }
+            catch (error) {
+                // Governance's answer about the grant list — unreachable, sign-in gone, a refusal — is about the leg, never about the app.
+                if (!(error instanceof CliError))
+                    throw error;
+                skipped(error.message);
+            }
+        }
     }
-    else if (options.governance)
-        output("Integrations were not tested: the app is not linked yet or the declaration is invalid.");
     // After the gate, because `.harbour/checks/*.mjs` is part of the deployed
     // tree (kit.ts `sourceDigest`) and the gate may have regenerated it: the
     // report has to pin the tree the journeys actually ran against, or

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

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { RemoteMcpClient } from "./remote-mcp-client.js";
 import { productionise } from "./productionise.js";
-import { confirmAudience, confirmProfile, dismissSecret, fetchStatus, getAppSetup, listSecrets, outcomeFor, promoteToProduction, readSecretFromStdin, readSecretFromTerminal, retryDeployment, setSecret, summarize, waitForSettled } from "./operations.js";
-import { CliError, failureEnvelope, renderFailure, renderSummary } from "./output.js";
+import { confirmAudience, confirmProfile, continueCommand, dismissSecret, fetchStatus, follow, getAppSetup, listSecrets, promoteToProduction, readSecretFromStdin, readSecretFromTerminal, retryDeployment, setSecret, summarize } from "./operations.js";
+import { CliError, failureEnvelope, operationEnvelope, renderFailure, renderSummary } from "./output.js";
 import { CLI_VERSION } from "./version.js";
 import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
 import { connect, loadConfig, resolveConfig } from "./config.js";
@@ -14,7 +14,7 @@ import { startDev } from "./dev.js";
 import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
 import { stopAllHarbourProjects } from "./docker-networks.js";
 import { runChecks } from "./check.js";
-import { GovernanceClient, integrationsStatus, requestIntegrations } from "./integrations.js";
+import { GovernanceClient, integrationsCatalog, integrationsStatus, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 const args = process.argv.slice(2);
 const command = args[0];
 const connectUrl = args[1];
@@ -39,8 +39,13 @@ const reason = optionValue("--reason");
 const environment = optionValue("--environment");
 const operations = optionValue("--operations");
 const expiresAt = optionValue("--expires-at");
+/** Seconds `productionise`, `status --wait`, `retry` and `promote` follow the operation before reporting it as still running (default: 30 minutes). */
+const maxWaitSeconds = args.includes("--max-wait") ? Number(optionValue("--max-wait")) : undefined;
+const waitOptions = maxWaitSeconds ? { maxWaitMs: maxWaitSeconds * 1000 } : {};
 const includePaths = [];
 let optionError;
+if (maxWaitSeconds !== undefined && !(Number.isInteger(maxWaitSeconds) && maxWaitSeconds > 0))
+    optionError = "--max-wait takes a whole number of seconds.";
 for (let index = 0; index < args.length; index += 1) {
     if (args[index] === "--include") {
         const value = args[index + 1];
@@ -57,10 +62,10 @@ const usage = [
     "Usage:",
     "  harbour connect <company-start-url>",
     "  harbour login | logout",
-    "  harbour productionise --app-root <path> [--include <relative-path>]... [--no-wait] [--json]",
-    "  harbour status --operation <reference> [--wait] [--json]",
-    "  harbour retry --operation <reference> [--no-wait] [--json]",
-    "  harbour promote --operation <reference> [--no-wait] [--json]",
+    "  harbour productionise --app-root <path> [--include <relative-path>]... [--no-wait] [--max-wait <seconds>] [--json]",
+    "  harbour status --operation <reference> [--wait] [--max-wait <seconds>] [--json]",
+    "  harbour retry --operation <reference> [--no-wait] [--max-wait <seconds>] [--json]",
+    "  harbour promote --operation <reference> [--no-wait] [--max-wait <seconds>] [--json]",
     "  harbour setup --operation <reference> [--json]            what the app still needs (name, audience, secrets)",
     "  harbour profile --operation <reference> [--name <text>] [--description <text>] [--json]",
     "  harbour audience --operation <reference> [--emails a@co,b@co] [--json]   (no --emails = only you)",
@@ -75,8 +80,10 @@ const usage = [
     "  harbour check --app-root <path> [--integrations] [--json]  types, build, then the pipeline's kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, journeys, operation coverage (+ authorised real reads)",
     "  harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>] [--operations a,b] [--expires-at <UTC>] [--json]",
     "  harbour integrations status --app-root <path> [--json]",
+    "  harbour integrations catalog --app-root <path> [--json]   the company's connections as .harbour/integrations.json names them: identifiers, allowed operations, approved channels/views/mailboxes per environment (no app needed)",
     "Run `harbour connect <company-start-url>` once, then sign in when Harbour asks.",
     "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
+    `--max-wait bounds how long productionise, status --wait, retry and promote follow the deployment (default 30 minutes). When it passes the command exits 0 with status RUNNING, the last known deployment state, and the \`${continueCommand("<reference>")}\` that continues the same deployment: a bounded wait is not a failure and never means start another one.`,
     "For kit apps, productionise first checks that every connection in .harbour/integrations.json has a preview grant and exits 2 (INTEGRATIONS_NOT_READY) with the requests to make, then runs the pipeline's kit gate in the local session and refuses (KIT_GATE_FAILED) what CodeBuild would refuse.",
     "secrets set reads the value from your terminal with echo off (or from stdin with --value-stdin); it is never printed or passed to any other program.",
     ""
@@ -108,9 +115,10 @@ else if (command === "agent-setup") {
 }
 else if (!["connect", "login", "logout", "productionise", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
-    || (command === "productionise" && (optionError || !root))
+    || (["productionise", "status", "retry", "promote"].includes(command) && optionError)
+    || (command === "productionise" && !root)
     || (LOCAL_COMMANDS.includes(command) && !root && !(command === "stop" && stopAll))
-    || (command === "integrations" && (!root || !subcommand || !["request", "status"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--") || !reason))))
+    || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--") || !reason))))
     || (OPERATION_COMMANDS.includes(command) && !operationRef)
     || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
     if (optionError)
@@ -231,24 +239,26 @@ else {
                     const governance = new GovernanceClient(config.apiUrl, token, tenant);
                     const result = subcommand === "status"
                         ? await integrationsStatus(target, governance)
-                        : await requestIntegrations(target, governance, tenant, EMBEDDED_KIT_BUNDLE, { connection: args[2], reason: reason, environment, operations: operations?.split(",").map(value => value.trim()).filter(Boolean), expiresAt });
+                        : subcommand === "catalog"
+                            ? await integrationsCatalog(governance)
+                            : await requestIntegrations(target, governance, tenant, EMBEDDED_KIT_BUNDLE, { connection: args[2], reason: reason, environment, operations: operations?.split(",").map(value => value.trim()).filter(Boolean), expiresAt });
                     envelope = summaryEnvelope(result);
                     if (!json)
-                        progress(subcommand === "status" ? renderIntegrationsStatus(result) : renderRequest(result));
+                        progress(subcommand === "status" ? renderIntegrationsStatus(result) : subcommand === "catalog" ? renderIntegrationsCatalog(result) : renderRequest(result));
                 }
                 else if (command === "productionise") {
                     // Kit apps: preview grants are checked (and the app linked) before any operation starts, so productionise never mints a second app for the same root.
-                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: EMBEDDED_KIT_BUNDLE } });
-                    envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: true, operationRef: result.operationRef, result: result.result };
+                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait, waitOptions, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: EMBEDDED_KIT_BUNDLE } });
+                    envelope = operationEnvelope(result.result, result.operationRef, CLI_VERSION);
                 }
                 else {
                     let summary;
                     if (command === "status")
-                        summary = wait ? outcomeFor(await waitForSettled(client, operationRef, progress), operationRef).summary : summarize(await fetchStatus(client, operationRef));
+                        summary = wait ? await follow(client, operationRef, progress, waitOptions) : summarize(await fetchStatus(client, operationRef));
                     else if (command === "retry")
-                        summary = await retryDeployment(client, operationRef, progress, { wait: !noWait });
+                        summary = await retryDeployment(client, operationRef, progress, { wait: !noWait, waitOptions });
                     else if (command === "promote")
-                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait });
+                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait, waitOptions });
                     else if (command === "setup")
                         summary = { setup: await getAppSetup(client, operationRef) };
                     else if (command === "profile")
@@ -261,7 +271,7 @@ else {
                         summary = await setSecret(client, operationRef, { name: secretName, ...(personal ? { personal: true } : {}), readValue: valueStdin ? readSecretFromStdin : () => readSecretFromTerminal(`Value for ${secretName} (not shown): `) }, progress);
                     else
                         summary = await dismissSecret(client, operationRef, secretName, progress);
-                    envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: true, operationRef: operationRef, result: summary };
+                    envelope = operationEnvelope(summary, operationRef, CLI_VERSION);
                 }
                 process.stdout.write(json ? `${JSON.stringify(envelope)}\n` : renderSummary(envelope));
             }

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

@@ -21,11 +21,17 @@ export class GovernanceClient {
     list(appId) {
         return this.call("GET", `/v1/development/apps/${encodeURIComponent(appId)}/integrations?tenantId=${encodeURIComponent(this.tenantId)}`);
     }
+    /** Tenant-scoped: needs no linked app, so it answers on a builder's first turn. */
+    catalog() {
+        return this.call("GET", `/v1/development/integrations/catalog?tenantId=${encodeURIComponent(this.tenantId)}`);
+    }
     execute(appId, body) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integrations/execute`, body);
     }
     async call(method, path, body) {
-        const response = await this.fetchImpl(`${this.apiUrl.replace(/\/$/, "")}${path}`, { method, headers: { authorization: `Bearer ${this.token}`, "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" });
+        const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
+        const response = await this.fetchImpl(url, { method, headers: { authorization: `Bearer ${this.token}`, "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" })
+            .catch((error) => { throw new CliError("GOVERNANCE_UNREACHABLE", `Harbour governance at ${new URL(url).host} could not be reached: ${transportFailure(error)}.`); });
         const parsed = await response.json().catch(() => ({}));
         if (response.status === 401)
             throw new CliError("AUTH_REQUIRED", "Please sign in to Harbour with `harbour login`.");
@@ -34,6 +40,22 @@ export class GovernanceClient {
         return (parsed.data ?? parsed);
     }
 }
+/**
+ * What actually failed under a `fetch` rejection. undici reports every transport
+ * failure as `TypeError: fetch failed` and keeps the reason in `cause`: `getaddrinfo
+ * ENOTFOUND <host>`, `connect ECONNREFUSED <ip>:<port>`, a ConnectTimeoutError
+ * (UND_ERR_CONNECT_TIMEOUT, after 10 s), `unexpected redirect` under `redirect:
+ * "error"`, or an AggregateError with an empty message over one error per address
+ * tried. Observed 2026-09-12 (CLI 0.1.29): `harbour check --integrations` printed
+ * `fetch failed` and nothing else, so what was wrong — and that nothing about the
+ * app was — could not be told from the output.
+ */
+function transportFailure(error) {
+    const cause = (error instanceof Error ? error.cause ?? error : error);
+    const words = (failure) => { const { message } = (failure ?? {}); return typeof message === "string" ? message.trim() : ""; };
+    const text = words(cause) || (Array.isArray(cause?.errors) ? cause.errors.map(words).filter(Boolean).join("; ") : "") || String(cause);
+    return typeof cause?.code === "string" && !text.includes(cause.code) ? `${text} (${cause.code})` : text;
+}
 /** Links the app once (stable idempotency key) and records the appId in kit.lock. */
 export async function ensureLinkedApp(root, client, tenantId, bundle) {
     const lock = (await readKitLock(root)) ?? newKitLock(bundle, tenantId);
@@ -45,6 +67,7 @@ export async function ensureLinkedApp(root, client, tenantId, bundle) {
     await writeKitLock(root, { ...lock, appId: linked.appId, tenantId });
     return linked.appId;
 }
+export const ENVIRONMENTS = ["development", "preview", "production"];
 /**
  * One request per identity mode from the declaration's scope (or the named subset).
  * Polls the grant list for up to 30 s; PENDING is reported as pending, never as ready.
@@ -54,7 +77,7 @@ export async function requestIntegrations(root, client, tenantId, bundle, option
     if (errors.length)
         throw new CliError("DECLARATION_INVALID", `.harbour/integrations.json is invalid: ${errors[0]}`);
     const environment = options.environment ?? "development";
-    if (!["development", "preview", "production"].includes(environment))
+    if (!ENVIRONMENTS.includes(environment))
         throw new CliError("USAGE", "--environment must be development, preview or production.");
     if (!options.reason.trim())
         throw new CliError("USAGE", "--reason <text> is required.");
@@ -180,6 +203,35 @@ export function requestScope(declaration, connection, only) {
         ...(identityMode === "app" && entry.operations.includes("slack.message.post") && declared.presentation ? { presentation: declared.presentation } : {})
     }));
 }
+/** Where connection, channel, view and mailbox names come from, so an agent never guesses one (2026-09-12: six of nineteen turns spent on refused guesses). */
+export async function integrationsCatalog(client) {
+    const listed = await client.catalog();
+    return { connections: listed.connections.map(entry => ({
+            connection: entry.connection, kind: entry.kind, ...(entry.provider ? { provider: entry.provider } : {}), ...(entry.connector ? { connector: entry.connector } : {}), ...(entry.installation ? { installation: entry.installation } : {}),
+            displayName: entry.displayName, status: entry.status,
+            operations: entry.operations.map(item => ({ operation: item.operation, identities: [...item.identities] })),
+            resources: Object.fromEntries(ENVIRONMENTS.map(environment => [environment, (entry.resources[environment] ?? []).map(resource => ({ name: resource.name, ...(resource.columns ? { columns: [...resource.columns] } : {}) }))]))
+        })) };
+}
+const PROVIDER_WORDS = { slack: "Slack", gmail: "Gmail" };
+const INSTALLATION_WORDS = { installed: "bot installed", not_installed: "bot not installed yet: IT installs it in the Harbour console", reconnect_required: "bot needs reconnecting: IT does that in the Harbour console" };
+/** One block per connection: the identifier to declare, what it is, the allowed operations with their identity, and the approved names per environment. */
+export function renderIntegrationsCatalog(result) {
+    if (!result.connections.length)
+        return "No connections are registered for your company yet; IT adds them in the Harbour console under Controls & integrations. Do not declare one until it is listed here.";
+    const lines = [];
+    for (const entry of result.connections) {
+        const what = entry.kind === "saas" ? `${PROVIDER_WORDS[entry.provider ?? ""] ?? entry.provider} connection` : `${entry.connector ?? "database"} warehouse`;
+        const state = [entry.status, ...(entry.installation && INSTALLATION_WORDS[entry.installation] ? [INSTALLATION_WORDS[entry.installation]] : [])].join(", ");
+        lines.push(`\`${entry.connection}\` — ${what} "${entry.displayName}" (${state})`);
+        lines.push(`  operations: ${entry.operations.map(item => `${item.operation} (${item.identities.join(" or ")})`).join(", ") || "none allowed"}`);
+        for (const environment of ENVIRONMENTS) {
+            const names = entry.resources[environment].map(resource => `${resource.name}${resource.columns?.length ? ` (${resource.columns.join(", ")})` : ""}`);
+            lines.push(`  ${environment}: ${names.join(", ") || "nothing approved yet"}`);
+        }
+    }
+    return lines.join("\n");
+}
 export async function integrationsStatus(root, client) {
     const lock = await readKitLock(root);
     if (!lock?.appId)

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

@@ -1,6 +1,6 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "harbour.kit-bundle/1.0",
-    "kitVersion": "0.1.30",
+    "kitVersion": "0.1.31",
     "sdk": {
         "package": "@harbour/app-sdk",
         "version": "1.1.0",
@@ -8,8 +8,8 @@ export const PUBLISHED_KIT_BUNDLE = {
         "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:88e00a9dac87f5281285ca1d881c7766f8fa04fcee00376f1c60e10e848bf16f"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:11a9ceadcb3b997163f61cf8249ad9302ad073af28ac7d2110c6cafac0a6d16e",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:72caccadc12cd5f604bdebec20f8b831242b6d93924a16128f4434aac2497e52"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:915320a5265e1f740c7d6078da164537666043883b69ec8404a3b5036dc8533a",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:d000142b60b2b3e97b0c2043fc0d8e13621d5d6467d0d048cf2c69e7a80fe014"
     },
     "brief": {
         "fingerprint": "4b3c61acdce47995c15e5ce8c38d5e636a624cd79ef7bebb9401b6228d129d11"

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

@@ -20,9 +20,12 @@ function pickDeployment(value) {
         ...(value.message ? { message: value.message } : {}),
         ...(value.protectedUrl ? { protectedUrl: value.protectedUrl } : {}),
         ...(value.versionId ? { versionId: value.versionId } : {}),
-        ...(value.failure ? { failure: { ...(value.failure.message ? { message: value.failure.message } : {}), ...(value.failure.retryable !== undefined ? { retryable: value.failure.retryable } : {}), ...(value.failure.remediationHint ? { remediationHint: value.failure.remediationHint } : {}) } } : {})
+        ...(value.failure ? { failure: pickFailure(value.failure) } : {})
     };
 }
+function pickFailure(value) {
+    return { ...(value.message ? { message: value.message } : {}), ...(value.retryable !== undefined ? { retryable: value.retryable } : {}), ...(value.remediationHint ? { remediationHint: value.remediationHint } : {}) };
+}
 /**
  * The refusal reason source intake stored on the operation. Read the same way
  * `pickDeployment` reads a deployment failure: keep the server's own code,
@@ -55,8 +58,9 @@ function pickProduction(value) {
         ...(value.status ? { status: value.status } : {}),
         ...(value.message ? { message: value.message } : {}),
         ...(value.productionUrl ? { productionUrl: value.productionUrl } : {}),
+        ...(value.versionId ? { versionId: value.versionId } : {}),
         ...(value.previewVersionId ? { previewVersionId: value.previewVersionId } : {}),
-        ...(value.failure?.message ? { failure: { message: value.failure.message } } : {})
+        ...(value.failure ? { failure: pickFailure(value.failure) } : {})
     };
 }
 export async function fetchStatus(client, operationRef, waitSeconds = 0) {
@@ -73,6 +77,10 @@ export function isSettled(status) {
         return DEPLOYMENT_TERMINAL.has(status.deployment.state);
     return false;
 }
+/** What the wait was before `--max-wait` existed: a caller that never passes it waits exactly as long as it did. */
+const DEFAULT_MAX_WAIT_MS = 30 * 60_000;
+/** A line at least this often while nothing changes, so a wrapper with its own idle timeout (an agent's shell tool) keeps seeing output; see `follow`. */
+const HEARTBEAT_MS = 60_000;
 /**
  * Follow the operation until the preview deployment (or an in-flight production
  * promotion) settles. Harbour long-polls up to 15 s per call and returns early
@@ -80,20 +88,36 @@ export function isSettled(status) {
  * `noDeploymentGraceMs` covers the gap between the source save succeeding and
  * the deployment attempt being recorded; past it, a saved operation with no
  * deployment is reported as such instead of waited on forever.
+ *
+ * Returns for exactly three reasons, and the status says which: it settled;
+ * nothing was in flight when the grace window closed; or something was in
+ * flight when the ceiling passed. The ceiling is never thrown — see `follow`.
+ * Two waits, two bounds: the grace window while nothing is in flight, the
+ * ceiling once something is. Each long-poll and each pause is cut to what is
+ * left of the bound, so `--max-wait N` answers within N seconds — an agent's
+ * tool with a total cap of N sees the answer instead of killing the command.
  */
 export async function waitForSettled(client, operationRef, output, options = {}) {
     const now = options.now ?? Date.now;
     const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
-    const maxWaitMs = options.maxWaitMs ?? 30 * 60_000;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
     const graceMs = options.noDeploymentGraceMs ?? 90_000;
     const startedAt = now();
+    // Until the first status says what is in flight, the shorter bound holds.
+    let bound = Math.min(graceMs, maxWaitMs);
+    let last;
     let lastLine = "";
+    let lastOutputAt = startedAt;
     let consecutiveFailures = 0;
     while (true) {
         const callStarted = now();
+        const remainingMs = startedAt + bound - callStarted;
+        // Nothing more fits inside the bound: the watch answers with what it last saw.
+        if (last && remainingMs <= 1_000)
+            return last;
         let status;
         try {
-            status = await fetchStatus(client, operationRef, 15);
+            status = await fetchStatus(client, operationRef, Math.min(15, Math.max(0, Math.floor(remainingMs / 1000))));
             consecutiveFailures = 0;
         }
         catch (error) {
@@ -110,52 +134,105 @@ export async function waitForSettled(client, operationRef, output, options = {})
             await sleep(Math.min(15_000, 3_000 * consecutiveFailures));
             continue;
         }
+        last = status;
         if (isSettled(status))
             return status;
-        if (!status.deployment && !status.production) {
-            if (now() - startedAt > graceMs)
-                return status;
-        }
+        const at = now();
+        bound = status.deployment || status.production ? maxWaitMs : graceMs;
         const line = progressLine(status);
-        if (line && line !== lastLine) {
+        if (line !== lastLine) {
             output(line);
             lastLine = line;
+            lastOutputAt = at;
         }
-        if (now() - startedAt > maxWaitMs)
-            throw new CliError("DEPLOYMENT_TIMEOUT", "Harbour is still deploying the app. Check again later with `harbour status`.", operationRef);
-        // Harbour returns immediately when nothing is in flight yet; do not spin.
-        const elapsed = now() - callStarted;
+        else if (at - lastOutputAt >= HEARTBEAT_MS) {
+            output(runningLine(status, at - startedAt, operationRef));
+            lastOutputAt = at;
+        }
+        // Harbour returns immediately when nothing is in flight yet; do not spin — and never past the bound.
+        const elapsed = at - callStarted;
         if (elapsed < 3_000)
-            await sleep(3_000 - elapsed);
+            await sleep(Math.min(3_000 - elapsed, Math.max(0, startedAt + bound - at)));
     }
 }
 function safeMessage(error) {
     const raw = error instanceof Error ? error.message : String(error);
     return raw.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").replace(/\s+/g, " ").trim().slice(0, 160) || "no details";
 }
+function activity(status) {
+    return status.production ? "promoting the app to production" : status.deployment ? "deploying the app" : "preparing the deployment";
+}
 function progressLine(status) {
-    if (status.production)
-        return `Harbour is promoting the app to production${status.production.message ? ` (${status.production.message})` : ""}.`;
-    if (status.deployment)
-        return `Harbour is deploying the app${status.deployment.message ? ` (${status.deployment.message})` : ""}.`;
-    return "Harbour saved the app and is preparing the deployment.";
+    const stage = status.production ?? status.deployment;
+    return stage ? `Harbour is ${activity(status)}${stage.message ? ` (${stage.message})` : ""}.` : "Harbour saved the app and is preparing the deployment.";
+}
+/**
+ * The one sentence for a watch that has not ended: the heartbeat prints it as
+ * time passes, and a ceiling that passes returns it as the next step. A
+ * wrapper that stops watching, or an agent whose tool did, runs the command
+ * it names and continues the same operation — it never starts another.
+ */
+function runningLine(status, elapsedMs, operationRef) {
+    const seconds = Math.round(elapsedMs / 1000);
+    return `Harbour is still ${activity(status)} (${Math.floor(seconds / 60)}m${seconds % 60}s). Safe to stop watching: \`${continueCommand(operationRef)}\` picks it up; do not start another.`;
 }
-/** The exit-relevant outcome of a settled status: success, a failure, or a step the maker must take. */
+/**
+ * The one command that resumes a watch, as the CLI's help and the agent guide
+ * print it too. Bounded at two minutes so a wrapper with an idle timeout gets
+ * an answer and runs it again, rather than cutting a 30-minute wait off and
+ * learning nothing.
+ */
+export function continueCommand(operationRef) {
+    return `harbour status --operation ${operationRef} --wait --max-wait 120 --json`;
+}
+/** The exit-relevant outcome of a status — success, a step the maker must take, an operation still in flight — as the summary with its `outcome` named; a failure is thrown. */
 export function outcomeFor(status, operationRef) {
     const summary = summarize(status);
+    // A failed stage, reported as the stage recorded it: its sentence, then its
+    // fix, with the summary attached so the envelope carries the version the
+    // console's releases tab and the email name. Only a stage that recorded no
+    // sentence at all gets the generic one.
+    const failed = (code, stage, fallback, suffix = "") => new CliError(code, `${stage.failure?.message ?? stage.message ?? fallback}${suffix}`, operationRef, stage.failure?.remediationHint, summary);
     if (status.production?.state === "LIVE")
-        return { kind: "production_live", summary };
+        return { ...summary, outcome: "production_live" };
     if (status.production && PRODUCTION_TERMINAL.has(status.production.state))
-        throw new CliError("PRODUCTION_PROMOTION_FAILED", status.production.failure?.message ?? status.production.message ?? "Harbour could not complete the production promotion.", operationRef);
+        throw failed("PRODUCTION_PROMOTION_FAILED", status.production, "Harbour could not complete the production promotion.");
     if (status.waiting)
-        return { kind: "waiting", summary };
+        return { ...summary, outcome: "waiting" };
+    // A promotion in flight rides on a LIVE preview; the promotion is what is being followed.
+    if (status.production)
+        return { ...summary, outcome: "running" };
     if (status.deployment?.state === "LIVE")
-        return { kind: "live", summary };
+        return { ...summary, outcome: "live" };
     if (status.deployment && DEPLOYMENT_TERMINAL.has(status.deployment.state)) {
         const retryable = status.deployment.failure?.retryable === true;
-        throw new CliError(retryable ? "DEPLOYMENT_RETRYABLE_FAILURE" : "DEPLOYMENT_FAILED", `${status.deployment.failure?.message ?? status.deployment.message ?? "Harbour could not complete the deployment."}${retryable ? " Run `harbour retry` to start it again." : ""}`, operationRef);
+        throw failed(retryable ? "DEPLOYMENT_RETRYABLE_FAILURE" : "DEPLOYMENT_FAILED", status.deployment, "Harbour could not complete the deployment.", retryable ? " Run `harbour retry` to start it again." : "");
     }
-    return { kind: "no_deployment", summary: { ...summary, nextStep: summary.nextStep ?? "Harbour saved the app but has not started a deployment for this company yet. Ask your Harbour administrator to connect deployment." } };
+    if (status.deployment)
+        return { ...summary, outcome: "running" };
+    return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? "Harbour saved the app but has not started a deployment for this company yet. Ask your Harbour administrator to connect deployment." };
+}
+/**
+ * `waitForSettled` then `outcomeFor`, as the one summary a command returns.
+ *
+ * A ceiling that passes is a `running` outcome and never an error: exit 0, the
+ * operation untouched, and the summary says how long this command watched and
+ * names the exact command that resumes the same watch. Measured 2026-09-12:
+ * the ceiling was a thrown `DEPLOYMENT_TIMEOUT`, an agent's shell tool cut the
+ * silent 30-minute wait off long before it, the agent started a second deploy
+ * to get "a status-producing call", and the first one's refusal reached the
+ * human by email and never reached the agent. The heartbeat, the bounded
+ * `--max-wait`, and this outcome each close one part of that.
+ */
+export async function follow(client, operationRef, output, options = {}) {
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const status = await waitForSettled(client, operationRef, output, options);
+    const summary = outcomeFor(status, operationRef);
+    if (summary.outcome !== "running")
+        return summary;
+    const elapsedMs = now() - startedAt;
+    return { ...summary, elapsedSeconds: Math.round(elapsedMs / 1000), nextStep: runningLine(status, elapsedMs, operationRef) };
 }
 export async function retryDeployment(client, operationRef, output, options = {}) {
     await client.initialize();
@@ -163,7 +240,7 @@ export async function retryDeployment(client, operationRef, output, options = {}
     output(result.retry?.replayed ? "Harbour had already accepted this retry." : "Harbour accepted the deployment retry.");
     if (options.wait === false)
         return summarize(await fetchStatus(client, operationRef));
-    return outcomeFor(await waitForSettled(client, operationRef, output), operationRef).summary;
+    return follow(client, operationRef, output, options.waitOptions);
 }
 /**
  * Promotion mirrors the console's "I tested this version" button: the maker
@@ -175,7 +252,7 @@ export async function promoteToProduction(client, operationRef, output, options
     const status = await fetchStatus(client, operationRef);
     if (status.production && !PRODUCTION_TERMINAL.has(status.production.state)) {
         output("Harbour is already promoting this app to production.");
-        return options.wait === false ? summarize(status) : outcomeFor(await waitForSettled(client, operationRef, output), operationRef).summary;
+        return options.wait === false ? summarize(status) : follow(client, operationRef, output, options.waitOptions);
     }
     const deployment = status.deployment;
     if (deployment?.state !== "LIVE" || !deployment.versionId || !deployment.protectedUrl)
@@ -193,7 +270,7 @@ export async function promoteToProduction(client, operationRef, output, options
     output("Harbour accepted the production promotion.");
     if (options.wait === false)
         return { ...summarize(status), ...(result.production ? { production: pickProduction(result.production) } : {}) };
-    return outcomeFor(await waitForSettled(client, operationRef, output), operationRef).summary;
+    return follow(client, operationRef, output, options.waitOptions);
 }
 export async function readLine() {
     if (!process.stdin.isTTY) {

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

@@ -99,11 +99,29 @@ function wholeWordsAfter(said, start) {
  */
 export function failureEnvelope(error, cliVersion) {
     const operationRef = error instanceof CliError ? error.operationRef : undefined;
-    return { schema: "harbour.cli-result/1.0", cliVersion, status: "FAILED", operationStarted: Boolean(operationRef), ...(operationRef ? { operationRef } : {}), error: safeError(error) };
+    const result = error instanceof CliError ? error.result : undefined;
+    return { schema: "harbour.cli-result/1.0", cliVersion, status: "FAILED", operationStarted: Boolean(operationRef), ...(operationRef ? { operationRef } : {}), error: safeError(error), ...(result !== undefined ? { result } : {}) };
 }
+/**
+ * The envelope for a command that finished without error: `SUCCEEDED`, or
+ * `RUNNING` when the operation it followed is still in flight (the result's
+ * `outcome`, set by `follow`) — see `CliEnvelope.status`.
+ */
+export function operationEnvelope(result, operationRef, cliVersion) {
+    const running = result?.outcome === "running";
+    return { schema: "harbour.cli-result/1.0", cliVersion, status: running ? "RUNNING" : "SUCCEEDED", operationStarted: true, operationRef, result };
+}
+/**
+ * The reason and the fix on one line, and — when the failure is a deployment
+ * or a promotion the result knows the version of — the stage line beneath it,
+ * so the builder and whoever reads the console or the email are looking at
+ * the same attempt.
+ */
 export function renderFailure(envelope) {
     const error = envelope.error;
-    return `${error?.message ?? NO_DETAIL}${error?.remediationHint ? ` ${error.remediationHint}` : ""}\n`;
+    const result = (envelope.result ?? {});
+    const stages = ["production", "deployment"].filter(kind => result[kind]?.failure && result[kind]?.versionId).map(kind => `\n${stageLine(kind, result[kind])}`);
+    return `${error?.message ?? NO_DETAIL}${error?.remediationHint ? ` ${error.remediationHint}` : ""}${stages.join("")}\n`;
 }
 /**
  * Server-supplied text on its way to a terminal, given exactly the treatment
@@ -140,6 +158,9 @@ function said(value) {
  *  - `operationRef` — the handle every later `--operation` needs, and already
  *    exempt on the failure path: `safeError` redacts the message and the hint,
  *    never the reference they travel with. The same policy on both paths.
+ *  - `deployment.versionId`, `production.versionId` — printed only on a failed
+ *    stage, and for the same reason: it is the reference the console and the
+ *    email carry for that attempt, and a bounded or reworded one names nothing.
  *  - `secrets.asks[].name` and `.prefilledFromPath` — identifiers, not prose. A
  *    secret named `AUTHORIZATION_TOKEN` matches the header pattern and would be
  *    erased whole, printing `Secret : needs a value`; the path is read off the
@@ -169,22 +190,14 @@ export function renderSummary(envelope) {
     if (verification)
         lines.push(`Saved app: ${verification}${assurance ? ` (${assurance})` : ""}`);
     if (result.production) {
-        lines.push(`Production: ${said(result.production.state)}${result.production.productionUrl ? ` — ${result.production.productionUrl}` : ""}`);
-        // `|| NO_DETAIL` for the reason `safeError` has it: redaction can empty a
-        // string, and a failure reported as two spaces is worse than one that says
-        // plainly this CLI has nothing to show.
+        lines.push(stageLine("production", result.production));
         if (result.production.failure?.message)
-            lines.push(`  ${said(result.production.failure.message) || NO_DETAIL}`);
+            lines.push(`  ${failureText(result.production.failure)}`);
     }
     if (result.deployment) {
-        lines.push(`Preview deployment: ${said(result.deployment.status ?? result.deployment.state)}${result.deployment.protectedUrl ? ` — ${result.deployment.protectedUrl}` : ""}`);
-        if (result.deployment.failure?.message) {
-            // The hint is redacted and bounded on its own, exactly as `safeError`
-            // bounds it separately from the message: appending it first would spend
-            // the message’s own budget on it.
-            const hint = said(result.deployment.failure.remediationHint);
-            lines.push(`  ${said(result.deployment.failure.message) || NO_DETAIL}${hint ? ` ${hint}` : ""}`);
-        }
+        lines.push(stageLine("deployment", result.deployment));
+        if (result.deployment.failure?.message)
+            lines.push(`  ${failureText(result.deployment.failure)}`);
     }
     // Gated on the redacted value rather than the raw one, so guidance that is
     // nothing but a link falls through to the next step instead of printing a
@@ -223,14 +236,38 @@ export function renderSummary(envelope) {
         lines.push("Setup complete.");
     return `${lines.join("\n")}\n`;
 }
+/**
+ * `Preview deployment: FAILED (fourier#app#preview#000001) — <url>`. On a
+ * failure the version is the reference the console's releases tab and the
+ * email carry, printed so everyone is looking at the same attempt. It is an
+ * identifier, exempt from `said` for the reason the operation reference is.
+ */
+function stageLine(kind, stage) {
+    const [label, state, url] = kind === "production" ? ["Production", stage.state, stage.productionUrl] : ["Preview deployment", stage.status ?? stage.state, stage.protectedUrl];
+    return `${label}: ${said(state)}${stage.failure && stage.versionId ? ` (${stage.versionId})` : ""}${url ? ` — ${url}` : ""}`;
+}
+/**
+ * The message, then the hint, each redacted and bounded on its own — exactly
+ * as `safeError` bounds them separately, so the hint never spends the
+ * message's budget. `|| NO_DETAIL` for the reason `safeError` has it: redaction
+ * can empty a string, and a failure reported as two spaces is worse than one
+ * that says plainly this CLI has nothing to show.
+ */
+function failureText(failure) {
+    const hint = said(failure.remediationHint);
+    return `${said(failure.message) || NO_DETAIL}${hint ? ` ${hint}` : ""}`;
+}
 export class CliError extends Error {
     code;
     operationRef;
     remediationHint;
-    constructor(code, message, operationRef, remediationHint) {
+    result;
+    /** `result` becomes the envelope's `result`: what the command knew about the operation when it failed. */
+    constructor(code, message, operationRef, remediationHint, result) {
         super(message);
         this.code = code;
         this.operationRef = operationRef;
         this.remediationHint = remediationHint;
+        this.result = result;
     }
 }

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

@@ -6,7 +6,7 @@ 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 { getAppSetup, outcomeFor, pickSourceFailure, readLine, waitForSettled } from "./operations.js";
+import { follow, getAppSetup, pickSourceFailure, readLine } from "./operations.js";
 import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertPreviewIntegrationsReady } from "./integrations.js";
@@ -106,17 +106,16 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         // the maker gets the app's real protected link, not the example one.
         // Past this point the app is saved and verified; a failure here is about
         // following the deployment, not about the save, and must say so.
-        let settled;
+        let summary;
         try {
-            settled = await waitForSettled(client, operationRef, output, options.waitOptions);
+            summary = await follow(client, operationRef, output, options.waitOptions);
         }
         catch (error) {
             if (error instanceof CliError)
                 throw error;
             throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Harbour saved and verified the app but could not follow its deployment (${error instanceof Error ? error.message.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").slice(0, 160) : "unknown error"}). Check again with \`harbour status\`.`, operationRef);
         }
-        const outcome = outcomeFor(settled, operationRef);
-        output(outcomeLine(outcome));
+        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;
@@ -128,7 +127,7 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         }
         if (setup?.pending?.length)
             output(`${setup.nextAction?.plainEnglish ?? "The app still needs setup."} Run \`harbour setup --operation ${operationRef}\`.`);
-        return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...outcome.summary, outcome: outcome.kind, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
+        return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...summary, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
     }
     catch (error) {
         throw await operationFailure(client, operationRef, error);
@@ -251,7 +250,7 @@ function refusal(failure, fallbackCode, fallbackMessage, operationRef) {
  */
 async function operationFailure(client, operationRef, error) {
     if (error instanceof CliError)
-        return error.operationRef ? error : new CliError(error.code, error.message, operationRef, error.remediationHint);
+        return error.operationRef ? error : new CliError(error.code, error.message, operationRef, error.remediationHint, error.result);
     const detail = errorDetail(error);
     const state = await probeOperation(client, operationRef);
     // A pending-setup operation is not a failed operation: nothing is wrong with
@@ -379,12 +378,13 @@ function safeVerificationResult(value, statusEvidence) {
             : {})
     };
 }
-function outcomeLine(outcome) {
-    switch (outcome.kind) {
-        case "live": return `Harbour deployed the app. Protected preview: ${outcome.summary.deployment?.protectedUrl ?? ""}`.trim();
-        case "production_live": return `The app is live in production: ${outcome.summary.production?.productionUrl ?? ""}`.trim();
-        case "waiting": return outcome.summary.waiting?.plainEnglish ?? "Harbour needs one more step in the Harbour console before it can deploy.";
-        case "no_deployment": return outcome.summary.nextStep ?? "Harbour saved the app; deployment has not started.";
+function outcomeLine(summary) {
+    switch (summary.outcome) {
+        case "live": return `Harbour deployed the app. Protected preview: ${summary.deployment?.protectedUrl ?? ""}`.trim();
+        case "production_live": return `The app is live in production: ${summary.production?.productionUrl ?? ""}`.trim();
+        case "waiting": return summary.waiting?.plainEnglish ?? "Harbour needs one more step in the Harbour console before it can deploy.";
+        // `running` and `no_deployment` both carry their own next step.
+        default: return summary.nextStep ?? "Harbour saved the app; deployment has not started.";
     }
 }
 const readApproval = readLine;

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

@@ -92,7 +92,7 @@ export function managedBlock() {
         "",
         "- Identity, data and files go through `@harbour/app-sdk` only: `harbour.identity.current()`, `harbour.data.from(table)`, `harbour.files.*`. Never open a database, storage bucket or company system from browser code, and never `fetch` a company URL directly.",
         "- Company systems (Slack, Gmail, warehouse views) are reached only through `harbour.integrations.execute(connection, {operation, resource, input})` with the connection and operation declared in `.harbour/integrations.json`. Operations are a closed set: `slack.channel.history` (user identity), `slack.message.post` (declared per app: `app` posts as the company's Slack bot, Isomorph AI, under the name IT approved; `user` posts as the signed-in person after their consent), `gmail.thread.list`, `gmail.message.read` and `gmail.message.send` (user identity — reads and one plain-text send as the signed-in person, resource `inbox`), `warehouse.view.read` (app identity). Resources are logical names, never IDs, URLs or tokens.",
-        "- `.harbour/integrations.json` starts with `\"connections\": {}` and stays that way until the app really calls a company system. Adding one is two steps: declare the connection with only the operations the app calls, then `harbour integrations request <connection> --reason \"<why>\" --app-root .` (and the same command with `--environment preview` before shipping). Every declared connection blocks the deploy until IT grants it, so a connection the app does not call is a deploy that never happens; a connection that is not declared cannot be requested at all (`CONNECTION_NOT_DECLARED`), so it never gets a grant. The file is strict JSON and cannot hold comments; the worked Slack and warehouse examples are in README.md and in the comment in `src/App.tsx`.",
+        "- `.harbour/integrations.json` starts with `\"connections\": {}` and stays that way until the app really calls a company system. Adding one is two steps: declare the connection — by the identifier `harbour integrations catalog --app-root .` lists, with only the operations the app calls and only channels, views and mailboxes the catalog shows as approved; never a guessed name — then `harbour integrations request <connection> --reason \"<why>\" --app-root .` (and the same command with `--environment preview` before shipping). Every declared connection blocks the deploy until IT grants it, so a connection the app does not call is a deploy that never happens; a connection that is not declared cannot be requested at all (`CONNECTION_NOT_DECLARED`), so it never gets a grant. The file is strict JSON and cannot hold comments; the worked Slack and warehouse examples are in README.md and in the comment in `src/App.tsx`.",
         "- A Slack message is sent only after the person presses an explicit Send control; pass a fresh UUID `idempotencyKey` per send action and reuse the same key when retrying that action. Never send from an effect, a timer or a background queue, and never send during checks.",
         "- A Slack message is posted either as the app (the company's Slack bot, Isomorph AI, under the IT-approved name: declare `\"presentation\": { \"displayName\": \"<app name>\" }` on the Slack connection, optional `iconEmoji`; every app-mode post ends with \"Posted by <app> on Isomorph\") or as the person (`\"identity\": \"user\"` on `slack.message.post`, their own consent; an older consent answers `USER_RECONNECT_REQUIRED` — offer Connect again) — never pretend one is the other. A post needs the bot in the channel: `/invite @Isomorph AI` there first.",
         "- Consent is only for user-identity operations (`slack.channel.history`, `gmail.*`, and `slack.message.post` declared `\"identity\": \"user\"`): call `harbour.integrations.connect(connection)` and, when it returns `consent_required`, open `authorizationUrl`. App-identity operations (`slack.message.post` declared `\"identity\": \"app\"`, `warehouse.view.read`) never call connect — it is refused as unapproved user access. Missing consent never falls back to another account.",
@@ -104,7 +104,7 @@ export function managedBlock() {
         "- 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. `harbour check` generates them from `migrations/` and the app's own source and deletes the ones the app no longer needs, so the way to keep them right is to run it in the same edit that changes the app — not to write or remove these files by hand. The pairing is two-way and the `flow` gate refuses the deploy in both directions. Start using a capability and it needs its own retained check: `harbour check` writes it, except for the ones it reports it cannot generate (`actions`, `realtime`), which you write yourself. 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: `harbour check` deletes the ones it generated, and one you wrote or edited is yours to delete, 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.",
         "- A generated check starts with a `// harbour:generated` line carrying a digest of its own body; that is how `harbour check` knows the file is still its to rewrite and remove. Edit one and it becomes yours: Harbour keeps your version, stops updating it and never deletes it, and keeping it honest is then your job. 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.*`. Replace the notes table with the app's own, or remove the \"Private files\" section, and the next `harbour check` rewrites and deletes to match — `.harbour/checks/files-journey.mjs` goes with that section, and you delete it by hand in that same edit only if you have edited it. 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 .` (types, build, then the pipeline's own kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, the generated journeys, operation coverage), `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.",
+        "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (types, build, then the pipeline's own kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, the generated journeys, operation coverage), `harbour integrations catalog --app-root .` (the company's connections and approved names, before declaring one), `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
     ].join("\n");

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.30";
+export const CLI_VERSION = "0.1.31";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
   "harbour": {
     "kitBundle": {
       "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
-      "version": "0.1.30"
+      "version": "0.1.31"
     }
   }
 }