@synap-core/cli 1.10.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";
@@ -150,6 +150,20 @@ function findCard(cards, name) {
     return (cards.find((c) => c.name.toLowerCase() === q) ??
         cards.find((c) => c.key.toLowerCase() === q));
 }
+/**
+ * When a name doesn't match a pack, it's often a VERB (e.g. `exa_search`) rather
+ * than its pack (`exa`). Find the pack that owns a verb by that id/label so the
+ * caller can point the user at the right `enable` target instead of a dead end.
+ */
+function findCardByVerb(cards, name) {
+    const q = name.trim().toLowerCase();
+    for (const card of cards) {
+        const verb = card.verbs.find((v) => v.verbId.toLowerCase() === q || v.label.toLowerCase() === q);
+        if (verb)
+            return { card, verb };
+    }
+    return undefined;
+}
 /** Status → badge glyph (●/◑/○) per §6. */
 function statusBadge(status) {
     switch (status) {
@@ -217,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
@@ -225,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) {
@@ -243,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) {
@@ -266,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);
@@ -283,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) {
@@ -335,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) {
@@ -380,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
@@ -428,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
@@ -551,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;
@@ -610,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);
@@ -630,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-
@@ -736,23 +760,85 @@ 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);
         }
     }
-    // Re-fetch to show the resulting (installed) status.
+    // Re-fetch to get the installed card (verbs + skillIds).
+    let after;
     try {
-        const after = findCard(await fetchCatalog(cfg, workspaceId), card.name);
-        if (after) {
-            console.log();
-            renderCardAny(after);
-        }
+        after = findCard(await fetchCatalog(cfg, workspaceId), card.name);
     }
     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
+    // with `cap enable`. This also removes the wrong-pod footgun the second command
+    // caused: `cap enable` (no --pod) targets the ACTIVE pod, not the install's
+    // --pod, so it "couldn't find" a capability installed on a different pod.
+    const autoEnabled = [];
+    const connectionReady = !after?.connection?.required || after?.connection?.state === "connected";
+    if (after && after.verbs.length > 0 && connectionReady) {
+        const reads = after.verbs.filter((v) => v.type === "read" && !v.enabled);
+        if (reads.length > 0) {
+            const idByName = reads.some((v) => !v.skillId)
+                ? new Map((await fetchSkills(cfg, workspaceId).catch(() => [])).map((s) => [s.name, s.id]))
+                : new Map();
+            const work = ora({ text: "Turning on read verbs…", color: "cyan" }).start();
+            try {
+                for (const v of reads) {
+                    const skillId = v.skillId ?? idByName.get(v.verbId);
+                    if (!skillId)
+                        continue;
+                    await hubPost(`/skills/${skillId}/approve`, { approved: true }, cfg);
+                    autoEnabled.push(v.label);
+                }
+                work.stop();
+            }
+            catch (err) {
+                work.stop();
+                log.dim(`(Couldn't auto-enable read verbs — run \`synap cap enable "${card.name}"\`. ${err.message})`);
+            }
+            try {
+                after = findCard(await fetchCatalog(cfg, workspaceId), card.name) ?? after;
+            }
+            catch {
+                // keep the pre-enable card for the render below
+            }
+        }
+    }
+    if (after) {
+        console.log();
+        renderCardAny(after);
+    }
     console.log();
-    log.dim(`Turn it on:  synap cap enable "${card.name}"`);
+    if (autoEnabled.length > 0) {
+        log.success(`Enabled ${autoEnabled.length} read verb${autoEnabled.length === 1 ? "" : "s"}: ${autoEnabled.join(", ")}`);
+    }
+    const pendingWrites = (after?.verbs ?? []).filter((v) => v.type !== "read" && !v.enabled);
+    if (pendingWrites.length > 0) {
+        log.dim(`${pendingWrites.length} write/action verb${pendingWrites.length === 1 ? "" : "s"} stay off (they ask approval per run). Turn on:  synap cap enable "${card.name}"`);
+    }
+    else if (autoEnabled.length === 0) {
+        log.dim(`Turn it on:  synap cap enable "${card.name}"`);
+    }
 }
 export async function capabilityEnable(name, opts) {
     let cfg;
@@ -760,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);
@@ -780,7 +866,7 @@ export async function capabilityEnable(name, opts) {
                 catalogNeedsDeploy();
                 return;
             }
-            log.error(err.message);
+            renderHubError(err);
             process.exit(1);
         }
         if (cards.length === 0) {
@@ -827,8 +913,10 @@ export async function capabilityEnable(name, opts) {
     }
     const spinner = ora({ text: `Resolving ${chalk.bold(name)}…`, color: "cyan" }).start();
     let card;
+    let catalog = [];
     try {
-        card = findCard(await fetchCatalog(cfg, workspaceId), name);
+        catalog = await fetchCatalog(cfg, workspaceId);
+        card = findCard(catalog, name);
         spinner.stop();
     }
     catch (err) {
@@ -838,10 +926,18 @@ 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) {
+        // A verb name (e.g. `exa_search`) isn't a pack — `enable` takes the PACK
+        // (`exa`). Point at the owning pack instead of dead-ending.
+        const owner = findCardByVerb(catalog, name);
+        if (owner) {
+            log.error(`"${name}" is a verb of the "${owner.card.name}" pack, not a capability itself.`);
+            log.dim(`Enable the pack (it lets you pick verbs):  synap cap enable "${owner.card.name}"`);
+            process.exit(1);
+        }
         log.error(`No capability named "${name}".`);
         log.dim("Run `synap cap list` to see what's available, or `synap cap add <name>` first.");
         process.exit(1);
@@ -929,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.
@@ -950,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);
@@ -971,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;
         }
@@ -991,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,
@@ -1010,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,
                 })),
             ],
         });
@@ -1021,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);
@@ -1040,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) {
@@ -1053,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}"`);
@@ -1076,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);
@@ -1160,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);
@@ -1177,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) {
@@ -1198,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")}`);
@@ -1246,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);
@@ -1324,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);
@@ -1335,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) {
@@ -1351,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)}`);
@@ -1387,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);
@@ -1430,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 ?? {});