@ishlabs/cli 0.19.0 → 0.20.0

package/dist/index.js

@@ -4,7 +4,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { runTunnel, runDetached, connectStatus, disconnect } from "./connect.js";
-import { login, decodeJwtClaims } from "./auth.js";
+import { login, decodeJwtClaims, isTokenExpired } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
@@ -27,8 +27,9 @@ import { tagAlias, ALIAS_PREFIX } from "./lib/alias-store.js";
 import { output } from "./lib/output.js";
 import { ishDir } from "./lib/paths.js";
 import { findInstalledSkill } from "./lib/skill-content.js";
-import { exitWithFlush, initObservability } from "./lib/observability.js";
+import { initObservability } from "./lib/observability.js";
 import { setSurfaceBaggage } from "./lib/baggage.js";
+import { resolveId } from "./lib/alias-store.js";
 import pkg from "../package.json" with { type: "json" };
 const { version } = pkg;
 // Bootstrap observability before anything else so the very first
@@ -58,31 +59,61 @@ program
 program.configureOutput({
     outputError: () => { },
 });
+// Enable Commander's built-in suggestion engine ("did you mean 'workspace'?"
+// for typos). Closes part of ISSUE-022.
+program.showSuggestionAfterError(true);
 program.exitOverride((err) => {
-    // Help and --version are normal exit-0 paths, not errors.
+    // Help and --version are normal exit-0 paths, not errors. process.exit
+    // is synchronous so the right exit code propagates regardless of any
+    // in-flight async work — Commander will otherwise rethrow CommanderError
+    // and Node's default uncaughtException handler exits with the error's
+    // own exitCode (1) before our async exitWithFlush gets to run.
     if (err.code === "commander.helpDisplayed"
         || err.code === "commander.version"
         || err.code === "commander.help") {
-        void exitWithFlush(0);
-        return;
+        process.exit(0);
     }
+    // Pattern E + ISSUE-022: the previous envelope used a literal "<command>"
+    // placeholder in suggestions that was never substituted. Reconstruct
+    // the right help target based on what kind of error fired:
+    //   - unknownCommand   → point at top-level `ish --help` (the user's
+    //                        firstWord IS the typo; no point pointing to it)
+    //   - missingArgument /
+    //     requiredOption   → point at the actual command's --help
+    //                        (`ish workspace --help` etc.)
+    // ISSUE-022.
+    const userArgs = process.argv.slice(2);
+    const firstWord = userArgs.find((a) => !a.startsWith("-")) ?? "";
+    const isUnknownCommand = err.code === "commander.unknownCommand"
+        || err.code === "commander.help" && /unknown/i.test(err.message);
+    const helpPath = isUnknownCommand || !firstWord ? "ish --help" : `ish ${firstWord} --help`;
     // Detect --json without relying on parsed opts (parse may have failed).
     const useJson = process.argv.includes("--json") || !process.stdout.isTTY;
+    // Strip the redundant "error: " prefix Commander adds — the envelope
+    // field is already called "error" (ISSUE-022).
+    const cleanedMessage = err.message.replace(/^error:\s*/i, "");
     const envelope = {
-        error: err.message,
+        error: cleanedMessage,
         error_code: "usage_error",
-        status: 0,
+        // Pattern D: omit `status` entirely when there's no upstream HTTP
+        // status to report. The previous `status: 0` was meaningless and
+        // confused agents branching on the field.
         retryable: false,
-        suggestions: ["Run `ish <command> --help` for usage"],
+        suggestions: [`Run \`${helpPath}\` for usage`],
     };
     if (useJson) {
         console.error(JSON.stringify(envelope));
     }
     else {
-        console.error(`Error: ${err.message}`);
-        console.error("  → Run `ish <command> --help` for usage");
+        console.error(`Error: ${cleanedMessage}`);
+        console.error(`  → Run \`${helpPath}\``);
     }
-    void exitWithFlush(EXIT_USAGE);
+    // Synchronous exit so the documented usage exit code (2) actually
+    // propagates. exitWithFlush is async — its inner process.exit only
+    // fires after Commander has already rethrown CommanderError, at which
+    // point Node's default handler exits with the error's exitCode (1).
+    // Pattern E (ISSUE-021).
+    process.exit(EXIT_USAGE);
 });
 // Global options
 program
