@synap-core/cli 1.11.0 → 1.13.0

package/dist/commands/capability.js

@@ -4,7 +4,7 @@
  * A Capability is a named, installable PACK of what you (and your AI) can do
  * (e.g. "Google Workspace", "Discord Bot"). Tools = its connection; skills = its
  * verbs; templates = the catalog. The user only ever lists, adds, and enables a
- * PACK — never a bare tool or skill (CAPABILITIES-NORTH-STAR.md).
+ * PACK — never a bare tool or skill (CAPABILITIES-NORTH-STAR, team pod).
  *
  * A capability VERB is a runnable action backed by a skill (verbId = skill name).
  * `run` is the launcher: it parses arbitrary `--key value` flags into the skill's
@@ -15,9 +15,9 @@
 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 { resolveHubConfig, hubGet, hubPost, hubPatch, hubDelete, HubError, renderHubError } from "../lib/hub-client.js";
 import { unwrapList } from "../lib/unwrapList.js";
 import { log } from "../utils/logger.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -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) {
@@ -395,85 +402,66 @@ async function pollUntilConnected(cfg, provider, workspaceId, timeoutMs = 180_00
     return null;
 }
 /**
- * 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.
+ * 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 ensureConnection(cfg, workspaceId, card) {
-    const conn = card.connection;
-    if (!conn || !conn.required || conn.state === "connected")
-        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
-    // own diagnosis (which of not_declared / unauthenticated / unreachable, and
-    // the remedy). Only OPENING A BROWSER is doomed, and that is already guarded
-    // below. Short-circuiting on the card's cached state costs the real message.
-    // ── Vault credential — prompt + re-apply WITH params ──────────────────────
-    // The correct wiring: apply the template with the credential as a param, so the
-    // governed applier stores the secret AND links it into the connection tool's
-    // credentialRef (pod-wide, for a pod-scoped cap). A bare /vault/secrets write
-    // creates an orphan secret that is NOT linked to the tool — the old bug.
-    if (conn.kind === "vault") {
-        const hasParams = (card.installParams ?? []).some((p) => p.required);
-        if (hasParams) {
-            const collected = await collectInstallParams(card);
-            if (!collected)
-                return false;
-            return applyTemplateWithParams(cfg, card, workspaceId, collected, "Connecting");
-        }
-        // Fallback (older pod without install-params on the card): store the secret
-        // directly. May need manual linking if the tool's credentialRef doesn't match.
-        const service = conn.provider ?? card.key;
-        const answer = await prompts({
-            type: "password",
-            name: "value",
-            message: `Paste the ${chalk.bold(card.name)} credential (${service})`,
-        });
-        const value = answer.value;
-        if (!value) {
-            log.dim("Cancelled — no credential entered.");
-            return false;
-        }
-        const spinner = ora({ text: "Storing credential in the vault…", color: "cyan" }).start();
-        try {
-            await hubPost("/vault/secrets", { name: `${card.name} credential`, value, service, type: "credential", workspaceId }, cfg);
-            spinner.succeed(chalk.green(`Stored ${chalk.bold(service)} credential.`));
-            return true;
-        }
-        catch (err) {
-            spinner.fail(chalk.red("Failed to store credential"));
-            log.error(err.message);
-            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();
+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 {
-        res = (await hubPost("/connectors/connect", { provider, workspaceId }, cfg));
+        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) {
-        spinner.fail(chalk.red("Failed to resolve connection"));
-        log.error(err.message);
+        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") {
-        log.success(`${res.displayName ?? provider} is already connected.`);
+        // Both flows prefer the server's displayName here (falling back locally).
+        log.success(`${res.displayName ?? ctx.displayName} 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}"`);
+    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 (status === "provider_unavailable") {
+    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(`${card.name} is unavailable on this pod.`);
+        log.warn(`${ctx.cardName} is unavailable on this pod.`);
         if (res.message)
             log.dim(String(res.message));
         return false;
@@ -483,14 +471,14 @@ async function ensureConnection(cfg, workspaceId, card) {
     // 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}.`);
+        log.warn(`Couldn't start a connection for ${name(res)}.`);
         if (res.message)
             log.dim(String(res.message));
-        else
+        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 ${res.displayName ?? provider}`);
+    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:")}`);
@@ -500,13 +488,105 @@ async function ensureConnection(cfg, workspaceId, card) {
     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))}!`));
+        waitSpinner.succeed(chalk.green(`Connected ${chalk.bold(name(connected))}!`));
         return true;
     }
     waitSpinner.stop();
-    log.dim(`Didn't detect a connection yet — finish the browser flow, then re-run \`synap cap enable "${card.name}"\`.`);
+    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://) → rotate the linked secret in place, or
+ * apply the template with the key as a param. Returns true when the connection
+ * is (now) satisfied, false otherwise.
+ */
+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)
+        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
+    // own diagnosis (which of not_declared / unauthenticated / unreachable, and
+    // the remedy). Only OPENING A BROWSER is doomed, and that is already guarded
+    // below. Short-circuiting on the card's cached state costs the real message.
+    // ── Vault credential ──────────────────────────────────────────────────────
+    // Every write here must land on the secret the capability's tools actually
+    // read. A bare /vault/secrets write creates an orphan secret NOT linked to the
+    // tool's credentialRef: the CLI used to fall back to it and print success
+    // while every run kept the old key (unipile-linkedin, 2026-10-27).
+    if (conn.kind === "vault") {
+        // Installed with a live key → rotate THAT secret in place. The tools keep
+        // their vault://<id>, so the new value is what the next run reads; no
+        // template re-apply, so optional install params are not blanked either.
+        if (card.id && conn.account && conn.state === "connected") {
+            return rotateLinkedSecret(cfg, card, card.id, conn.account);
+        }
+        // No live key yet → apply the template WITH params: the governed applier
+        // stores the secret AND links it into the tool's credentialRef.
+        const hasParams = (card.installParams ?? []).some((p) => p.required);
+        if (hasParams) {
+            const collected = await collectInstallParams(card);
+            if (!collected)
+                return false;
+            return applyTemplateWithParams(cfg, card, workspaceId, collected, "Connecting");
+        }
+        log.error(`Can't connect ${card.name} from here.`);
+        log.dim(card.id
+            ? "The pod lists no install params for it and its tools point at no vault key that still exists."
+            : "The pod lists no install params for it.");
+        log.dim(`Re-install it with its key:  synap cap add "${card.key}"`);
+        return false;
+    }
+    // ── Provider OAuth (nango://) — open + poll ───────────────────────────────
+    const provider = conn.provider ?? card.key;
+    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,
+    });
+}
+/**
+ * Replace the value of the vault secret a capability's tools point at
+ * (`secretId` = the card's `connection.account`, the id in their
+ * `vault://<id>`), through the capability credentials door. The row keeps its
+ * id, so every reference to it now resolves to the new value and no second
+ * secret is written.
+ */
+async function rotateLinkedSecret(cfg, card, capabilityId, secretId) {
+    const answer = await prompts({
+        type: "password",
+        name: "value",
+        message: `Paste the new ${chalk.bold(card.name)} key`,
+    });
+    const value = answer.value;
+    if (!value) {
+        log.dim("Cancelled — no key entered. The current key is unchanged.");
+        return false;
+    }
+    const spinner = ora({ text: `Replacing the ${chalk.bold(card.name)} key…`, color: "cyan" }).start();
+    try {
+        await hubPatch(`/capabilities/${capabilityId}/credentials/${secretId}`, { value }, cfg);
+        spinner.succeed(chalk.green(`Replaced the ${chalk.bold(card.name)} key. Its tools use the new one from the next run.`));
+        return true;
+    }
+    catch (err) {
+        spinner.fail(chalk.red(`Couldn't replace the ${card.name} key — the current key is unchanged`));
+        renderHubError(err);
+        return false;
+    }
+}
 /**
  * Prompt for a template's REQUIRED install params (masked for secrets). Returns
  * the params map, or null if the user cancelled. Empty map when nothing required.
@@ -565,58 +645,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 +655,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 +675,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 +781,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 +793,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 +867,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 +887,7 @@ export async function capabilityEnable(name, opts) {
                 catalogNeedsDeploy();
                 return;
             }
-            log.error(err.message);
+            renderHubError(err);
             process.exit(1);
         }
         if (cards.length === 0) {
@@ -901,7 +947,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 +1046,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 +1067,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 +1088,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 +1108,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 +1131,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 +1142,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 +1164,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 +1177,13 @@ 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(card.connection.kind === "vault"
+            ? "Replacing the key its tools use."
+            : "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 +1206,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 +1290,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 +1307,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 +1328,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 +1390,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 +1468,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 +1479,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 +1495,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 +1531,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 +1574,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 ?? {});