@stigmer/cli 3.12.0 → 3.12.2

package/src/commands/push.ts

@@ -19,6 +19,7 @@ interface PushFlags {
   gitUrl?: string;
   gitRef?: string;
   subdir?: string;
+  archive?: string;
   ignore?: string[];
   include?: string[];
   gitignore?: boolean; // false when --no-gitignore is passed (commander negation)
@@ -37,6 +38,7 @@ export function registerPush(program: Command): void {
     .option("--git-url <url>", "push from a remote git repository URL")
     .option("--git-ref <ref>", "git reference (tag, branch, or commit SHA) for remote push")
     .option("--subdir <dir>", "subdirectory within the git repository containing the artifact")
+    .option("--archive <file>", "push a pre-packaged ZIP archive as-is (version hash = the file's SHA-256)")
     .option("--ignore <pattern>", "additional pattern to ignore (repeatable)", collect, [])
     .option("--include <pattern>", "pattern to force-include (repeatable)", collect, [])
     .option("--no-gitignore", "don't respect .gitignore patterns")
@@ -72,6 +74,11 @@ async function runPush(type: string, path: string | undefined, options: PushFlag
   const tag = options.tag ?? "latest";
   const message = options.message ?? "";
 
+  if (options.archive !== undefined && options.archive !== "") {
+    await pushArchive(client.stigmer, skill, { org, tag, message, path, options });
+    return;
+  }
+
   if (options.gitUrl !== undefined && options.gitUrl !== "") {
     await pushRemote(client.stigmer, skill, { org, tag, message, ignoreOptions, decisionSink, options });
     return;
@@ -95,6 +102,73 @@ async function runPush(type: string, path: string | undefined, options: PushFlag
   process.stdout.write(renderResult(result, skill));
 }
 
+interface ArchiveContext {
+  org: string;
+  tag: string;
+  message: string;
+  path: string | undefined;
+  options: PushFlags;
+}
+
+/**
+ * Push a pre-packaged skill archive (`--archive`). The bytes are uploaded
+ * as-is, so source-mode and filtering flags have nothing to act on — passing
+ * one alongside --archive is a contradiction we fail loudly rather than
+ * silently ignore.
+ */
+async function pushArchive(
+  client: import("@stigmer/sdk").Stigmer,
+  skill: typeof import("../resources/skill.js"),
+  ctx: ArchiveContext,
+): Promise<void> {
+  const conflicts: string[] = [];
+  if (ctx.path !== undefined && ctx.path !== "") conflicts.push("[path]");
+  if (ctx.options.gitUrl !== undefined && ctx.options.gitUrl !== "") conflicts.push("--git-url");
+  if (ctx.options.gitRef !== undefined && ctx.options.gitRef !== "") conflicts.push("--git-ref");
+  if (ctx.options.subdir !== undefined && ctx.options.subdir !== "") conflicts.push("--subdir");
+  if ((ctx.options.ignore ?? []).length > 0) conflicts.push("--ignore");
+  if ((ctx.options.include ?? []).length > 0) conflicts.push("--include");
+  if (ctx.options.gitignore === false) conflicts.push("--no-gitignore");
+  if (conflicts.length > 0) {
+    throw new UsageError(
+      `--archive pushes a pre-packaged ZIP as-is and cannot be combined with: ${conflicts.join(", ")}\n\n` +
+        "Packaging already happened when the archive was built.",
+    );
+  }
+
+  const archivePath = ctx.options.archive ?? "";
+  if (ctx.options.dryRun === true) {
+    process.stdout.write(renderArchiveDryRun(archivePath, skill.readSkillArchive(archivePath), skill));
+    return;
+  }
+
+  const result = await skill.pushSkillFromArchive(client, archivePath, ctx.org, ctx.tag, ctx.message);
+  process.stdout.write(renderResult(result, skill));
+}
+
+function renderArchiveDryRun(
+  archivePath: string,
+  archive: import("../resources/skill.js").SkillArchive,
+  skill: typeof import("../resources/skill.js"),
+): string {
+  const lines = [
+    "",
+    `Dry run - validating skill archive: ${archivePath}`,
+    "",
+    `Skill name:   ${archive.meta.name}`,
+    `Files:        ${archive.fileCount}`,
+    `Content size: ${skill.formatBytes(archive.totalSize)}`,
+    `Upload size:  ${skill.formatBytes(archive.bytes.length)}`,
+    "",
+    "The archive bytes are uploaded as-is: the registered version hash is the",
+    "SHA-256 of this file, so it matches any checksum you published for it.",
+    "",
+    "Run without --dry-run to push the skill artifact.",
+    "",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
 interface RemoteContext {
   org: string;
   tag: string;

package/src/commands/setup.ts

@@ -1,11 +1,17 @@
 // `stigmer setup` — configure the LLM provider used for agent execution.
 //
 // Two paths share one decision core (local/setup/wizard.ts): a non-interactive
-// flag path (`--provider`, `--api-key`, `--model`) for scripts and CI, and an
+// flag path (`--provider`, `--api-key`) for scripts and CI, and an
 // interactive API-key prompt when no provider flag is given. Both write to
 // backend.local.llm, preserving every other config field. The valid provider
 // set is owned by wizard.ts's PROVIDER_CHOICES (Anthropic-only + skip — the
 // only story the native runner serves).
+//
+// Setup deliberately has NO model concept: the platform model registry owns
+// the execution default, and per-run overrides belong to `stigmer run
+// --model`. A setup-level pin used to exist but never reached execution
+// (oss#314) — config that looks authoritative but is dead invites exactly the
+// bug class Session 29 fixed, so it is structurally gone rather than wired up.
 
 import type { Command } from "commander";
 import { homedir } from "node:os";
@@ -14,7 +20,6 @@ import { addResultFlags, resultFormat } from "./shared.js";
 
 interface SetupFlags extends OutputFlags {
   provider?: string;
-  model?: string;
   apiKey?: string;
 }
 
@@ -23,7 +28,6 @@ export function registerSetup(program: Command): void {
     .command("setup")
     .description("configure the LLM provider for agent execution")
     .option("--provider <name>", "provider: anthropic, or skip to clear (non-interactive)")
-    .option("--model <name>", "pin a specific model (defaults to the platform-selected model)")
     .option("--api-key <key>", "Anthropic API key")
     .action((options: SetupFlags) => runSetup(options));
   addResultFlags(setup);
@@ -47,7 +51,6 @@ async function runSetup(options: SetupFlags): Promise<void> {
       ]);
     }
     updated = applyChoice(config, provider as (typeof PROVIDER_CHOICES)[number], {
-      model: options.model,
       apiKey: options.apiKey,
     });
   } else {

package/src/local/daemon/launch.ts

@@ -95,7 +95,7 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
 
   await applySeedpackBestEffort(home);
 
-  saveStartupConfig(data, buildStartupConfig(data, logs, temporal.address, config, daemonPid, options));
+  saveStartupConfig(data, buildStartupConfig(data, logs, temporal.address, daemonPid, options));
 }
 
 /**
@@ -246,18 +246,13 @@ function buildStartupConfig(
   data: string,
   logs: string,
   temporalAddr: string,
-  config: Config,
   daemonPid: number,
   options: UpOptions,
 ): StartupConfig {
-  const local = config.backend.local as { llm?: { provider?: string; model?: string; base_url?: string } } | undefined;
   return {
     data_dir: data,
     log_dir: logs,
     temporal_addr: temporalAddr,
-    llm_provider: local?.llm?.provider ?? "",
-    llm_model: local?.llm?.model ?? "",
-    llm_base_url: local?.llm?.base_url ?? "",
     execution_mode: "local",
     sandbox_image: "",
     sandbox_auto_pull: false,

package/src/local/llm-config.test.ts

@@ -4,7 +4,6 @@ import {
   detectProviderFromEnv,
   readLlm,
   resolveApiKey,
-  resolveModel,
   resolveProvider,
   setLlm,
 } from "./llm-config.js";
@@ -32,17 +31,6 @@ describe("resolveProvider", () => {
   });
 });
 
-describe("resolveModel", () => {
-  it("returns the explicit override, else empty — the registry owns the default", () => {
-    // No hardcoded model version anywhere in the CLI: unset means "platform
-    // default", resolved by the runner from the model registry.
-    expect(resolveModel(config({ llm: { provider: "anthropic" } }), {})).toBe("");
-    expect(resolveModel(config(), {})).toBe("");
-    expect(resolveModel(config({ llm: { provider: "anthropic", model: "claude-x" } }), {})).toBe("claude-x");
-    expect(resolveModel(config({ llm: { provider: "anthropic" } }), { STIGMER_LLM_MODEL: "envm" })).toBe("envm");
-  });
-});
-
 describe("resolveApiKey", () => {
   it("uses ANTHROPIC_API_KEY, then config", () => {
     const cfg = config({ llm: { provider: "anthropic", api_key: "cfgkey" } });
@@ -58,12 +46,21 @@ describe("resolveApiKey", () => {
 describe("setLlm", () => {
   it("preserves sibling local keys and can clear the section", () => {
     const cfg = config({ temporal: { managed: true }, llm: { provider: "anthropic" } });
-    const updated = setLlm(cfg, { provider: "anthropic", model: "m" });
-    expect(readLlm(updated)).toEqual({ provider: "anthropic", model: "m" });
+    const updated = setLlm(cfg, { provider: "anthropic", api_key: "k" });
+    expect(readLlm(updated)).toEqual({ provider: "anthropic", api_key: "k" });
     expect((updated.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
 
     const cleared = setLlm(cfg, undefined);
     expect(readLlm(cleared)).toBeUndefined();
     expect((cleared.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
   });
+
+  it("replaces the section wholesale — a stale model key from a pre-oss#314 config does not survive a rewrite", () => {
+    // The graceful-migration contract: old configs may carry llm.model (the
+    // removed dead pin). Reads ignore it (LlmSettings no longer models it);
+    // the next setup write clears it because setLlm never merges.
+    const cfg = config({ llm: { provider: "anthropic", model: "stale-pin", api_key: "k" } });
+    const rewritten = setLlm(cfg, { provider: "anthropic", api_key: "k" });
+    expect(readLlm(rewritten)).toEqual({ provider: "anthropic", api_key: "k" });
+  });
 });

package/src/local/llm-config.ts

@@ -4,7 +4,7 @@
 // The config module (config/config.ts) carries `backend.local` through verbatim
 // so the CLI never drops fields it does not model. This module adds a *typed
 // lens* for the one sub-tree setup owns — `local.llm` — and resolves the
-// effective provider/model with env-override precedence (env > config file >
+// effective provider/key with env-override precedence (env > config file >
 // API-key autodetect). Writes merge into a shallow copy of `local`, preserving
 // every sibling key (temporal, execution, …).
 //
@@ -12,10 +12,13 @@
 // Anthropic clients, and the platform model registry's native-harness entries
 // are all Anthropic models. Two invariants follow:
 //
-//   1. The model registry — not this config — owns the default execution model.
-//      The runner resolves it from the registry at execution time, so this
-//      module never hardcodes a model version (hardcoded versions here drifted
-//      from the registry repeatedly). An unset model means "platform default".
+//   1. The model registry — not this config — owns the execution model, so
+//      there is deliberately NO model field here. A config-level model pin
+//      existed once but never reached execution (oss#314): the launcher
+//      forwards only the API key, making such a pin config-that-lies. Per-run
+//      overrides belong to `stigmer run --model`. Stale `model` keys in
+//      existing config files are silently ignored (verbatim carry-through)
+//      and cleared by the next `setup` write.
 //   2. `provider` exists to route the right API key to the runner, not to
 //      select an execution backend; "anthropic" is the only provider the local
 //      stack can serve.
@@ -25,7 +28,6 @@ import type { Config } from "../config/config.js";
 /** LLM settings as persisted under `backend.local.llm` (snake_case = YAML keys). */
 export interface LlmSettings {
   provider?: string;
-  model?: string;
   api_key?: string;
 }
 
@@ -61,15 +63,6 @@ export function resolveProvider(config: Config, env: NodeJS.ProcessEnv = process
   return detectProviderFromEnv(env);
 }
 
-/**
- * Effective model override: env override > config. Empty string means "no
- * override" — the runner picks the default from the platform model registry.
- */
-export function resolveModel(config: Config, env: NodeJS.ProcessEnv = process.env): string {
-  if (env.STIGMER_LLM_MODEL) return env.STIGMER_LLM_MODEL;
-  return readLlm(config)?.model ?? "";
-}
-
 /** Effective API key: ANTHROPIC_API_KEY env var > config. */
 export function resolveApiKey(config: Config, env: NodeJS.ProcessEnv = process.env): string {
   if (resolveProvider(config, env) !== "anthropic") return "";

package/src/local/setup/wizard.test.ts

@@ -21,11 +21,10 @@ describe("PROVIDER_CHOICES", () => {
 });
 
 describe("buildLlmForChoice", () => {
-  it("persists no model unless explicitly overridden — the registry owns the default", () => {
+  it("persists provider and key only — there is no model concept, the registry owns it (oss#314)", () => {
     expect(buildLlmForChoice("anthropic")).toEqual({ provider: "anthropic" });
-    expect(buildLlmForChoice("anthropic", { apiKey: "k", model: "m" })).toEqual({
+    expect(buildLlmForChoice("anthropic", { apiKey: "k" })).toEqual({
       provider: "anthropic",
-      model: "m",
       api_key: "k",
     });
   });

package/src/local/setup/wizard.ts

@@ -7,9 +7,9 @@
 // Local agent execution is Anthropic-only (the native runner only constructs
 // Anthropic clients and the registry's native entries are Anthropic models),
 // so the interactive flow is a single API-key prompt rather than a provider
-// menu. The model is deliberately NOT asked for: the platform model registry
-// owns the execution default, and an explicit override is a power-user flag
-// (`stigmer setup --model …`), not a setup question.
+// menu. There is no model concept here at all: the platform model registry
+// owns the execution default, and per-run overrides belong to `stigmer run
+// --model` (oss#314 removed the dead setup-level pin).
 
 import type { Config } from "../../config/config.js";
 import { type LlmSettings, setLlm } from "../llm-config.js";
@@ -27,19 +27,17 @@ export type ProviderChoice = (typeof PROVIDER_CHOICES)[number];
 
 export interface SelectionInputs {
   apiKey?: string;
-  model?: string;
 }
 
 /**
- * Resolve a provider choice (plus optional overrides) to the LLM settings to
- * persist. "skip" yields `undefined`, which clears the section. An omitted
- * model is stored as absent — meaning "platform default", resolved from the
- * model registry at execution time.
+ * Resolve a provider choice (plus an optional API key) to the LLM settings to
+ * persist. "skip" yields `undefined`, which clears the section — including any
+ * stale `model` key from a pre-oss#314 config, since setLlm replaces the
+ * section wholesale.
  */
 export function buildLlmForChoice(choice: ProviderChoice, inputs: SelectionInputs = {}): LlmSettings | undefined {
   if (choice === "skip") return undefined;
   const settings: LlmSettings = { provider: choice };
-  if (inputs.model) settings.model = inputs.model;
   if (inputs.apiKey) settings.api_key = inputs.apiKey;
   return settings;
 }

package/src/local/state/startup-config.ts

@@ -1,19 +1,23 @@
-// Configuration captured at `up` time so the daemon can restart components with
-// the same settings the user launched with. Persisted as `startup-config.json`
-// in the data dir; JSON keys are snake_case to match the Go CLI's file.
+// A diagnostic snapshot of the settings `up` launched with, persisted as
+// `startup-config.json` in the data dir and removed by `down`. Nothing in the
+// CLI or daemon reads it back — it exists for humans and support tooling
+// inspecting a running stack, so keep it truthful: a field that no component
+// consumes does not belong here (oss#314 removed the write-only llm_* trio).
+// JSON keys stay snake_case for continuity with previously-written files.
 
 import { readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { STARTUP_CONFIG_FILE } from "../constants.js";
 
-/** The persisted launch configuration. Mirrors the Go `StartupConfig` struct. */
+/**
+ * The persisted launch snapshot. `loadStartupConfig` parses leniently (a cast,
+ * not a validator), so files written by older CLIs with extra fields — e.g.
+ * the removed llm_* trio — load without migration.
+ */
 export interface StartupConfig {
   data_dir: string;
   log_dir: string;
   temporal_addr: string;
-  llm_provider: string;
-  llm_model: string;
-  llm_base_url: string;
   execution_mode: string;
   sandbox_image: string;
   sandbox_auto_pull: boolean;

package/src/local/state/state.test.ts

@@ -82,9 +82,6 @@ describe("startup-config", () => {
       data_dir: dir,
       log_dir: join(dir, "logs"),
       temporal_addr: "127.0.0.1:7233",
-      llm_provider: "anthropic",
-      llm_model: "claude",
-      llm_base_url: "",
       execution_mode: "local",
       sandbox_image: "",
       sandbox_auto_pull: false,
@@ -98,6 +95,29 @@ describe("startup-config", () => {
     removeStartupConfig(dir);
     expect(loadStartupConfig(dir)).toBeNull();
   });
+
+  it("loads files written by older CLIs carrying since-removed fields (e.g. the llm_* trio)", () => {
+    // The lenient-load contract oss#314 leans on: no migration for on-disk
+    // files — extra keys simply come along and nothing consumes them.
+    const dir = tempDir("stigmer-startup-");
+    const legacy = {
+      data_dir: dir,
+      log_dir: join(dir, "logs"),
+      temporal_addr: "127.0.0.1:7233",
+      llm_provider: "anthropic",
+      llm_model: "claude",
+      llm_base_url: "",
+      execution_mode: "local",
+      sandbox_image: "",
+      sandbox_auto_pull: false,
+      sandbox_cleanup: true,
+      sandbox_ttl: 0,
+      stigmer_server_pid: 999,
+      server_only: false,
+    };
+    writeFileSync(join(dir, "startup-config.json"), JSON.stringify(legacy));
+    expect(loadStartupConfig(dir)).toMatchObject({ temporal_addr: "127.0.0.1:7233", stigmer_server_pid: 999 });
+  });
 });
 
 describe("log-rotation", () => {

package/src/local/status.test.ts

@@ -62,12 +62,12 @@ describe("buildStatusResult", () => {
     expect(field(result, "Web UI", "Temporal")).toBe("http://localhost:8233");
   });
 
-  it("shows an explicit model override verbatim", async () => {
+  it("ignores a stale model key from a pre-oss#314 config — the pin never reached execution, so status must not display it", async () => {
     writeHealth({ daemon_pid: process.pid, started_at: new Date().toISOString(), components: {} });
     writeFileSync(configPath(home), "backend:\n  type: local\n  local:\n    llm:\n      provider: anthropic\n      model: claude-x\n      api_key: sk-x\n");
 
     const result = await buildStatusResult(home, open);
-    expect(field(result, "LLM Configuration", "Model")).toBe("claude-x");
+    expect(field(result, "LLM Configuration", "Model")).toBe("Auto (platform default)");
   });
 
   it("reports a non-anthropic provider as unknown — local execution is Anthropic-only", async () => {

package/src/local/status.ts

@@ -13,7 +13,7 @@ import { load as loadConfig } from "../config/config.js";
 import { configPath } from "../config/paths.js";
 import { CommandResult } from "../output/command-result.js";
 import { SERVER_PORT, TEMPORAL_UI_PORT, WEB_CONSOLE_PORT } from "./constants.js";
-import { resolveApiKey, resolveModel, resolveProvider } from "./llm-config.js";
+import { resolveApiKey, resolveProvider } from "./llm-config.js";
 import { tcpConnects } from "./net/tcp.js";
 import { dataDir } from "./paths.js";
 import { type ComponentState, type HealthState, loadHealthState } from "./state/health-state.js";
@@ -130,12 +130,11 @@ function addLlmSection(result: CommandResult, home: string): void {
     return;
   }
 
-  // An unset model is not a gap: the platform model registry picks the
-  // execution default, so the CLI reports that truthfully instead of asserting
-  // a version it does not control.
-  const model = resolveModel(config);
+  // The model line is a constant: the platform model registry picks the
+  // execution default and the CLI has no model concept to report (oss#314
+  // removed the dead config pin). Per-run overrides ride `stigmer run --model`.
   section.field("Provider", "Anthropic (Cloud)");
-  section.field("Model", model !== "" ? model : "Auto (platform default)");
+  section.field("Model", "Auto (platform default)");
   section.field("API Key", resolveApiKey(config) !== "" ? "Configured ✓" : "Not configured ✗");
 }
 

package/src/resources/apply/apply.test.ts

@@ -0,0 +1,134 @@
+// Unit tests for the shared apply core's declared-visibility follow-up
+// (oss#573). Plain updates preserve stored visibility on both editions, so
+// the apply RPC's response carries the STORED level; when a manifest
+// declares a different one, the core must land it through the guarded
+// updateVisibility RPC — or warn when the kind has no such door.
+
+import { create, type Message } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { describe, expect, it } from "vitest";
+import { applyMessage } from "./apply.js";
+import type { ApplyHandler, ControllerFn } from "./handlers.js";
+
+// The controller accessor is only ever forwarded to handler methods, which
+// these tests stub out — a throwing dummy proves nothing else touches it.
+const controller: ControllerFn = () => {
+  throw new Error("unexpected controller access");
+};
+
+function agent(visibility: ApiResourceVisibility, id = "agent-1") {
+  return create(AgentSchema, {
+    metadata: { id, name: "a", org: "acme", visibility },
+    spec: { instructions: "i" },
+  });
+}
+
+interface HandlerOptions {
+  applyReturns: Message;
+  updateVisibility?: (input: UpdateVisibilityInput) => Promise<Message>;
+}
+
+function handlerWith(opts: HandlerOptions): { handler: ApplyHandler; calls: UpdateVisibilityInput[] } {
+  const calls: UpdateVisibilityInput[] = [];
+  const handler: ApplyHandler = {
+    kind: ApiResourceKind.agent,
+    displayName: "Agent",
+    schema: AgentSchema,
+    applyOrder: 3,
+    apply: () => Promise.resolve(opts.applyReturns),
+    ...(opts.updateVisibility !== undefined && {
+      updateVisibility: (_c: ControllerFn, input: UpdateVisibilityInput) => {
+        calls.push(input);
+        return opts.updateVisibility!(input);
+      },
+    }),
+  };
+  return { handler, calls };
+}
+
+describe("applyMessage declared-visibility follow-up", () => {
+  it("lands a declared level the update preserved away, and reflects it on the outcome", async () => {
+    // Server preserved stored org; manifest declares public.
+    const { handler, calls } = handlerWith({
+      applyReturns: agent(ApiResourceVisibility.visibility_org),
+      updateVisibility: () => Promise.resolve(agent(ApiResourceVisibility.visibility_public)),
+    });
+
+    const outcome = await applyMessage(controller, handler, agent(ApiResourceVisibility.visibility_public), "acme", false);
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].resourceId).toBe("agent-1");
+    expect(calls[0].visibility).toBe(ApiResourceVisibility.visibility_public);
+    expect(outcome.warning).toBeUndefined();
+    const appliedMeta = (outcome.applied as { metadata?: { visibility?: ApiResourceVisibility } })?.metadata;
+    expect(appliedMeta?.visibility).toBe(ApiResourceVisibility.visibility_public);
+  });
+
+  it("skips the follow-up when the manifest omits visibility", async () => {
+    const { handler, calls } = handlerWith({
+      applyReturns: agent(ApiResourceVisibility.visibility_org),
+      updateVisibility: () => Promise.reject(new Error("must not be called")),
+    });
+
+    const outcome = await applyMessage(
+      controller,
+      handler,
+      agent(ApiResourceVisibility.api_resource_visibility_unspecified),
+      "acme",
+      false,
+    );
+
+    expect(calls).toHaveLength(0);
+    expect(outcome.warning).toBeUndefined();
+  });
+
+  it("skips the follow-up when the server already matches (idempotent re-apply)", async () => {
+    const { handler, calls } = handlerWith({
+      applyReturns: agent(ApiResourceVisibility.visibility_public),
+      updateVisibility: () => Promise.reject(new Error("must not be called")),
+    });
+
+    const outcome = await applyMessage(controller, handler, agent(ApiResourceVisibility.visibility_public), "acme", false);
+
+    expect(calls).toHaveLength(0);
+    expect(outcome.warning).toBeUndefined();
+  });
+
+  it("warns instead of silently swallowing a diff on kinds without the RPC", async () => {
+    const { handler } = handlerWith({
+      applyReturns: agent(ApiResourceVisibility.visibility_private),
+    });
+
+    const outcome = await applyMessage(controller, handler, agent(ApiResourceVisibility.visibility_public), "acme", false);
+
+    expect(outcome.warning).toMatch(/visibility cannot be changed declaratively/);
+    expect(outcome.warning).toMatch(/stored value is kept/);
+  });
+
+  it("fails loudly when the guarded door rejects, naming the partial state", async () => {
+    // e.g. the default-instance FAILED_PRECONDITION or an unsupported level.
+    const { handler } = handlerWith({
+      applyReturns: agent(ApiResourceVisibility.visibility_org),
+      updateVisibility: () => Promise.reject(new Error("default instances do not have their own visibility")),
+    });
+
+    await expect(
+      applyMessage(controller, handler, agent(ApiResourceVisibility.visibility_public), "acme", false),
+    ).rejects.toThrow(/spec applied, but the manifest's visibility change was rejected/);
+  });
+
+  it("does not follow up in dry-run mode", async () => {
+    const { handler, calls } = handlerWith({
+      applyReturns: agent(ApiResourceVisibility.visibility_org),
+      updateVisibility: () => Promise.reject(new Error("must not be called")),
+    });
+
+    const outcome = await applyMessage(controller, handler, agent(ApiResourceVisibility.visibility_public), "acme", true);
+
+    expect(calls).toHaveLength(0);
+    expect(outcome.applied).toBeUndefined();
+  });
+});