@@ -102,8 +133,55 @@ program
 program
     .command("login")
     .description("Authenticate with ish via your browser")
-    .action(async (_opts, cmd) => {
+    .option("-f, --force", "Re-run the browser flow even if already authenticated (replaces the saved token)")
+    .addHelpText("after", `
+By default, \`ish login\` short-circuits when there's already a valid
+saved token — it tells you who you're logged in as and exits without
+opening a browser. Pass --force to re-run the flow anyway (e.g. to
+switch accounts).
+
+Without the guard, every reflexive \`ish login\` opens a new browser
+tab AND registers a fresh OAuth client (orphaning the previous one
+on the auth server). The guard prevents both.
+
+Examples:
+  $ ish login              # noop if already authenticated
+  $ ish login --force      # always re-run`)
+    .action(async (opts, cmd) => {
     await runInline(cmd, async (globals) => {
+        // ISSUE-007: idempotency guard. Default behavior on an already-
+        // authenticated session is to short-circuit with a friendly
+        // "Already logged in as ..." message. Pass --force to bypass.
+        if (!opts.force) {
+            const existing = loadConfig();
+            const existingToken = existing.access_token;
+            if (existingToken && !isTokenExpired(existingToken)) {
+                const claims = decodeJwtClaims(existingToken);
+                const email = typeof claims?.email === "string" ? claims.email : "(no email in token)";
+                const exp = typeof claims?.exp === "number" ? claims.exp : 0;
+                const remainingSec = Math.max(0, exp - Math.floor(Date.now() / 1000));
+                const remainingMin = Math.floor(remainingSec / 60);
+                // Code-review #7: previously this called output(...) for the
+                // structured envelope AND console.error(...) for the human line —
+                // human-mode users saw the key-value dump on stdout AND the
+                // cleaner sentence on stderr (duplicate). JSON consumers get the
+                // structured envelope; human-mode users get just the stderr
+                // sentence. Single output path per mode.
+                if (globals.json) {
+                    output({
+                        message: "Already logged in",
+                        email,
+                        token_valid: true,
+                        expires_in_seconds: remainingSec,
+                        hint: "Pass --force to re-run the browser flow (e.g. to switch accounts).",
+                    }, true);
+                }
+                else if (!globals.quiet) {
+                    console.error(`Already logged in as ${email} (token valid, expires in ${remainingMin}m). Pass --force to switch accounts.`);
+                }
+                return;
+            }
+        }
         const tokens = await login({ dev: globals.dev });
         const config = loadConfig();
         config.access_token = tokens.accessToken;
@@ -159,19 +237,39 @@ program
         // Resolve names of active resources. Failures are non-fatal — we still
         // return the saved IDs so the user knows what's configured.
         const client = token ? new ApiClient({ apiUrl, token }) : null;
+        // Helper: look up an active ref's name; on failure attach a `warning`
+        // field so the user can tell apart "name unavailable due to transient"
+        // vs. "this active ref is orphan — switch or clear it". Pattern A.
+        const ORPHAN_HINT = (kind) => `Active ${kind} is no longer accessible (deleted, moved workspace, or auth issue). Use \`ish ${kind} use <id>\` to switch, or \`ish ${kind} use --clear\` to drop.`;
+        const lookupName = async (path) => {
+            if (!client)
+                return {};
+            try {
+                const row = await client.get(path);
+                return row?.name ? { name: row.name } : {};
+            }
+            catch (err) {
+                // Distinguish missing-entity (404) from other failures. Either
+                // way the user benefits from the warning; the 404 specifically
+                // means "orphan", anything else is "couldn't confirm".
+                const status = err?.status;
+                if (status === 404)
+                    return { warning: "orphan — entity no longer exists in this workspace" };
+                return { warning: "name lookup failed (auth, network, or permission)" };
+            }
+        };
         let workspace = null;
         if (config.workspace) {
             workspace = {
                 id: config.workspace,
                 alias: tagAlias(ALIAS_PREFIX.workspace, config.workspace),
             };
-            if (client) {
-                try {
-                    const ws = await client.get(`/products/${config.workspace}`);
-                    if (ws?.name)
-                        workspace.name = ws.name;
-                }
-                catch { /* keep id+alias only */ }
+            const { name, warning } = await lookupName(`/products/${config.workspace}`);
+            if (name)
+                workspace.name = name;
+            if (warning) {
+                workspace.warning = warning;
+                workspace.hint = ORPHAN_HINT("workspace");
             }
         }
         let study = null;
@@ -180,13 +278,12 @@ program
                 id: config.study,
                 alias: tagAlias(ALIAS_PREFIX.study, config.study),
             };
-            if (client) {
-                try {
-                    const s = await client.get(`/studies/${config.study}`);
-                    if (s?.name)
-                        study.name = s.name;
-                }
-                catch { /* keep id+alias only */ }
+            const { name, warning } = await lookupName(`/studies/${config.study}`);
+            if (name)
+                study.name = name;
+            if (warning) {
+                study.warning = warning;
+                study.hint = ORPHAN_HINT("study");
             }
         }
         let ask = null;
@@ -195,13 +292,29 @@ program
                 id: config.ask,
                 alias: tagAlias(ALIAS_PREFIX.ask, config.ask),
             };
-            if (client) {
-                try {
-                    const a = await client.get(`/asks/${config.ask}`);
-                    if (a?.name)
-                        ask.name = a.name;
-                }
-                catch { /* keep id+alias only */ }
+            const { name, warning } = await lookupName(`/asks/${config.ask}`);
+            if (name)
+                ask.name = name;
+            if (warning) {
+                ask.warning = warning;
+                ask.hint = ORPHAN_HINT("ask");
+            }
+        }
+        // Pattern A: chat_endpoint was silently absent from `ish status` even
+        // when set (ISSUE-017). Surface it the same shape as workspace/study/ask.
+        let chatEndpoint = null;
+        if (config.chat_endpoint) {
+            chatEndpoint = {
+                id: config.chat_endpoint,
+                alias: tagAlias(ALIAS_PREFIX.chatEndpoint, config.chat_endpoint),
+            };
+            const { name, warning } = await lookupName(`/chatbot-endpoints/${config.chat_endpoint}`);
+            if (name)
+                chatEndpoint.name = name;
+            if (warning) {
+                chatEndpoint.warning = warning;
+                chatEndpoint.hint =
+                    "Active chat endpoint is no longer accessible. Use `ish chat endpoint use <id>` to switch or `ish chat endpoint use --clear` to drop.";
             }
         }
         // Best-effort skill detection: walks parent directories from cwd so an
@@ -219,12 +332,21 @@ program
             workspace,
             study,
             ask,
+            chat_endpoint: chatEndpoint,
             skill,
             api_url: apiUrl,
             home: ishDir(),
         };
-        if (tokenError && !token)
-            payload.hint = `Run \`ish login\`. (${tokenError})`;
+        if (tokenError && !token) {
+            // Pattern B (ISSUE-001): the inner message already tells the user
+            // to run `ish login` (auth.ts emits "Session expired. Run \"ish
+            // login\" to re-authenticate." / "No auth token found. Run \"ish
+            // login\"…"). Don't re-wrap with another "Run `ish login`. (…)"
+            // shell — that produced nested JSON soup with duplicated
+            // suggestions in the original bug. Pass the canonical message
+            // straight through.
+            payload.hint = tokenError;
+        }
         if (globals.json) {
             output(payload, true);
             return;
@@ -239,15 +361,31 @@ program
                 return `${h}h${m % 60}m`;
             return `${m}m`;
         };
+        const renderRef = (ref) => {
+            if (!ref)
+                return "—";
+            const base = `${ref.name ?? "(name unavailable)"} (${ref.alias})`;
+            return ref.warning ? `${base}  ⚠ ${ref.warning}` : base;
+        };
         console.log(`User:       ${user ? `${user.email ?? "(no email)"}  (token ${user.token_valid ? "valid" : "expired"}, expires in ${fmtSeconds(user.expires_in_seconds)})` : "(not logged in — run `ish login`)"}`);
-        console.log(`Workspace:  ${workspace ? `${workspace.name ?? "(name unavailable)"} (${workspace.alias})` : "—"}`);
-        console.log(`Study:      ${study ? `${study.name ?? "(name unavailable)"} (${study.alias})` : "—"}`);
-        console.log(`Ask:        ${ask ? `${ask.name ?? "(name unavailable)"} (${ask.alias})` : "—"}`);
+        console.log(`Workspace:  ${renderRef(workspace)}`);
+        console.log(`Study:      ${renderRef(study)}`);
+        console.log(`Ask:        ${renderRef(ask)}`);
+        console.log(`Chat ep:    ${renderRef(chatEndpoint)}`);
         console.log(`Skill:      ${skillHit ? skillHit.root : "not installed (run `ish init` to install the agent skill)"}`);
         console.log(`Home:       ${ishDir()}`);
         console.log(`API:        ${apiUrl}`);
         if (tokenError && !token)
             console.error(`\nHint: ${payload.hint}`);
+        // Surface orphan hints once at the bottom so they're visible in human
+        // output (the JSON envelope has them inline on each ref).
+        for (const [kind, ref] of [["workspace", workspace], ["study", study], ["ask", ask], ["chat_endpoint", chatEndpoint]]) {
+            if (ref?.warning) {
+                console.error(`\n⚠ ${kind}: ${ref.warning}`);
+                if (ref.hint)
+                    console.error(`   → ${ref.hint}`);
+            }
+        }
     });
 });
 const connectCmd = program
