@stigmer/cli 3.1.6 → 3.1.8

package/src/resources/mcp/placeholder-resolver.test.ts

@@ -0,0 +1,71 @@
+// Unit tests for the strict ${VAR} placeholder resolver.
+
+import { describe, expect, it } from "vitest";
+import { PlaceholderResolutionError, resolveHeaders, resolvePlaceholders } from "./placeholder-resolver.js";
+
+describe("resolvePlaceholders", () => {
+  it("returns a string with no placeholders unchanged", () => {
+    expect(resolvePlaceholders("/tmp/data.sqlite", {})).toBe("/tmp/data.sqlite");
+  });
+
+  it("resolves a single placeholder from the env map", () => {
+    expect(resolvePlaceholders("${DIR}", { DIR: "/home/me" })).toBe("/home/me");
+  });
+
+  it("resolves a placeholder embedded in surrounding text", () => {
+    expect(resolvePlaceholders("${DB_PATH}/data.sqlite", { DB_PATH: "/var/lib" })).toBe("/var/lib/data.sqlite");
+  });
+
+  it("resolves multiple and adjacent placeholders", () => {
+    expect(resolvePlaceholders("${A}${B}-${A}", { A: "x", B: "y" })).toBe("xy-x");
+  });
+
+  it("resolves to an empty string when the value is empty", () => {
+    // An empty-but-present value is a resolved value, not a missing variable.
+    expect(resolvePlaceholders("[${X}]", { X: "" })).toBe("[]");
+  });
+
+  it("ignores $VAR without braces (only ${VAR} is a placeholder)", () => {
+    expect(resolvePlaceholders("$HOME/bin", { HOME: "/root" })).toBe("$HOME/bin");
+  });
+
+  it("throws PlaceholderResolutionError for an unresolved variable, carrying name + context", () => {
+    let caught: unknown;
+    try {
+      resolvePlaceholders("${MISSING}", { OTHER: "1" }, "stdio arg[2]");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PlaceholderResolutionError);
+    const e = caught as PlaceholderResolutionError;
+    expect(e.variableName).toBe("MISSING");
+    expect(e.context).toBe("stdio arg[2]");
+    expect(e.message).toContain("${MISSING}");
+    expect(e.message).toContain("stdio arg[2]");
+  });
+
+  it("throws on the first unresolved variable even when others resolve", () => {
+    expect(() => resolvePlaceholders("${A}-${B}", { A: "ok" })).toThrow(PlaceholderResolutionError);
+  });
+});
+
+describe("resolveHeaders", () => {
+  it("resolves placeholders in every header value", () => {
+    const resolved = resolveHeaders(
+      { Authorization: "Bearer ${TOKEN}", "X-Static": "v1" },
+      { TOKEN: "abc123" },
+    );
+    expect(resolved).toEqual({ Authorization: "Bearer abc123", "X-Static": "v1" });
+  });
+
+  it("throws with the offending header name in the context", () => {
+    let caught: unknown;
+    try {
+      resolveHeaders({ Authorization: "Bearer ${API_KEY}" }, {});
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PlaceholderResolutionError);
+    expect((caught as PlaceholderResolutionError).message).toContain('header "Authorization"');
+  });
+});

package/src/resources/mcp/placeholder-resolver.ts

