@stigmer/cli 3.12.4 → 3.12.5

package/src/local/seedpack/apply.test.ts

@@ -1,11 +1,19 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Message } from "@bufbuild/protobuf";
+import type { Stigmer } from "@stigmer/sdk";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { buildDeclarativeItems, scanResourceFiles } from "../../resources/apply/declarative.js";
 import type { ControllerFn } from "../../resources/apply/handlers.js";
-import { applySeedpack, resolveSeedpackOrg, seedpackContentHash } from "./apply.js";
+import {
+  applySeedpack,
+  readServerSeedpackHash,
+  resolveSeedpackOrg,
+  SEEDPACK_HASH_LABEL,
+  SEEDPACK_PROJECT_SLUG,
+  seedpackContentHash,
+} from "./apply.js";
 import type { SeedpackContent } from "./content.js";
 import { extractSeedpack, readMarker, resolveSeedpackContent } from "./content.js";
 
@@ -43,27 +51,43 @@ function makeContent(): SeedpackContent {
   return { dir, source: "repo" };
 }
 
-// Records each applied message's proto type name; every controller resolves to
-// the same stub apply (the handlers only call `.apply`).
-function recordingDeps() {
+// Records each applied message (and its proto type name); every controller
+// resolves to the same stub apply (the handlers only call `.apply`).
+function recordingDeps(stigmer?: unknown) {
   const applied: string[] = [];
+  const appliedMessages: Message[] = [];
   const controller = (() => ({
     apply: async (m: Message) => {
       applied.push((m as { $typeName: string }).$typeName);
+      appliedMessages.push(m);
       return m;
     },
   })) as unknown as ControllerFn;
   return {
     applied,
+    appliedMessages,
     deps: {
       controller,
-      stigmer: {} as never,
+      stigmer: (stigmer ?? {}) as never,
       info: () => {},
       warn: () => {},
     },
   };
 }
 
+// A Stigmer stub whose project.getByReference reports the given stored hash
+// (null → the label is absent; "absent" → the project itself does not exist).
+function stigmerWithServerHash(stored: string | null | "absent"): Stigmer {
+  return {
+    project: {
+      getByReference: async () => {
+        if (stored === "absent") throw new Error("not found");
+        return { metadata: { labels: stored === null ? {} : { [SEEDPACK_HASH_LABEL]: stored } } };
+      },
+    },
+  } as unknown as Stigmer;
+}
+
 let content: SeedpackContent;
 let markerDir: string;
 beforeEach(() => {
@@ -125,6 +149,91 @@ describe("applySeedpack", () => {
     expect(result.applied).toBe(true);
     expect(forced.applied.length).toBeGreaterThan(0);
   });
+
+  it("stamps the content hash as a reserved label on the applied Project", async () => {
+    const { appliedMessages, deps } = recordingDeps();
+    const result = await applySeedpack(deps, { markerDir, content });
+
+    const project = appliedMessages.find((m) => (m as { $typeName: string }).$typeName.endsWith("Project")) as
+      | { metadata?: { labels: Record<string, string> } }
+      | undefined;
+    expect(project).toBeDefined();
+    expect(project?.metadata?.labels[SEEDPACK_HASH_LABEL]).toBe(result.hash);
+  });
+});
+
+describe("applySeedpack — cloud mode (useServerHash)", () => {
+  it("skips when the server's recorded hash matches, without touching the marker", async () => {
+    const hash = seedpackContentHash({ content });
+    const { applied, deps } = recordingDeps(stigmerWithServerHash(hash));
+
+    const result = await applySeedpack(deps, { markerDir, content, useServerHash: true });
+
+    expect(result.applied).toBe(false);
+    expect(applied).toHaveLength(0);
+    expect(readMarker(markerDir)).toBeNull();
+  });
+
+  it("applies when the server records a different hash — and never writes the marker", async () => {
+    const { applied, deps } = recordingDeps(stigmerWithServerHash("sha256:0000000000000000"));
+
+    const result = await applySeedpack(deps, { markerDir, content, useServerHash: true });
+
+    expect(result.applied).toBe(true);
+    expect(applied.length).toBeGreaterThan(0);
+    // Cloud mode's record is the Project label; a marker here would be a
+    // second record of the same fact, free to drift.
+    expect(readMarker(markerDir)).toBeNull();
+  });
+
+  it("applies when the seedpack Project does not exist yet (first bootstrap)", async () => {
+    const { applied, deps } = recordingDeps(stigmerWithServerHash("absent"));
+
+    const result = await applySeedpack(deps, { markerDir, content, useServerHash: true });
+
+    expect(result.applied).toBe(true);
+    expect(applied.length).toBeGreaterThan(0);
+  });
+
+  it("ignores a stale local marker: the server is the only truth consulted", async () => {
+    const hash = seedpackContentHash({ content });
+    // A leftover marker from the pre-cloud#429 era says "up to date"…
+    const { deps: first } = recordingDeps();
+    await applySeedpack(first, { markerDir, content });
+    // …but the server has never seen this content.
+    const { applied, deps } = recordingDeps(stigmerWithServerHash(null));
+
+    const result = await applySeedpack(deps, { markerDir, content, useServerHash: true });
+
+    expect(result.applied).toBe(true);
+    expect(applied.length).toBeGreaterThan(0);
+    expect(hash).toBe(result.hash);
+  });
+
+  it("re-applies when forced even if the server hash matches", async () => {
+    const hash = seedpackContentHash({ content });
+    const { applied, deps } = recordingDeps(stigmerWithServerHash(hash));
+
+    const result = await applySeedpack(deps, { markerDir, content, useServerHash: true, force: true });
+
+    expect(result.applied).toBe(true);
+    expect(applied.length).toBeGreaterThan(0);
+  });
+});
+
+describe("readServerSeedpackHash", () => {
+  it("returns the recorded label", async () => {
+    const hash = await readServerSeedpackHash(stigmerWithServerHash("sha256:abcdef0123456789"), "stigmer");
+    expect(hash).toBe("sha256:abcdef0123456789");
+  });
+
+  it("returns null when the label is absent", async () => {
+    expect(await readServerSeedpackHash(stigmerWithServerHash(null), "stigmer")).toBeNull();
+  });
+
+  it("returns null when the project cannot be read (never applied / transient failure)", async () => {
+    expect(await readServerSeedpackHash(stigmerWithServerHash("absent"), "stigmer")).toBeNull();
+  });
 });
 
 describe("seedpackContentHash", () => {
@@ -139,6 +248,18 @@ describe("seedpackContentHash", () => {
 // CI canary manifest) must live outside the content set, never beside the
 // McpServer YAMLs where `loadDocuments(strict)` would reject it for missing a
 // `kind`. The synthetic fixtures above can't catch this — only real content can.
+// The cloud-mode hash read addresses the seedpack Project by a pinned slug.
+// The server derives the slug from the manifest's metadata.name, so this pin
+// holds exactly as long as the real seedpack keeps that name — verify against
+// the real content so a rename there fails here, not silently in prod.
+describe("SEEDPACK_PROJECT_SLUG pins the real manifest name", () => {
+  it("matches seedpack/stigmer.yaml metadata.name", () => {
+    const real = resolveSeedpackContent();
+    const manifest = readFileSync(join(real.dir, "stigmer.yaml"), "utf8");
+    expect(manifest).toMatch(new RegExp(`name:\\s*${SEEDPACK_PROJECT_SLUG}\\s*$`, "m"));
+  });
+});
+
 describe("real seedpack content loads through the declarative scanner", () => {
   it("scans + builds apply items without a missing-kind error", () => {
     const real = resolveSeedpackContent();

package/src/local/seedpack/apply.ts

@@ -10,11 +10,18 @@
 //   2. the project (stigmer.yaml + agents/skills/mcp-servers/workflows) via the
 //      declarative reconciler, under the target org.
 //
-// Idempotent: a content-hash marker skips the apply when nothing changed.
+// Idempotent, with the applied-hash truth living with the backend it describes
+// (cloud#429): every apply stamps the content hash as a reserved label on the
+// seedpack Project, and cloud-mode runs skip by reading that label back — so
+// any machine (operator laptop, CI) sees the same applied state. Local mode
+// keeps the original marker file (the local data dir lives and dies with the
+// local backend, so a local file IS backend-scoped state there).
 
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import type { Stigmer } from "@stigmer/sdk";
 import { applyItem, resolveApplyItems } from "../../resources/apply/apply.js";
 import { applyDeclarative, detectTrack } from "../../resources/apply/declarative.js";
@@ -31,6 +38,23 @@ import {
 const DEFAULT_ORG = "stigmer";
 const ORG_ENV_VAR = "STIGMER_SEEDPACK_ORG";
 
+/**
+ * Reserved label on the seedpack Project recording the last applied content
+ * hash (cloud#429). Writing a NEW value requires `can_write_reserved_labels`
+ * (the seeding identity's capability); re-sending an unchanged value is an
+ * echo the cloud guard passes for any caller — so re-applies of identical
+ * content are never treated as reserved-label writes.
+ */
+export const SEEDPACK_HASH_LABEL = "stigmer.ai/seedpack-hash";
+
+/**
+ * The seedpack Project's slug. The server derives it from the manifest's
+ * `metadata.name` in `seedpack/stigmer.yaml` — "stigmer-seedpack" is already
+ * slug-shaped, so name and slug coincide. Pinned by a test against the real
+ * content so a rename there fails loudly here.
+ */
+export const SEEDPACK_PROJECT_SLUG = "stigmer-seedpack";
+
 export interface SeedpackApplyDeps {
   /** Raw command-controller accessor (full-proto apply, preserves metadata.id). */
   readonly controller: ControllerFn;
@@ -43,7 +67,7 @@ export interface SeedpackApplyDeps {
 }
 
 export interface SeedpackApplyOptions {
-  /** Directory holding the idempotency marker (data dir for local, config dir for cloud). */
+  /** Directory holding the idempotency marker (local mode only). */
   readonly markerDir: string;
   /** Target org slug. Defaults to STIGMER_SEEDPACK_ORG, then "stigmer". */
   readonly org?: string;
@@ -52,6 +76,13 @@ export interface SeedpackApplyOptions {
   /** Pre-resolved content (injectable for tests); resolved on demand otherwise. */
   readonly content?: SeedpackContent;
   readonly home?: string;
+  /**
+   * Cloud mode: the idempotency truth is the {@link SEEDPACK_HASH_LABEL} on the
+   * server's seedpack Project, read via {@link readServerSeedpackHash} — the
+   * local marker is neither read nor written, so a stateless machine (CI, a
+   * second operator laptop) still skips unchanged content correctly.
+   */
+  readonly useServerHash?: boolean;
 }
 
 export interface SeedpackApplyResult {
@@ -77,17 +108,35 @@ export function seedpackContentHash(opts: Pick<SeedpackApplyOptions, "content" |
   return hashSeedpackContent(content.dir);
 }
 
+/**
+ * Read the applied content hash recorded on the backend's seedpack Project,
+ * or null when it cannot be proven (project absent — never applied — or the
+ * read failed). Null means "apply": the apply itself is idempotent server-side,
+ * so an unprovable state costs one redundant pass, never a skipped update.
+ */
+export async function readServerSeedpackHash(stigmer: Stigmer, org: string): Promise<string | null> {
+  try {
+    const project = await stigmer.project.getByReference({ org, slug: SEEDPACK_PROJECT_SLUG });
+    return project.metadata?.labels?.[SEEDPACK_HASH_LABEL] ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Apply the seedpack to the backend the deps connect to. Returns `applied:false`
- * (without touching the backend) when the marker already matches the content
- * hash and `force` is not set.
+ * (without touching the backend beyond the cloud-mode hash read) when the
+ * recorded hash already matches the content hash and `force` is not set.
  */
 export async function applySeedpack(deps: SeedpackApplyDeps, opts: SeedpackApplyOptions): Promise<SeedpackApplyResult> {
   const org = resolveSeedpackOrg(opts.org);
   const content = opts.content ?? resolveSeedpackContent({ home: opts.home });
   const hash = hashSeedpackContent(content.dir);
 
-  if (opts.force !== true && readMarker(opts.markerDir) === hash) {
+  const appliedHash = opts.useServerHash === true
+    ? await readServerSeedpackHash(deps.stigmer, org)
+    : readMarker(opts.markerDir);
+  if (opts.force !== true && appliedHash === hash) {
     return { applied: false, hash, org };
   }
 
@@ -96,8 +145,12 @@ export async function applySeedpack(deps: SeedpackApplyDeps, opts: SeedpackApply
   try {
     extractSeedpack(content.dir, stage);
     await applyOrganizations(deps, stage);
-    await applyProject(deps, stage, org);
-    writeMarker(opts.markerDir, hash);
+    await applyProject(deps, stage, org, hash);
+    // The Project label written above is the cloud-mode record; the marker
+    // stays the local-mode one. Never both — two records of one fact drift.
+    if (opts.useServerHash !== true) {
+      writeMarker(opts.markerDir, hash);
+    }
   } finally {
     rmSync(stage, { recursive: true, force: true });
   }
@@ -124,11 +177,18 @@ async function applyOrganizations(deps: SeedpackApplyDeps, stageDir: string): Pr
 
 // Phase 2: the project (agents, skills, MCP servers, workflows) via the shared
 // declarative reconciler — the same path `stigmer apply` runs for a user project.
-async function applyProject(deps: SeedpackApplyDeps, stageDir: string, org: string): Promise<void> {
+//
+// The content hash is stamped as a reserved label on the Project HERE, in the
+// seedpack path only — general `stigmer apply` never writes reserved labels.
+// The stamp rides the project apply that happens anyway, so recording the hash
+// costs no extra RPC and can never succeed while the apply failed.
+async function applyProject(deps: SeedpackApplyDeps, stageDir: string, org: string, contentHash: string): Promise<void> {
   const detect = detectTrack(stageDir);
-  if (detect.track !== "declarative") {
+  if (detect.track !== "declarative" || detect.project === undefined) {
     throw new Error(`seedpack is not a declarative project (detected '${detect.track}')`);
   }
+  detect.project.metadata ??= create(ApiResourceMetadataSchema, {});
+  detect.project.metadata.labels[SEEDPACK_HASH_LABEL] = contentHash;
   await applyDeclarative(detect, {
     controller: deps.controller,
     stigmer: deps.stigmer,

package/src/resources/apply/apply.ts

@@ -8,6 +8,7 @@
 
 import { create, fromJson, type JsonValue, type Message } from "@bufbuild/protobuf";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/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 { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -19,6 +20,7 @@ import { UsageError } from "../../errors/index.js";
 import { CommandResult } from "../../output/index.js";
 import { defaultRegistry, Verb } from "../../registry/index.js";
 import { loadDocuments, resolveYamlFiles } from "../documents.js";
+import { decodeWorkflowTaskConfigs } from "../task-configs.js";
 import { type ApplyHandler, APPLY_HANDLERS, type ControllerFn } from "./handlers.js";
 
 export interface ApplyItem {
@@ -112,7 +114,15 @@ export async function applyItem(
  */
 export function marshalItem(item: ApplyItem): Message {
   try {
-    return fromJson(item.handler.schema, item.document, { ignoreUnknownFields: false });
+    const message = fromJson(item.handler.schema, item.document, { ignoreUnknownFields: false });
+    // Workflow task_config blocks live inside an open Struct the top-level
+    // decode cannot see into; decode them per kind so a dry-run (and the
+    // reconciler's marshal) rejects exactly what a real apply rejects
+    // (stigmer/stigmer#778).
+    if (item.handler.kind === ApiResourceKind.workflow) {
+      decodeWorkflowTaskConfigs(message as Workflow);
+    }
+    return message;
   } catch (err) {
     throw new UsageError(`invalid ${item.handler.displayName} in ${item.filePath}: ${(err as Error).message}`);
   }

package/src/resources/connect/connect.ts

@@ -1,7 +1,9 @@
-// `connect mcp-server` orchestration. Mirrors Go's mcpserver.Connect (connect.go):
-// resolve the server, then either push to the backend (the Connect RPC runs
-// discovery server-side and persists capabilities + tool-approval policies) or,
-// for --dry-run, discover locally and return without persisting.
+// `connect mcp-server` orchestration. Resolve the server, then either run the
+// server-side connect (discovery + tool-approval classification, persisted on
+// the resource) or, for --dry-run, discover locally and return without
+// persisting. The server-side path uses the async lane — startConnect + poll
+// (stigmer/stigmer#425) — with a blocking-RPC fallback for backends that
+// predate it.
 //
 // OAuth: when a server requires OAuth, has no existing grant, and no --env was
 // supplied, the interactive browser flow (oauth.ts) shepherds the user through
@@ -11,10 +13,12 @@
 
 import { create } from "@bufbuild/protobuf";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { ConnectInput } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { ConnectInputSchema, GetOAuthGrantStatusInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import type { DiscoveredCapabilities } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { Stigmer } from "@stigmer/sdk";
+import { connectAndWait, ConnectStillRunningError, CONNECT_SETTLE_BOUND_MS } from "@stigmer/sdk";
 import type { BackendType } from "../../config/config.js";
 import { CliExitError, ExitCode, UsageError } from "../../errors/index.js";
 import { defaultRegistry } from "../../registry/index.js";
@@ -49,6 +53,13 @@ export interface ConnectResult {
   readonly capabilities: DiscoveredCapabilities | undefined;
   /** Set when capabilities were persisted (non-dry-run); undefined for dry-run. */
   readonly updated: McpServer | undefined;
+  /**
+   * Start-time advisory from the backend's connect pre-flight (e.g. "no
+   * runner appears to be polling the task queue"). Only set on the async
+   * lane, and only when the operation ultimately settled anyway — surfaced
+   * so the user learns their runner came up late.
+   */
+  readonly warning?: string;
 }
 
 /** Connect to an MCP server and discover its capabilities (push or dry-run). */
@@ -75,50 +86,65 @@ export async function connectMcpServer(client: Stigmer, opts: ConnectOptions): P
 
   await ensureOAuthSatisfied(client, server, opts);
 
-  const push = client.mcpServer.connect(
-    create(ConnectInputSchema, {
-      mcpServerId: server.metadata?.id ?? "",
-      org: opts.org,
-      runtimeEnv: buildRuntimeEnv(server, opts.envOverrides),
-    }),
-  );
-  const updated = opts.pushTimeoutMs === undefined
-    ? await push
-    : await boundedPush(push, opts.pushTimeoutMs, server);
-  return { server, capabilities: updated.status?.discoveredCapabilities, updated };
+  const input = create(ConnectInputSchema, {
+    mcpServerId: server.metadata?.id ?? "",
+    org: opts.org,
+    runtimeEnv: buildRuntimeEnv(server, opts.envOverrides),
+  });
+  return serverSideConnect(client, server, input, opts);
 }
 
-// Soft timeout on the server-side connect (the client/client.ts idiom): races
-// the RPC against a timer without cancelling it — the backend's connect
-// workflow keeps running and persists its result on its own, so the message
-// says exactly that instead of implying the connect failed.
-async function boundedPush<T>(push: Promise<T>, timeoutMs: number, server: McpServer): Promise<T> {
+// Run the server-side connect through the SDK's shared async-lane protocol
+// (connectAndWait, stigmer/stigmer#425): startConnect + poll, with the
+// blocking-RPC fallback for backends that predate the lane. The CLI's job is
+// only to translate its --timeout semantics and turn a still-running stop
+// into its own actionable guidance.
+async function serverSideConnect(
+  client: Stigmer,
+  server: McpServer,
+  input: ConnectInput,
+  opts: ConnectOptions,
+): Promise<ConnectResult> {
   const slug = server.metadata?.slug ?? server.metadata?.id ?? "the server";
-  let timer: NodeJS.Timeout | undefined;
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(
-      () =>
-        reject(
-          new CliExitError(
-            `Stopped waiting for the connect of MCP server '${slug}' after ${timeoutMs / 1000}s (--timeout)`,
-            ExitCode.Connection,
-            [
-              "The server-side connect is still running and will persist its result if it succeeds.",
-              `Check the outcome with: stigmer get mcp-server ${slug}`,
-              "Re-run without --timeout to wait for completion.",
-            ],
-          ),
-        ),
-      timeoutMs,
-    );
-  });
-  // The losing push may settle after the CLI has started exiting; swallow its
-  // late rejection so it cannot surface as an unhandled-rejection crash.
-  void push.catch(() => {});
+  let warning = "";
   try {
-    return await Promise.race([push, timeout]);
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
+    const updated = await connectAndWait(client.mcpServer, input, {
+      deadlineMs: opts.pushTimeoutMs,
+      onStarted: (started) => {
+        warning = started.status?.connectStatus?.warning ?? "";
+      },
+    });
+    return {
+      server,
+      capabilities: updated.status?.discoveredCapabilities,
+      updated,
+      warning: warning !== "" ? warning : undefined,
+    };
+  } catch (err) {
+    if (!(err instanceof ConnectStillRunningError)) throw err;
+    if (opts.pushTimeoutMs !== undefined) {
+      // The user's explicit --timeout fired: historical soft-bound semantics.
+      throw new CliExitError(
+        `Stopped waiting for the connect of MCP server '${slug}' after ${opts.pushTimeoutMs / 1000}s (--timeout)`,
+        ExitCode.Connection,
+        [
+          "The server-side connect is still running and will persist its result if it succeeds.",
+          `Check the outcome with: stigmer get mcp-server ${slug}`,
+          "Re-run without --timeout to wait for completion.",
+        ],
+      );
+    }
+    // The SDK's settle bound fired: past the backend's own ceiling, only a
+    // connect_status orphaned by a backend restart can still read CONNECTING.
+    throw new CliExitError(
+      `The connect of MCP server '${slug}' did not settle within ${CONNECT_SETTLE_BOUND_MS / 60_000} minutes`,
+      ExitCode.Connection,
+      [
+        "This usually means the backend restarted mid-operation.",
+        `Check the current state with: stigmer get mcp-server ${slug}`,
+        "Re-run the connect to start a fresh operation.",
+      ],
+    );
   }
 }
 

package/src/resources/connect/display.ts

@@ -26,6 +26,9 @@ export function renderConnectResult(result: ConnectResult, sink: ConnectSink, co
   sink(result.updated !== undefined
     ? style.green("✓ Connected — capabilities and tool approvals saved")
     : style.yellow("⚠ Dry run — results not saved to backend"));
+  if (result.warning !== undefined) {
+    sink(style.yellow(`⚠ ${result.warning}`));
+  }
   sink("");
 }
 

package/src/resources/run/prepare.test.ts

@@ -70,6 +70,27 @@ const BASE_FLAGS: AgentExecFlags = {
 // with no attachments a bare stub suffices.
 const STUB_CLIENT = { agentExecution: {} } as unknown as Stigmer;
 
+/** Stub whose whoAmI resolves an account carrying the given preference. */
+function clientWithPreference(defaultNativeModel: string): Stigmer {
+  return {
+    agentExecution: {},
+    identityAccount: {
+      whoAmI: () =>
+        Promise.resolve({ spec: { preferences: { defaultNativeModel } } }),
+    },
+  } as unknown as Stigmer;
+}
+
+/** Stub whose whoAmI rejects (auth failure, backend without the RPC, ...). */
+function clientWithFailingWhoAmI(): Stigmer {
+  return {
+    agentExecution: {},
+    identityAccount: {
+      whoAmI: () => Promise.reject(new Error("unimplemented")),
+    },
+  } as unknown as Stigmer;
+}
+
 describe("prepareAgentExec env injection", () => {
   it("injects STIGMER_ORG_ID when absent", async () => {
     const prepared = await prepareAgentExec(BASE_FLAGS, STUB_CLIENT, "acme");
@@ -103,3 +124,62 @@ describe("prepareAgentExec env injection", () => {
     expect(prepared.mode).toBe("plan");
   });
 });
+
+describe("prepareAgentExec account-preference model fill (oss#293 Phase 1.5)", () => {
+  it("fills an omitted --model from the account preference on cloud", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreference("claude-sonnet-4.6"),
+      "acme",
+      undefined,
+      { cloudBackend: true },
+    );
+    expect(prepared.model).toBe("claude-sonnet-4.6");
+  });
+
+  it("an explicit --model always outranks the preference", async () => {
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, model: "gpt-5.3" },
+      clientWithPreference("claude-sonnet-4.6"),
+      "acme",
+      undefined,
+      { cloudBackend: true },
+    );
+    expect(prepared.model).toBe("gpt-5.3");
+  });
+
+  it("never consults identity on a local backend", async () => {
+    // The failing stub doubles as a call detector: local mode must not even
+    // attempt whoAmI, so a rejecting client cannot affect the result.
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithFailingWhoAmI(),
+      "acme",
+      undefined,
+      { cloudBackend: false },
+    );
+    expect(prepared.model).toBe("");
+  });
+
+  it("falls through silently when whoAmI fails — a missing preference never fails a run", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithFailingWhoAmI(),
+      "acme",
+      undefined,
+      { cloudBackend: true },
+    );
+    expect(prepared.model).toBe("");
+  });
+
+  it("stays empty when the account declares no native default", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreference(""),
+      "acme",
+      undefined,
+      { cloudBackend: true },
+    );
+    expect(prepared.model).toBe("");
+  });
+});