@@ -319,9 +457,31 @@ program
     .command("upgrade")
     .description("Update ish to the latest version")
     .option("--release <version>", "Install a specific release (e.g. 0.8.1)")
-    .addHelpText("after", "\nPin a specific release with --release <version>. Note: --version is the global CLI-version flag; use --release here.")
-    .action(async (options) => {
-    await upgrade(version, options.release);
+    .addHelpText("after", `
+Downloads the latest standalone binary from https://ishlabs.io/api/releases/
+and atomically replaces the running executable at \`$execPath\` (typically
+\`~/.ish/bin/ish\`). TLS-verified; no checksum. Already-up-to-date is a
+no-op.
+
+Pin a specific release with --release <version>. Note: --version is the
+global CLI-version flag; use --release here.
+
+Requires a standalone binary install (curl|sh or brew). On npm-installed
+CLIs (\`npm install -g @ishlabs/cli\`), upgrade refuses with an exit-code-2
+usage error and a pointer to \`npm install -g @ishlabs/cli@latest\` —
+overwriting \`node\` would break every other Node tool.
+
+Examples:
+  $ ish upgrade
+  $ ish upgrade --release 0.20.0`)
+    // Pattern C: wrap in runInline so errors flow through outputError +
+    // exitCodeFromError. Previously the raw Error was caught by Commander's
+    // default handler — leaked bun/node stack traces and exited 0 on
+    // validation failures like `--release "not-a-version"` (ISSUE-012).
+    .action(async (options, cmd) => {
+    await runInline(cmd, async (_globals) => {
+        await upgrade(version, options.release);
+    });
 });
 injectGlobalWorkspaceOption(program);
 // L3 / Pattern J: surface --get and --fields on every verb's --help.
@@ -344,11 +504,19 @@ function injectAgentTipsFooter(cmd) {
     }
 }
 injectAgentTipsFooter(program);
-// Single source of `client.surface` baggage: fires before EVERY
-// subcommand's action handler. `actionCommand.name()` is the leaf
+// Single source of `client.surface` + `workspace_id` baggage: fires before
+// EVERY subcommand's action handler. `actionCommand.name()` is the leaf
 // command name (e.g. "list" inside `ish workspace list`). For groups,
 // Commander joins names via `.parent` — flatten to the dotted path so
 // the backend sees `client.surface=workspace.list` not just `list`.
+//
+// Workspace resolution mirrors `resolveWorkspace` in command-helpers.ts:
+// (1) merged --workspace from action + program globals, (2) ISH_WORKSPACE,
+// (3) the persisted active workspace in ~/.ish/config.json. Aliases
+// (`w-abc`) are normalised to UUIDs via `resolveId`. Resolution is
+// best-effort here — if the value is a bogus alias the action's own
+// `resolveWorkspace` will throw the right error; we just skip stamping
+// baggage rather than crashing the preAction hook.
 program.hook("preAction", (_thisCommand, actionCommand) => {
     const parts = [];
     let cmd = actionCommand;
@@ -356,6 +524,21 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
         parts.unshift(cmd.name());
         cmd = cmd.parent;
     }
-    setSurfaceBaggage(parts.join(".") || actionCommand.name());
+    const surface = parts.join(".") || actionCommand.name();
+    let workspaceId;
+    try {
+        const merged = actionCommand.optsWithGlobals();
+        const raw = (typeof merged.workspace === "string" && merged.workspace) ||
+            process.env.ISH_WORKSPACE ||
+            loadConfig().workspace ||
+            undefined;
+        if (raw)
+            workspaceId = resolveId(raw);
+    }
+    catch {
+        // Bogus alias / unresolvable: leave workspace_id off baggage; the
+        // action's own resolver will surface a clean error.
+    }
+    setSurfaceBaggage({ surface, workspaceId });
 });
 program.parse();