@@ -0,0 +1,63 @@
+// Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+//
+// The MCP server spec (StdioServerConfig.args, HttpServerConfig.headers) allows
+// values to reference declared env vars with ${VAR_NAME}. The proto contract is
+// explicit that resolution is strict: a missing variable must produce a clear
+// error rather than passing a literal "${VAR}" to the subprocess/server.
+//
+// This mirrors the runner's shared resolver (backend/services/runner/src/shared/
+// placeholder-resolver.ts) so `connect --dry-run` (which discovers locally)
+// behaves identically to real connect (which resolves on the runner). Kept
+// intentionally dependency-free and semantically identical so the two can be
+// collapsed into one shared package later without any behavior change.
+
+const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export class PlaceholderResolutionError extends Error {
+  constructor(
+    public readonly variableName: string,
+    public readonly context?: string,
+  ) {
+    const where = context ? ` in ${context}` : "";
+    super(
+      `Unresolved placeholder \${${variableName}}${where}: ` +
+        `variable is not present in the execution environment`,
+    );
+    this.name = "PlaceholderResolutionError";
+  }
+}
+
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(
+  template: string,
+  envVars: Record<string, string>,
+  context?: string,
+): string {
+  return template.replace(PLACEHOLDER_RE, (_match, varName: string) => {
+    if (varName in envVars) {
+      return envVars[varName];
+    }
+    throw new PlaceholderResolutionError(varName, context);
+  });
+}
+
+/**
+ * Resolve placeholders in every value of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export function resolveHeaders(
+  headers: Record<string, string>,
+  envVars: Record<string, string>,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    resolved[key] = resolvePlaceholders(value, envVars, `header "${key}"`);
+  }
+  return resolved;
+}

package/src/resources/mcp/runtime-env.test.ts

@@ -4,12 +4,18 @@ import { create } from "@bufbuild/protobuf";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { UsageError } from "../../errors/index.js";
-import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides } from "./runtime-env.js";
+import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides, resolveDeclaredEnvValues } from "./runtime-env.js";
 
 function serverWithEnv(env: Record<string, { isSecret: boolean }>) {
   return create(McpServerSchema, { metadata: { id: "mcp_1" }, spec: { env } });
 }
 
+// resolveDeclaredEnvValues takes the raw declarations map; the tests only rely on
+// keys being present, so a minimal declaration object is sufficient.
+function decls(...keys: string[]) {
+  return Object.fromEntries(keys.map((k) => [k, { isSecret: false }]));
+}
+
 describe("parseEnvOverrides", () => {
   it("parses KEY=VALUE pairs, preserving '=' in the value", () => {
     expect(parseEnvOverrides(["A=1", "B=x=y"])).toEqual({ A: "1", B: "x=y" });
@@ -66,3 +72,31 @@ describe("mergeProcessEnv", () => {
     expect(merged.NEW).toBe("1");
   });
 });
+
+describe("resolveDeclaredEnvValues", () => {
+  const original = process.env;
+  beforeEach(() => {
+    process.env = { ...original, ALLOWED_DIR: "/from-os", EMPTY_VAR: "" };
+  });
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("pulls declared keys from the OS environment", () => {
+    expect(resolveDeclaredEnvValues(decls("ALLOWED_DIR"))).toEqual({ ALLOWED_DIR: "/from-os" });
+  });
+
+  it("skips declared keys that are unset or empty in the environment", () => {
+    expect(resolveDeclaredEnvValues(decls("EMPTY_VAR", "MISSING"))).toEqual({});
+  });
+
+  it("lets --env overrides win over the OS environment", () => {
+    expect(resolveDeclaredEnvValues(decls("ALLOWED_DIR"), ["ALLOWED_DIR=/override"])).toEqual({
+      ALLOWED_DIR: "/override",
+    });
+  });
+
+  it("includes an --env override even when the key is undeclared (matches buildRuntimeEnv)", () => {
+    expect(resolveDeclaredEnvValues(decls(), ["EXTRA=1"])).toEqual({ EXTRA: "1" });
+  });
+});

package/src/resources/mcp/runtime-env.ts

@@ -36,6 +36,39 @@ export function parseEnvOverrides(overrides: readonly string[]): Record<string,
   return result;
 }
 
+/**
+ * Resolve the values behind a server's declared env vars: declared keys pulled
+ * from the OS environment (non-empty only), with `--env` overrides layered on
+ * top (override wins; an undeclared override is still included).
+ *
+ * This is the single source of truth for "which env value is in play". It backs
+ * both the runtime_env sent to the backend (buildRuntimeEnv) and the ${VAR}
+ * placeholder resolution done locally for `--dry-run` (discover.ts), so the two
+ * can never drift: dry-run resolves against the exact same map the backend hands
+ * the runner (minus platform-injected infra vars, which a local machine cannot
+ * know).
+ *
+ * `declarations` is the server's `spec.env` map; only its keys (the declared
+ * variable names) are read, so any map keyed by those names is accepted.
+ */
+export function resolveDeclaredEnvValues(
+  declarations: Record<string, unknown>,
+  envOverrides: readonly string[] = [],
+): Record<string, string> {
+  const values: Record<string, string> = {};
+
+  for (const key of Object.keys(declarations)) {
+    const value = process.env[key];
+    if (value !== undefined && value !== "") values[key] = value;
+  }
+
+  for (const [key, value] of Object.entries(parseEnvOverrides(envOverrides))) {
+    values[key] = value;
+  }
+
+  return values;
+}
+
 /**
  * Build the runtime_env map for the Connect RPC from the OS environment and the
  * supplied --env overrides. Only keys with a non-empty value are emitted.
@@ -45,17 +78,10 @@ export function buildRuntimeEnv(
   envOverrides: readonly string[] = [],
 ): Record<string, ExecutionValue> {
   const declarations = server.spec?.env ?? {};
-  const overrides = parseEnvOverrides(envOverrides);
+  const values = resolveDeclaredEnvValues(declarations, envOverrides);
   const runtime: Record<string, ExecutionValue> = {};
 
-  for (const [key, decl] of Object.entries(declarations)) {
-    const value = process.env[key];
-    if (value !== undefined && value !== "") {
-      runtime[key] = create(ExecutionValueSchema, { value, isSecret: decl.isSecret });
-    }
-  }
-
-  for (const [key, value] of Object.entries(overrides)) {
+  for (const [key, value] of Object.entries(values)) {
     runtime[key] = create(ExecutionValueSchema, { value, isSecret: declarations[key]?.isSecret ?? false });
   }
 

package/src/resources/read-verbs.integration.test.ts

@@ -38,7 +38,7 @@ const knownAgent = create(AgentSchema, {
 const knownOrg = create(OrganizationSchema, {
   apiVersion: "tenancy.stigmer.ai/v1",
   kind: "Organization",
-  metadata: { name: "Acme", slug: "acme", org: "acme", id: "org_1" },
+  metadata: { name: "Acme", slug: "acme", org: "acme", id: "acme" },
 });
 
 const knownApiKey = create(ApiKeySchema, {

package/src/resources/share.test.ts

@@ -0,0 +1,389 @@
+// Unit tests for the share-agent resource layer. The critical contract is
+// merge-preservation: `updateSharing` replaces `spec.sharing` wholesale, so a
+// CLI toggle must never wipe console-configured origins or visitor messages.
+
+import { clone, create } from "@bufbuild/protobuf";
+import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/status_pb";
+import type { UpdateAgentSharingInput } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import { AgentSharingAudience } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { buildEmbedSnippet, type Stigmer } from "@stigmer/sdk";
+import { describe, expect, it } from "vitest";
+import { classify, ExitCode, UsageError } from "../errors/index.js";
+import { shareAgent } from "./share.js";
+
+const CLOUD = { appOrigin: "https://app.stigmer.ai", isLocal: false };
+const LOCAL = { appOrigin: "http://localhost:8234", isLocal: true };
+
+function makeAgent(
+  sharing?: {
+    enabled?: boolean;
+    audience?: AgentSharingAudience;
+    allowedOrigins?: string[];
+    messages?: { rateLimited?: string; unavailable?: string; conversationEnded?: string };
+  },
+  shareLinkToken?: string,
+): Agent {
+  return create(AgentSchema, {
+    metadata: { id: "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", org: "acme", slug: "support-agent", name: "Support Agent" },
+    spec: sharing !== undefined ? { sharing } : {},
+    ...(shareLinkToken !== undefined ? { status: { shareLinkToken } } : {}),
+  });
+}
+
+// A minimal fake of the SDK surface shareAgent touches: agent.getByReference /
+// agent.get + call-recording agent.updateSharing / agent.rotateShareLink
+// (skill.test.ts convention). Rotation answers with the agent re-stamped
+// with `rotatedToken`, mirroring the server's fresh-entropy response.
+function fakeClient(
+  agent: Agent,
+  opts: { failWith?: Error; rotatedToken?: string } = {},
+) {
+  const calls: UpdateAgentSharingInput[] = [];
+  let rotations = 0;
+  const client = {
+    agent: {
+      async get() {
+        return agent;
+      },
+      async getByReference() {
+        return agent;
+      },
+      async updateSharing(input: UpdateAgentSharingInput) {
+        if (opts.failWith) throw opts.failWith;
+        calls.push(input);
+        return agent;
+      },
+      async rotateShareLink() {
+        rotations += 1;
+        const rotated = clone(AgentSchema, agent);
+        rotated.status = create(AgentStatusSchema, {
+          shareLinkToken: opts.rotatedToken ?? "fresh-token",
+        });
+        return rotated;
+      },
+    },
+  } as unknown as Stigmer;
+  return { client, calls, rotationCount: () => rotations };
+}
+
+describe("shareAgent merge-preservation (fails closed)", () => {
+  it("enabling preserves console-configured origins and messages verbatim", async () => {
+    const agent = makeAgent({
+      enabled: false,
+      allowedOrigins: ["https://example.com", "https://docs.example.com"],
+      messages: { rateLimited: "Slow down!", unavailable: "Back soon.", conversationEnded: "Bye!" },
+    });
+    const { client, calls } = fakeClient(agent);
+
+    await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].resourceId).toBe("agt_01ARZ3NDEKTSV4RRFFQ69G5FAV");
+    expect(calls[0].sharing?.enabled).toBe(true);
+    expect(calls[0].sharing?.allowedOrigins).toEqual(["https://example.com", "https://docs.example.com"]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("Slow down!");
+    expect(calls[0].sharing?.messages?.unavailable).toBe("Back soon.");
+    expect(calls[0].sharing?.messages?.conversationEnded).toBe("Bye!");
+  });
+
+  it("disabling preserves origins and messages, flipping only enabled", async () => {
+    const agent = makeAgent({
+      enabled: true,
+      allowedOrigins: ["https://example.com"],
+      messages: { rateLimited: "Slow down!" },
+    });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: false, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].sharing?.enabled).toBe(false);
+    expect(calls[0].sharing?.allowedOrigins).toEqual(["https://example.com"]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("Slow down!");
+    expect(result.message).toContain("Sharing disabled");
+    // No link/snippet on disable — the URL no longer works.
+    expect(result.sections).toHaveLength(0);
+  });
+
+  it("enables cleanly for an agent that has never been shared (no spec.sharing)", async () => {
+    const { client, calls } = fakeClient(makeAgent(undefined));
+
+    await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].sharing?.enabled).toBe(true);
+    expect(calls[0].sharing?.allowedOrigins).toEqual([]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("");
+  });
+
+  it("a plain toggle preserves an org-members-only audience (never reverts to public)", async () => {
+    const agent = makeAgent({
+      enabled: false,
+      audience: AgentSharingAudience.org,
+      allowedOrigins: [],
+    });
+    const { client, calls } = fakeClient(agent);
+
+    await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    // A re-enable without --audience must keep the org restriction: writing
+    // public here would silently expose an internal agent to the internet.
+    expect(calls[0].sharing?.audience).toBe(AgentSharingAudience.org);
+  });
+});
+
+describe("shareAgent audience", () => {
+  it("--audience org sets the audience and writes the full block", async () => {
+    const agent = makeAgent({
+      enabled: true,
+      allowedOrigins: ["https://example.com"],
+      messages: { rateLimited: "Slow down!" },
+    });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "org",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].sharing?.audience).toBe(AgentSharingAudience.org);
+    expect(calls[0].sharing?.enabled).toBe(true);
+    expect(calls[0].sharing?.allowedOrigins).toEqual(["https://example.com"]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("Slow down!");
+
+    // Org shares print the member link and NO embed snippet (embeds serve
+    // anonymous guests, which org shares refuse).
+    const link = result.sections.find((s) => s.title === "Member chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+    expect(result.sections.find((s) => s.title === "Embed on your site")).toBeUndefined();
+    expect(result.hints.some((h) => h.includes("signed-in members"))).toBe(true);
+    expect(result.hints.some((h) => h.includes("search engines"))).toBe(false);
+  });
+
+  it("--audience public converts an org share back to an explicit public one", async () => {
+    const agent = makeAgent({ enabled: true, audience: AgentSharingAudience.org });
+    const { client, calls } = fakeClient(agent);
+
+    await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "public",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(1);
+    // Written as the explicit enum value, never left unspecified.
+    expect(calls[0].sharing?.audience).toBe(AgentSharingAudience.public);
+  });
+
+  it("an audience change alone triggers a write even when enabled matches", async () => {
+    const agent = makeAgent({ enabled: true });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "org",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(result.message).toContain("Sharing enabled");
+  });
+
+  it("matching enabled AND audience stays idempotent (no write)", async () => {
+    const agent = makeAgent({ enabled: true, audience: AgentSharingAudience.org });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "org",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(0);
+    expect(result.message).toContain("already on");
+  });
+});
+
+describe("shareAgent idempotency", () => {
+  it("skips the write when sharing is already enabled, still reporting the link", async () => {
+    const { client, calls } = fakeClient(makeAgent({ enabled: true }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(0);
+    expect(result.message).toContain("already on");
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+  });
+
+  it("skips the write when sharing is already disabled", async () => {
+    const { client, calls } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: false, ...CLOUD });
+
+    expect(calls).toHaveLength(0);
+    expect(result.message).toContain("already off");
+  });
+});
+
+describe("shareAgent output", () => {
+  it("builds the link and snippet from the RESOLVED agent's org/slug (ID refs included)", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "", { enabled: true, ...CLOUD });
+
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+  });
+
+  it("emits the exact embed snippet the web share dialog emits", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    const embed = result.sections.find((s) => s.title === "Embed on your site");
+    expect(embed?.items.join("\n")).toBe(buildEmbedSnippet("https://app.stigmer.ai", "acme", "support-agent"));
+  });
+
+  it("includes the who-pays and indexability hints", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(result.hints.some((h) => h.includes("acme's credits"))).toBe(true);
+    expect(result.hints.some((h) => h.includes("search engines"))).toBe(true);
+  });
+
+  it("warns that a local link won't serve visitors (guest chat is Cloud-only)", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...LOCAL });
+
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual(["http://localhost:8234/chat/acme/support-agent"]);
+    expect(result.hints.some((h) => h.includes("Stigmer Cloud"))).toBe(true);
+  });
+
+  it("omits the local warning on a cloud backend", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(result.hints.some((h) => h.includes("Stigmer Cloud"))).toBe(false);
+  });
+});
+
+describe("shareAgent --reset-link (rotatable share token)", () => {
+  it("rotates and prints the fresh tokened link and snippet", async () => {
+    const { client, calls, rotationCount } = fakeClient(
+      makeAgent({ enabled: true }),
+      { rotatedToken: "fresh-token" },
+    );
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      resetLink: true,
+      ...CLOUD,
+    });
+
+    // Already enabled: no sharing write, exactly one rotation.
+    expect(calls).toHaveLength(0);
+    expect(rotationCount()).toBe(1);
+    expect(result.message).toContain("Share link reset");
+
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual([
+      "https://app.stigmer.ai/chat/acme/support-agent?k=fresh-token",
+    ]);
+    const embed = result.sections.find((s) => s.title === "Embed on your site");
+    expect(embed?.items.join("\n")).toBe(
+      buildEmbedSnippet("https://app.stigmer.ai", "acme", "support-agent", "fresh-token"),
+    );
+    expect(result.hints.some((h) => h.includes("Re-share the new link"))).toBe(true);
+  });
+
+  it("a plain toggle on a locked link keeps printing the existing tokened URL", async () => {
+    const { client, rotationCount } = fakeClient(
+      makeAgent({ enabled: true }, "existing-token"),
+    );
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      ...CLOUD,
+    });
+
+    // No rotation was requested: the current token must ride the link
+    // verbatim, or the printed URL would be dead.
+    expect(rotationCount()).toBe(0);
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual([
+      "https://app.stigmer.ai/chat/acme/support-agent?k=existing-token",
+    ]);
+  });
+
+  it("refuses --reset-link for an org-members-only share with actionable guidance", async () => {
+    const { client, rotationCount } = fakeClient(
+      makeAgent({ enabled: true, audience: AgentSharingAudience.org }),
+    );
+
+    const err = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      resetLink: true,
+      ...CLOUD,
+    }).catch((e: unknown) => e);
+
+    // Org access is gated by live membership — the token is never consulted,
+    // so rotating it would be a silent no-op the user did not get.
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as Error).message).toContain("public links");
+    expect(rotationCount()).toBe(0);
+  });
+
+  it("the member link never carries a token, even when one exists in status", async () => {
+    const { client } = fakeClient(
+      makeAgent({ enabled: true, audience: AgentSharingAudience.org }, "existing-token"),
+    );
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      ...CLOUD,
+    });
+
+    const link = result.sections.find((s) => s.title === "Member chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+  });
+});
+
+describe("shareAgent errors", () => {
+  it("fails fast with org guidance for a bare slug and no org", async () => {
+    const { client, calls } = fakeClient(makeAgent());
+
+    const err = await shareAgent(client, "support-agent", "", { enabled: true, ...CLOUD }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as Error).message).toContain("organization not set");
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("does not apply the org guard to an ID reference", async () => {
+    const { client, calls } = fakeClient(makeAgent({ enabled: false }));
+
+    await shareAgent(client, "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+  });
+
+  it("propagates server rejections (permission denied) unchanged", async () => {
+    const denied = new Error("permission denied: can_edit required");
+    const { client } = fakeClient(makeAgent({ enabled: false }), { failWith: denied });
+
+    await expect(shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD })).rejects.toThrow(
+      /permission denied/,
+    );
+  });
+});