@synap-core/cli 1.11.0 → 1.12.2

package/dist/commands/capability.js

@@ -15,7 +15,7 @@
 import chalk from "chalk";
 import ora from "ora";
 import prompts from "prompts";
-import { exec } from "child_process";
+import { openExternalUrl } from "../lib/safe-open.js";
 import { readFileSync } from "node:fs";
 import { resolveHubConfig, hubGet, hubPost, hubDelete, HubError, renderHubError } from "../lib/hub-client.js";
 import { unwrapList } from "../lib/unwrapList.js";
@@ -231,7 +231,12 @@ function accountLabel(account) {
     const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(account);
     return isUuid ? null : account;
 }
-/** A USABLE pack: name + each runnable verb as a ready-to-run command. */
+/**
+ * A USABLE pack: name + its verbs grouped by exec-mode as compact NAME lists.
+ * The full `--param` signature is NOT dumped per verb here — that turned a pack
+ * with 20+ verbs into an unscannable wall. The list answers "what can this do?";
+ * `synap cap show <verb>` gives the exact run command for the one you pick.
+ */
 function renderUsable(card) {
     const label = accountLabel(card.connection?.account);
     const acct = label
@@ -239,13 +244,19 @@ function renderUsable(card) {
         : card.connection?.provider
             ? chalk.dim(` · ${card.connection.provider} connected`)
             : "";
-    console.log(`  ${chalk.green("●")} ${chalk.bold(card.name)}${acct}`);
-    for (const v of card.verbs.filter((x) => x.runnable)) {
-        const mark = v.type !== "read" ? chalk.yellow("✋") : chalk.green("▸");
-        const note = v.type !== "read"
-            ? chalk.yellow(" — asks approval")
-            : chalk.dim(" — instant");
-        console.log(`      ${mark} ${chalk.cyan(runCommand(v))}${note}`);
+    const runnable = card.verbs.filter((x) => x.runnable);
+    const instant = runnable.filter((v) => v.type === "read");
+    const approval = runnable.filter((v) => v.type !== "read");
+    const count = chalk.dim(` · ${runnable.length} verb${runnable.length === 1 ? "" : "s"}` +
+        (approval.length ? `, ${approval.length} need approval` : ""));
+    console.log(`  ${chalk.green("●")} ${chalk.bold(card.name)}${acct}${count}`);
+    if (instant.length > 0) {
+        console.log(`      ${chalk.green("▸")} ${chalk.dim("instant ")} ` +
+            instant.map((v) => chalk.cyan(v.verbId)).join("  "));
+    }
+    if (approval.length > 0) {
+        console.log(`      ${chalk.yellow("✋")} ${chalk.dim("approval")} ` +
+            approval.map((v) => chalk.cyan(v.verbId)).join("  "));
     }
     const off = card.verbs.filter((v) => !v.runnable);
     if (off.length > 0) {
@@ -257,6 +268,12 @@ function renderUsable(card) {
 function renderSetup(card) {
     console.log(`  ${chalk.yellow("◌")} ${chalk.bold(card.name)}  ${chalk.dim(statusSummary(card))}`);
     console.log(`      ${chalk.cyan("→")} ${card.nextAction.hint || `synap cap enable "${card.name}"`}`);
+    // An expired connection reads as "needs a step", but the fix is a RECONNECT, not
+    // an enable — show the exact command so the hint's "Reconnect …" prose is
+    // actionable (the state word tells WHAT, this tells HOW).
+    if (card.connection?.state === "expired") {
+        console.log(`        ${chalk.dim(`synap cap connect "${card.name}" --reconnect`)}`);
+    }
 }
 /** An AVAILABLE pack: one line — name · what it offers · add command. */
 function renderAvailable(card) {
@@ -280,7 +297,7 @@ export async function capabilityList(opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -297,7 +314,7 @@ export async function capabilityList(opts) {
             return;
         }
         spinner?.fail(chalk.red("Failed to fetch capabilities"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     if (opts.json) {
@@ -349,18 +366,8 @@ export async function capabilityList(opts) {
 // ── Connection sub-flow (shared by enable + connect) ────────────────────────
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function openBrowser(url) {
-    const platform = process.platform;
-    const cmd = platform === "darwin"
-        ? `open "${url}"`
-        : platform === "win32"
-            ? `start "" "${url}"`
-            : `xdg-open "${url}"`;
-    try {
-        exec(cmd);
-    }
-    catch {
-        // silently ignore — caller already prints the URL
-    }
+    // argv only, http(s) only — never a shell string (`safe-open.ts`).
+    openExternalUrl(url);
 }
 /** Short host label for a pod (for picker headers: "→ pod.perso…"). */
 function podHostLabel(cfg) {
@@ -394,14 +401,117 @@ async function pollUntilConnected(cfg, provider, workspaceId, timeoutMs = 180_00
     }
     return null;
 }
+/**
+ * The ONE "connect a provider" path: resolve `/connectors/connect`, open the
+ * browser on the returned `redirectUrl`, and poll (self-completing door) until
+ * the provider flips to `connected`. Shared by the capability-card flow
+ * (`ensureConnection`) and the raw-provider discovery picker
+ * (`capabilityConnect` with no name), so both reach the identical endpoint,
+ * status handling, browser-open and poll semantics.
+ *
+ * `cardName` is the discriminator: when present the caller is connecting on
+ * behalf of a capability card, which enables the card-aware `provider_required`
+ * / `provider_unavailable` branches and the named re-run + timeout hints. The
+ * raw-picker path already holds an explicit provider id, so those branches do
+ * not apply to it — it goes straight from `connected` to the `redirectUrl`
+ * check, exactly as before.
+ *
+ * `displayName` is the local fallback name: the provider's list label for the
+ * raw picker, the provider id for the card flow (a card has no separate label).
+ */
+async function connectProviderOAuth(cfg, provider, workspaceId, ctx) {
+    const isCard = ctx.cardName !== undefined;
+    // Card flow prefers the server's displayName (falling back to the provider
+    // id); the raw picker uses its own list label verbatim.
+    const name = (r) => isCard ? String(r.displayName ?? ctx.displayName) : ctx.displayName;
+    const spinner = ora({
+        text: isCard ? `Resolving ${chalk.bold(provider)} connection…` : `Connecting ${chalk.bold(ctx.displayName)}…`,
+        color: "cyan",
+    }).start();
+    let res;
+    try {
+        const body = { provider };
+        if (workspaceId)
+            body.workspaceId = workspaceId;
+        if (ctx.forceReauth)
+            body.forceReauth = true;
+        res = (await hubPost("/connectors/connect", body, cfg));
+        spinner.stop();
+    }
+    catch (err) {
+        if (isCard)
+            spinner.fail(chalk.red("Failed to resolve connection"));
+        else
+            spinner.stop();
+        renderHubError(err);
+        return false;
+    }
+    const status = String(res.status);
+    if (status === "connected") {
+        // Both flows prefer the server's displayName here (falling back locally).
+        log.success(`${res.displayName ?? ctx.displayName} is already connected.`);
+        return true;
+    }
+    if (isCard && status === "provider_required") {
+        log.warn(`Couldn't resolve a single provider for ${ctx.cardName}.`);
+        log.dim(`Connect it directly:  synap cap connect "${ctx.cardName}"`);
+        return false;
+    }
+    if (isCard && status === "provider_unavailable") {
+        // The pod can't offer this provider (not declared / unreachable / malformed).
+        // The server message already names the real cause + remedy — print it as-is.
+        // No browser, and no "re-run connect": re-running cannot fix a server-side gap.
+        log.warn(`${ctx.cardName} is unavailable on this pod.`);
+        if (res.message)
+            log.dim(String(res.message));
+        return false;
+    }
+    // setup_required (or any status this CLI doesn't know) → only ever open a
+    // browser when the server actually handed us a URL. An older/newer pod that
+    // returns a status we don't handle must NOT send the user to "undefined".
+    const redirectUrl = typeof res.redirectUrl === "string" && res.redirectUrl.length > 0 ? res.redirectUrl : null;
+    if (!redirectUrl) {
+        log.warn(`Couldn't start a connection for ${name(res)}.`);
+        if (res.message)
+            log.dim(String(res.message));
+        else if (isCard)
+            log.dim(`The pod returned status "${status}" with no connect URL. Check the pod's connector configuration.`);
+        return false;
+    }
+    log.heading(`Connect ${name(res)}`);
+    console.log();
+    console.log(`  Opening OAuth flow in your browser…`);
+    console.log(`  ${chalk.dim("If it didn't open, paste this URL:")}`);
+    console.log(`  ${chalk.underline(chalk.cyan(redirectUrl))}`);
+    console.log();
+    openBrowser(redirectUrl);
+    const waitSpinner = ora({ text: "Waiting for you to finish in the browser…", color: "cyan" }).start();
+    const connected = await pollUntilConnected(cfg, provider, workspaceId);
+    if (connected) {
+        waitSpinner.succeed(chalk.green(`Connected ${chalk.bold(name(connected))}!`));
+        return true;
+    }
+    waitSpinner.stop();
+    log.dim(isCard
+        ? `Didn't detect a connection yet — finish the browser flow, then re-run \`synap cap enable "${ctx.cardName}"\`.`
+        : `Didn't detect a connection yet — finish the browser flow, then re-run.`);
+    return false;
+}
 /**
  * Ensure a capability's required connection is satisfied. Provider (nango://) →
  * OAuth open + poll. Vault (vault://) → prompt for the key, POST /vault/secrets.
  * Returns true when the connection is (now) satisfied, false otherwise.
  */
-async function ensureConnection(cfg, workspaceId, card) {
+async function ensureConnection(cfg, workspaceId, card, 
+// Force a re-auth even when the card reports `state === "connected"`. The card
+// reflects a connection RECORD's existence, not its token's HEALTH, so an
+// expired/revoked token still reads "connected" — only a forced fresh OAuth
+// fixes it. Threaded to the provider door as `forceReauth`.
+forceReconnect = false) {
     const conn = card.connection;
-    if (!conn || !conn.required || conn.state === "connected")
+    if (!conn || !conn.required)
+        return true;
+    if (conn.state === "connected" && !forceReconnect)
         return true;
     // NOTE: `state === "unavailable"` is deliberately NOT short-circuited here.
     // Resolving the door is not an OAuth attempt — it returns 200 with the pod's
@@ -442,70 +552,19 @@ async function ensureConnection(cfg, workspaceId, card) {
         }
         catch (err) {
             spinner.fail(chalk.red("Failed to store credential"));
-            log.error(err.message);
+            renderHubError(err);
             return false;
         }
     }
     // ── Provider OAuth (nango://) — open + poll ───────────────────────────────
     const provider = conn.provider ?? card.key;
-    const spinner = ora({ text: `Resolving ${chalk.bold(provider)} connection…`, color: "cyan" }).start();
-    let res;
-    try {
-        res = (await hubPost("/connectors/connect", { provider, workspaceId }, cfg));
-        spinner.stop();
-    }
-    catch (err) {
-        spinner.fail(chalk.red("Failed to resolve connection"));
-        log.error(err.message);
-        return false;
-    }
-    const status = String(res.status);
-    if (status === "connected") {
-        log.success(`${res.displayName ?? provider} is already connected.`);
-        return true;
-    }
-    if (status === "provider_required") {
-        log.warn(`Couldn't resolve a single provider for ${card.name}.`);
-        log.dim(`Connect it directly:  synap cap connect "${card.name}"`);
-        return false;
-    }
-    if (status === "provider_unavailable") {
-        // The pod can't offer this provider (not declared / unreachable / malformed).
-        // The server message already names the real cause + remedy — print it as-is.
-        // No browser, and no "re-run connect": re-running cannot fix a server-side gap.
-        log.warn(`${card.name} is unavailable on this pod.`);
-        if (res.message)
-            log.dim(String(res.message));
-        return false;
-    }
-    // setup_required (or any status this CLI doesn't know) → only ever open a
-    // browser when the server actually handed us a URL. An older/newer pod that
-    // returns a status we don't handle must NOT send the user to "undefined".
-    const redirectUrl = typeof res.redirectUrl === "string" && res.redirectUrl.length > 0 ? res.redirectUrl : null;
-    if (!redirectUrl) {
-        log.warn(`Couldn't start a connection for ${res.displayName ?? provider}.`);
-        if (res.message)
-            log.dim(String(res.message));
-        else
-            log.dim(`The pod returned status "${status}" with no connect URL. Check the pod's connector configuration.`);
-        return false;
-    }
-    log.heading(`Connect ${res.displayName ?? provider}`);
-    console.log();
-    console.log(`  Opening OAuth flow in your browser…`);
-    console.log(`  ${chalk.dim("If it didn't open, paste this URL:")}`);
-    console.log(`  ${chalk.underline(chalk.cyan(redirectUrl))}`);
-    console.log();
-    openBrowser(redirectUrl);
-    const waitSpinner = ora({ text: "Waiting for you to finish in the browser…", color: "cyan" }).start();
-    const connected = await pollUntilConnected(cfg, provider, workspaceId);
-    if (connected) {
-        waitSpinner.succeed(chalk.green(`Connected ${chalk.bold(String(connected.displayName ?? provider))}!`));
-        return true;
-    }
-    waitSpinner.stop();
-    log.dim(`Didn't detect a connection yet — finish the browser flow, then re-run \`synap cap enable "${card.name}"\`.`);
-    return false;
+    return connectProviderOAuth(cfg, provider, workspaceId, {
+        // A card has no separate display name — the provider id is the fallback the
+        // server's displayName (when sent) takes precedence over.
+        displayName: provider,
+        cardName: card.name,
+        forceReauth: forceReconnect,
+    });
 }
 /**
  * Prompt for a template's REQUIRED install params (masked for secrets). Returns
@@ -565,58 +624,9 @@ async function applyTemplateWithParams(cfg, card, workspaceId, params, verb) {
     }
     catch (err) {
         spinner.fail(chalk.red(`Failed to ${verb.toLowerCase()} ${card.name}`));
-        log.error(err.message);
-        return false;
-    }
-}
-/**
- * Connect a RAW provider chosen from the discovery picker (not tied to a
- * capability card): start OAuth via `/connectors/connect`, open the browser, and
- * poll until it flips to connected. Same door + poll the card flow uses.
- */
-async function connectProviderFlow(cfg, provider, displayName, workspaceId) {
-    const spinner = ora({ text: `Connecting ${chalk.bold(displayName)}…`, color: "cyan" }).start();
-    let res;
-    try {
-        const body = { provider };
-        if (workspaceId)
-            body.workspaceId = workspaceId;
-        res = (await hubPost("/connectors/connect", body, cfg));
-        spinner.stop();
-    }
-    catch (err) {
-        spinner.stop();
         renderHubError(err);
         return false;
     }
-    if (String(res.status) === "connected") {
-        log.success(`${res.displayName ?? displayName} is already connected.`);
-        return true;
-    }
-    const redirectUrl = typeof res.redirectUrl === "string" && res.redirectUrl.length > 0 ? res.redirectUrl : null;
-    if (!redirectUrl) {
-        log.warn(`Couldn't start a connection for ${displayName}.`);
-        // Covers provider_unavailable too — the server message names the real cause.
-        if (res.message)
-            log.dim(String(res.message));
-        return false;
-    }
-    log.heading(`Connect ${displayName}`);
-    console.log();
-    console.log(`  Opening OAuth flow in your browser…`);
-    console.log(`  ${chalk.dim("If it didn't open, paste this URL:")}`);
-    console.log(`  ${chalk.underline(chalk.cyan(redirectUrl))}`);
-    console.log();
-    openBrowser(redirectUrl);
-    const waitSpinner = ora({ text: "Waiting for you to finish in the browser…", color: "cyan" }).start();
-    const connected = await pollUntilConnected(cfg, provider, workspaceId);
-    if (connected) {
-        waitSpinner.succeed(chalk.green(`Connected ${chalk.bold(displayName)}!`));
-        return true;
-    }
-    waitSpinner.stop();
-    log.dim(`Didn't detect a connection yet — finish the browser flow, then re-run.`);
-    return false;
 }
 export async function capabilityAdd(name, opts) {
     let cfg;
@@ -624,7 +634,7 @@ export async function capabilityAdd(name, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -644,7 +654,7 @@ export async function capabilityAdd(name, opts) {
             return;
         }
         spinner.fail(chalk.red("Failed to fetch catalog"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     // No name given → open an interactive picker over the AVAILABLE (not-yet-
@@ -750,7 +760,7 @@ export async function capabilityAdd(name, opts) {
         }
         catch (err) {
             addSpinner.fail(chalk.red(`Failed to add ${card.name}`));
-            log.error(err.message);
+            renderHubError(err);
             process.exit(1);
         }
     }
@@ -762,6 +772,21 @@ export async function capabilityAdd(name, opts) {
     catch {
         // best-effort — the add already succeeded
     }
+    // CONNECT-first: a provider capability that isn't connected yet runs the OAuth
+    // flow now, so `cap add` is the ONE happy-path door (apply → connect → enable
+    // reads). `ensureConnection` is the shared provider+OAuth path; a failed or
+    // timed-out OAuth returns false and leaves the card un-connected — recover
+    // with `synap cap connect "<name>"`. No-connection / already-connected cards
+    // skip this.
+    if (after?.connection?.required && after.connection.state !== "connected") {
+        await ensureConnection(cfg, workspaceId, after);
+        try {
+            after = findCard(await fetchCatalog(cfg, workspaceId), card.name) ?? after;
+        }
+        catch {
+            // keep the pre-connect card
+        }
+    }
     // AUTO-ENABLE the read verbs, so install is ONE step, not two. Reads are the
     // `auto`-governance, no-side-effect verbs — safe to turn on without asking.
     // Write/action verbs stay OFF (they ask approval per run); enable them later
@@ -821,7 +846,7 @@ export async function capabilityEnable(name, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -841,7 +866,7 @@ export async function capabilityEnable(name, opts) {
                 catalogNeedsDeploy();
                 return;
             }
-            log.error(err.message);
+            renderHubError(err);
             process.exit(1);
         }
         if (cards.length === 0) {
@@ -901,7 +926,7 @@ export async function capabilityEnable(name, opts) {
             return;
         }
         spinner.fail(chalk.red("Failed to fetch catalog"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     if (!card) {
@@ -1000,7 +1025,7 @@ export async function capabilityEnable(name, opts) {
     }
     catch (err) {
         work.fail(chalk.red("Failed while applying your selection"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     // (d) Report what changed + an example run.
@@ -1021,7 +1046,7 @@ export async function capabilityConnect(name, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -1042,7 +1067,7 @@ export async function capabilityConnect(name, opts) {
         }
         catch (err) {
             spin.stop();
-            log.error(err.message);
+            renderHubError(err);
             log.dim("Couldn't reach the pod's connector service.");
             return;
         }
@@ -1062,18 +1087,22 @@ export async function capabilityConnect(name, opts) {
         }
         const connectable = providers.filter((p) => !p.connected);
         const connected = providers.filter((p) => p.connected);
-        if (connectable.length === 0) {
+        // --reconnect: the point is to re-auth an ALREADY-connected (but expired)
+        // service, so connected rows become selectable (a fresh OAuth) rather than
+        // disabled, and "everything already connected" is no longer a dead end.
+        if (connectable.length === 0 && !opts.reconnect) {
             log.heading("Everything connectable here is already connected.");
             for (const p of connected)
                 log.dim(`  ${chalk.green("✓")} ${p.displayName ?? p.provider}`);
+            log.dim("Reconnect an expired one:  synap cap connect --reconnect");
             return;
         }
         const answer = await prompts({
             type: "select",
             name: "id",
-            message: `Connect a service ${chalk.dim(`→ ${podHostLabel(cfg)}`)}`,
-            // Connectable first; already-connected (disabled) grouped at the end —
-            // mirrors the `cap add` picker so the disabled rows don't scatter.
+            message: `${opts.reconnect ? "Reconnect" : "Connect"} a service ${chalk.dim(`→ ${podHostLabel(cfg)}`)}`,
+            // Connectable first; already-connected grouped at the end — disabled in the
+            // normal flow, but SELECTABLE (for a forced re-auth) under --reconnect.
             choices: [
                 ...connectable.map((p) => ({
                     title: p.displayName ?? p.provider,
@@ -1081,9 +1110,9 @@ export async function capabilityConnect(name, opts) {
                 })),
                 ...connected.map((p) => ({
                     title: `${p.displayName ?? p.provider} ${chalk.green("✓ connected")}`,
-                    description: "already connected",
+                    description: opts.reconnect ? "re-authenticate" : "already connected",
                     value: p.id,
-                    disabled: true,
+                    disabled: !opts.reconnect,
                 })),
             ],
         });
@@ -1092,7 +1121,10 @@ export async function capabilityConnect(name, opts) {
             return;
         }
         const chosen = providers.find((p) => p.id === answer.id);
-        const ok = await connectProviderFlow(cfg, chosen.id, chosen.displayName ?? chosen.provider, workspaceId);
+        const ok = await connectProviderOAuth(cfg, chosen.id, workspaceId, {
+            displayName: chosen.displayName ?? chosen.provider,
+            forceReauth: opts.reconnect ?? false,
+        });
         // A connect that did not connect must not report success to a caller/script.
         if (!ok)
             process.exit(1);
@@ -1111,7 +1143,7 @@ export async function capabilityConnect(name, opts) {
             return;
         }
         spinner.fail(chalk.red("Failed to fetch catalog"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     if (!card) {
@@ -1124,7 +1156,11 @@ export async function capabilityConnect(name, opts) {
         log.dim(`Enable its verbs:  synap cap enable "${card.name}"`);
         return;
     }
-    const ok = await ensureConnection(cfg, workspaceId, card);
+    if (opts.reconnect) {
+        log.heading(`Reconnecting ${card.name}`);
+        log.dim("Forcing a fresh sign-in — your previous access had expired or was revoked.");
+    }
+    const ok = await ensureConnection(cfg, workspaceId, card, opts.reconnect ?? false);
     if (!ok)
         process.exit(1);
     log.dim(`Now enable its verbs:  synap cap enable "${card.name}"`);
@@ -1147,7 +1183,7 @@ export async function capabilityDisconnect(name, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -1231,7 +1267,7 @@ export async function capabilityShow(name, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -1248,7 +1284,7 @@ export async function capabilityShow(name, opts) {
             return;
         }
         spinner?.fail(chalk.red("Failed to fetch catalog"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     if (!card) {
@@ -1269,20 +1305,34 @@ export async function capabilityShow(name, opts) {
         const c = card.connection;
         // `unavailable` is dim, not red: it isn't the user's fault and isn't fixable
         // by connecting — red reads as "you have a missing credential to go fix".
-        const stateColor = c.state === "connected"
-            ? chalk.green
-            : c.state === "expired"
-                ? chalk.yellow
-                : c.state === "unavailable"
-                    ? chalk.dim
-                    : chalk.red;
+        // Unverified: the pod could not actually check (a broker/list fault), not a
+        // checked absence. Render distinctly from a plain "missing" — that would
+        // falsely claim "you never connected this".
+        const stateColor = c.unverified
+            ? chalk.yellow
+            : c.state === "connected"
+                ? chalk.green
+                : c.state === "expired"
+                    ? chalk.yellow
+                    : c.state === "unavailable"
+                        ? chalk.dim
+                        : chalk.red;
+        const stateLabel = c.unverified ? "couldn't check" : c.state;
         const parts = [
             c.kind ?? "connection",
             c.provider ? chalk.dim(`(${c.provider})`) : "",
             c.account ? chalk.dim(c.account) : "",
-            stateColor(c.state),
+            stateColor(stateLabel),
         ].filter(Boolean);
         console.log(`  ${chalk.bold("Connection")}  ${parts.join(" ")}`);
+        // Expired = previously connected, token now dead. Surface the exact command to
+        // fix it — the state word alone tells WHAT, not HOW (the user's original ask).
+        if (c.state === "expired") {
+            console.log(`      ${chalk.yellow("→")} its access expired — reconnect:  synap cap connect "${card.name}" --reconnect`);
+        }
+        else if (c.unverified) {
+            console.log(`      ${chalk.yellow("→")} ${c.unverified.message || c.unverified.reason} — retry:  synap cap show "${card.name}"`);
+        }
     }
     else {
         console.log(`  ${chalk.bold("Connection")}  ${chalk.dim("none required")}`);
@@ -1317,7 +1367,7 @@ export async function capabilityRun(verb, params, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -1395,7 +1445,7 @@ export async function capabilityTest(verb, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -1406,7 +1456,7 @@ export async function capabilityTest(verb, opts) {
     }
     catch (err) {
         spinner.fail(chalk.red("Failed to resolve capability"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     if (!skillId) {
@@ -1422,7 +1472,7 @@ export async function capabilityTest(verb, opts) {
     }
     catch (err) {
         spinner.fail(chalk.red(`Dry-run failed for ${verb}`));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     log.heading(`Dry-run preview — ${chalk.bold(verb)}`);
@@ -1458,7 +1508,7 @@ export async function capabilityCreate(file, opts) {
         cfg = await resolveHubConfig();
     }
     catch (err) {
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const workspaceId = requireWorkspace(opts, cfg);
@@ -1501,7 +1551,7 @@ export async function capabilityCreate(file, opts) {
     }
     catch (err) {
         spinner.fail(chalk.red("Failed to create capability"));
-        log.error(err.message);
+        renderHubError(err);
         process.exit(1);
     }
     const created = (res.created ?? {});