package/dist/lib/alias-store.js

@@ -122,7 +122,12 @@ const HYDRATE_HINT = {
     s: "ish study list",
     i: "ish iteration list --study <study-id>",
     p: "ish person list",
-    ps: "ish source list",
+    // ISSUE-038 (partial): `ish source list` is not implemented in 0.19.0.
+    // Until it lands, advertise the upload-from-known-path or get-by-uuid
+    // workflows rather than the non-existent list command. The deterministic
+    // alias map at ~/.ish/aliases.json carries any sources the CLI has
+    // touched in this session.
+    ps: "ish source upload <file>  # or `cat ~/.ish/aliases.json | grep ^ps-` to recover prior aliases",
     pt: "ish participant get <participant-id>",
     c: "ish config list",
     a: "ish ask list",
@@ -158,11 +163,25 @@ export function resolveId(input) {
         const uuid = aliases[input];
         if (uuid)
             return uuid;
-        throw new Error(`Unknown alias "${input}". Run \`${hintForPrefix(input)}\` first to generate aliases.`);
+        // Pattern D + ISSUE-038 follow-through: tag as `not_found` for
+        // exit-code-4 consistency with the alias-format-unknown branch and
+        // the server's 404 path. Splits the hint onto its own line so the
+        // recovery suggestion reads cleanly even when the hint contains
+        // embedded comments (e.g. for `ps-` which has no list command yet).
+        const aliasErr = new Error(`Unknown alias "${input}". To generate aliases, run:\n  ${hintForPrefix(input)}`);
+        aliasErr.error_code = "not_found";
+        throw aliasErr;
     }
-    // 3. Anything else — fail with helpful guidance
-    throw new Error(`Invalid ID "${input}". Use a short alias (e.g. w-a3f, s-b2c) or a full UUID.\n` +
+    // 3. Anything else — fail with helpful guidance.
+    // Pattern D (ISSUE-029): tag as `not_found` so the alias-format-unknown
+    // path returns the same envelope shape and exit code (4) as the server's
+    // 404 path. Previously the local pre-check returned exit 2 / client_error
+    // while the server 404 returned exit 4 / not_found — asymmetric for the
+    // same user-visible outcome ("that thing doesn't exist").
+    const err = new Error(`Invalid ID "${input}". Use a short alias (e.g. w-a3f, s-b2c) or a full UUID.\n` +
         "Run a list command first to see available aliases:\n" +
         "  ish workspace list\n" +
         "  ish study list --workspace <id>");
+    err.error_code = "not_found";
+    throw err;
 }

package/dist/lib/auth.js

@@ -77,8 +77,20 @@ export async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
                 if (err instanceof TypeError || (err instanceof Error && err.message.includes('fetch'))) {
                     throw new Error('Could not refresh session (network error). Check your connection or run "ish login".');
                 }
-                const detail = err instanceof Error && err.message.startsWith("Token refresh failed") ? ` (${err.message})` : "";
-                throw new Error(`Session expired. Run "ish login" to re-authenticate.${detail}`);
+                // Pattern B (ISSUE-001 / ISSUE-008): default-mode error is the
+                // clean sentence; the raw Supabase HTTP body is only useful for
+                // debugging and surfacing it in the `hint` field produces nested
+                // JSON soup in `ish status`. Gate behind `--verbose`. Detection
+                // is via argv (process.argv) rather than threading globals through
+                // because resolveToken sits below the command-helpers layer.
+                const verbose = process.argv.includes("--verbose");
+                const detail = verbose && err instanceof Error && err.message.startsWith("Token refresh failed")
+                    ? ` (${err.message})`
+                    : "";
+                const sessionErr = new Error(`Session expired. Run "ish login" to re-authenticate.${detail}`);
+                // Pattern D continuity: tag for consistent exit code 3 mapping.
+                sessionErr.error_code = "auth_failed";
+                throw sessionErr;
             }
         }
         if (await verifyToken(accessToken, apiUrl)) {
@@ -93,6 +105,12 @@ export async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
         }
         throw new Error('Saved token is invalid. Run "ish login" to re-authenticate.');
     }
-    // 6. No token found
-    throw new Error('No auth token found. Run "ish login", set ISH_TOKEN, or pass --token <token> / --token-file <path>.');
+    // 6. No token found.
+    // Pattern D (ISSUE-010): tag with the same `error_code` that invalid-
+    // token errors carry (`auth_failed`) so agents branching on
+    // `error_code === "auth_failed"` to re-prompt for login handle both
+    // the no-token and invalid-token cases identically.
+    const err = new Error('No auth token found. Run "ish login", set ISH_TOKEN, or pass --token <token> / --token-file <path>.');
+    err.error_code = "auth_failed";
+    throw err;
 }

package/dist/lib/baggage.d.ts

@@ -2,10 +2,11 @@
  * Helpers for setting OTel Baggage entries and propagating them on
  * outbound fetches.
  *
- * The CLI carries three baggage entries on every backend call so the
- * backend can attribute spans + Sentry events to the right surface:
+ * The CLI carries four baggage entries on every backend call so the
+ * backend can attribute spans + Sentry events to the right surface and,
+ * when the command is workspace-scoped, the right workspace:
  *
- *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>
+ *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>[,workspace_id=<uuid>]
  *
  * In Node mode, `@opentelemetry/instrumentation-undici` will inject the
  * active baggage onto outbound `fetch` automatically once
@@ -23,13 +24,21 @@ export declare const BAGGAGE_KEY_CLIENT_NAME = "client.name";
 export declare const BAGGAGE_KEY_CLIENT_SURFACE = "client.surface";
 export declare const BAGGAGE_KEY_CLIENT_VERSION = "client.version";
 export declare const BAGGAGE_KEY_CONSENT_ANALYTICS = "consent.analytics";
+export declare const BAGGAGE_KEY_WORKSPACE_ID = "workspace_id";
 /** The fixed ``client.name`` we tag every CLI invocation with. The plan
  * pins this string — backend dashboards filter on it. */
 export declare const CLIENT_NAME = "ish-cli";
+export interface SurfaceBaggageInput {
+    surface: string;
+    /** Resolved workspace UUID (raw, not peppered). The backend HMACs this
+     * at the PostHog boundary; baggage / Sentry / logs see the raw UUID. */
+    workspaceId?: string | null;
+}
 /**
  * Stamp the active OTel baggage with ``client.name`` / ``client.surface``
- * / ``client.version`` and stash a process-local copy for the
- * manual-injection ``withBaggage`` helper.
+ * / ``client.version`` (always) and ``workspace_id`` (when the command
+ * carries one), then stash a process-local copy for the manual-injection
+ * ``withBaggage`` helper.
  *
  * Idempotent — subsequent calls overwrite the previous surface, which is
  * what we want when Commander invokes ``preAction`` once per resolved
@@ -49,7 +58,7 @@ export declare const CLIENT_NAME = "ish-cli";
  * Safe to call even with no OTel SDK registered — `@opentelemetry/api`
  * ships no-op fallbacks.
  */
-export declare function setSurfaceBaggage(commandName: string): void;
+export declare function setSurfaceBaggage(input: SurfaceBaggageInput): void;
 /**
  * Manually inject the active baggage into a ``HeadersInit`` value.
  *

package/dist/lib/baggage.js

@@ -2,10 +2,11 @@
  * Helpers for setting OTel Baggage entries and propagating them on
  * outbound fetches.
  *
- * The CLI carries three baggage entries on every backend call so the
- * backend can attribute spans + Sentry events to the right surface:
+ * The CLI carries four baggage entries on every backend call so the
+ * backend can attribute spans + Sentry events to the right surface and,
+ * when the command is workspace-scoped, the right workspace:
  *
- *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>
+ *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>[,workspace_id=<uuid>]
  *
  * In Node mode, `@opentelemetry/instrumentation-undici` will inject the
  * active baggage onto outbound `fetch` automatically once
@@ -25,13 +26,15 @@ export const BAGGAGE_KEY_CLIENT_NAME = "client.name";
 export const BAGGAGE_KEY_CLIENT_SURFACE = "client.surface";
 export const BAGGAGE_KEY_CLIENT_VERSION = "client.version";
 export const BAGGAGE_KEY_CONSENT_ANALYTICS = "consent.analytics";
+export const BAGGAGE_KEY_WORKSPACE_ID = "workspace_id";
 /** The fixed ``client.name`` we tag every CLI invocation with. The plan
  * pins this string — backend dashboards filter on it. */
 export const CLIENT_NAME = "ish-cli";
 /**
  * Stamp the active OTel baggage with ``client.name`` / ``client.surface``
- * / ``client.version`` and stash a process-local copy for the
- * manual-injection ``withBaggage`` helper.
+ * / ``client.version`` (always) and ``workspace_id`` (when the command
+ * carries one), then stash a process-local copy for the manual-injection
+ * ``withBaggage`` helper.
  *
  * Idempotent — subsequent calls overwrite the previous surface, which is
  * what we want when Commander invokes ``preAction`` once per resolved
@@ -51,17 +54,20 @@ export const CLIENT_NAME = "ish-cli";
  * Safe to call even with no OTel SDK registered — `@opentelemetry/api`
  * ships no-op fallbacks.
  */
-export function setSurfaceBaggage(commandName) {
+export function setSurfaceBaggage(input) {
     const existing = propagation.getActiveBaggage() ?? propagation.createBaggage();
-    const next = existing
+    let next = existing
         .setEntry(BAGGAGE_KEY_CLIENT_NAME, { value: CLIENT_NAME })
-        .setEntry(BAGGAGE_KEY_CLIENT_SURFACE, { value: commandName })
+        .setEntry(BAGGAGE_KEY_CLIENT_SURFACE, { value: input.surface })
         .setEntry(BAGGAGE_KEY_CLIENT_VERSION, { value: pkg.version })
         // CLI runs on a developer's machine with no client-side consent UI.
         // Emit "unknown" so the backend resolver falls through to the
         // authenticated user's persisted consent rather than default-denying
         // via baggage absence.
         .setEntry(BAGGAGE_KEY_CONSENT_ANALYTICS, { value: "unknown" });
+    if (input.workspaceId) {
+        next = next.setEntry(BAGGAGE_KEY_WORKSPACE_ID, { value: input.workspaceId });
+    }
     _activeBaggage = next;
 }
 /** Process-local copy of the active baggage for the manual-injection path.

package/dist/lib/command-helpers.d.ts

@@ -23,6 +23,7 @@ export interface PersonResolveOpts {
     /** Profile IDs to exclude from the fetched pool (e.g. participants already on an ask). */
     excludeProfileIds?: Set<string>;
 }
+export declare function normalizeVisibility(raw: string | undefined): string | undefined;
 /** True when any person-selection flag is set on the command. */
 export declare function hasPersonFlags(flags: PersonFilterOpts): boolean;
 /**