@stigmer/cli 3.12.6 → 3.12.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/cli",
-  "version": "3.12.6",
+  "version": "3.12.7",
   "description": "Stigmer command-line interface — manage agents, workflows, MCP servers, skills, and executions from the terminal",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,10 +35,10 @@
     "@connectrpc/connect": "^2.0.0",
     "@connectrpc/connect-node": "^2.1.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@stigmer/ink": "3.12.6",
-    "@stigmer/mcp-server": "3.12.6",
-    "@stigmer/protos": "3.12.6",
-    "@stigmer/sdk": "3.12.6",
+    "@stigmer/ink": "3.12.7",
+    "@stigmer/mcp-server": "3.12.7",
+    "@stigmer/protos": "3.12.7",
+    "@stigmer/sdk": "3.12.7",
     "commander": "^12.1.0",
     "fflate": "^0.8.3",
     "ink": "^7.0.0",

package/src/commands/setup.ts

@@ -1,11 +1,14 @@
-// `stigmer setup` — configure the LLM provider used for agent execution.
+// `stigmer setup` — configure the LLM provider used for agent execution and
+// the optional self-hosted operator identity (oss#796).
 //
 // Two paths share one decision core (local/setup/wizard.ts): a non-interactive
-// 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).
+// flag path (`--provider`/`--api-key`, `--operator-email`/`--operator-name`)
+// for scripts and CI, and an interactive flow when NO flag is given. Flags
+// are independently applicable — operator flags without `--provider` leave
+// the LLM section untouched, and vice versa. Writes land under
+// backend.local.llm / backend.local.operator, 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
@@ -21,45 +24,72 @@ import { addResultFlags, resultFormat } from "./shared.js";
 interface SetupFlags extends OutputFlags {
   provider?: string;
   apiKey?: string;
+  operatorEmail?: string;
+  operatorName?: string;
 }
 
 export function registerSetup(program: Command): void {
   const setup = program
     .command("setup")
-    .description("configure the LLM provider for agent execution")
+    .description("configure the LLM provider and operator identity for local execution")
     .option("--provider <name>", "provider: anthropic, or skip to clear (non-interactive)")
     .option("--api-key <key>", "Anthropic API key")
+    .option("--operator-email <email>", "operator identity for local caller attribution (non-interactive)")
+    .option("--operator-name <name>", "operator display name (requires --operator-email)")
     .action((options: SetupFlags) => runSetup(options));
   addResultFlags(setup);
 }
 
 async function runSetup(options: SetupFlags): Promise<void> {
   const { load, save } = await import("../config/config.js");
-  const { PROVIDER_CHOICES, applyChoice, runInteractiveWizard } = await import("../local/setup/wizard.js");
+  const { PROVIDER_CHOICES, applyChoice, applyOperatorIdentity, runInteractiveWizard } =
+    await import("../local/setup/wizard.js");
   const { isRunning } = await import("../local/daemon/launch.js");
   const { CliExitError } = await import("../errors/cli-exit-error.js");
   const { ExitCode } = await import("../errors/exit-codes.js");
 
   const config = load();
+  const nonInteractive =
+    options.provider !== undefined ||
+    options.operatorEmail !== undefined ||
+    options.operatorName !== undefined;
 
   let updated: typeof config;
-  if (options.provider !== undefined) {
-    const provider = options.provider.toLowerCase();
-    if (!(PROVIDER_CHOICES as readonly string[]).includes(provider)) {
-      throw new CliExitError(`unknown provider: ${options.provider}`, ExitCode.Usage, [
-        `Valid providers: ${PROVIDER_CHOICES.join(", ")}`,
-      ]);
+  if (nonInteractive) {
+    updated = config;
+    if (options.provider !== undefined) {
+      const provider = options.provider.toLowerCase();
+      if (!(PROVIDER_CHOICES as readonly string[]).includes(provider)) {
+        throw new CliExitError(`unknown provider: ${options.provider}`, ExitCode.Usage, [
+          `Valid providers: ${PROVIDER_CHOICES.join(", ")}`,
+        ]);
+      }
+      updated = applyChoice(updated, provider as (typeof PROVIDER_CHOICES)[number], {
+        apiKey: options.apiKey,
+      });
+    }
+    if (options.operatorEmail !== undefined || options.operatorName !== undefined) {
+      try {
+        updated = applyOperatorIdentity(
+          updated,
+          options.operatorEmail ?? "",
+          options.operatorName ?? "",
+        );
+      } catch (error) {
+        // Same rule the server enforces at boot, surfaced at setup time.
+        throw new CliExitError(
+          error instanceof Error ? error.message : String(error),
+          ExitCode.Usage,
+        );
+      }
     }
-    updated = applyChoice(config, provider as (typeof PROVIDER_CHOICES)[number], {
-      apiKey: options.apiKey,
-    });
   } else {
     updated = await runInteractiveWizard(config);
   }
 
   save(updated);
 
-  const result = CommandResult.success("LLM configuration saved");
+  const result = CommandResult.success("Configuration saved");
   if (await isRunning(homedir())) {
     result.hint("Restart to apply: stigmer down && stigmer up");
   }

package/src/local/daemon/components.test.ts

@@ -26,6 +26,26 @@ describe("buildServerEnv", () => {
     expect(env.DB_PATH).toBe("/home/u/.stigmer/stigmer.db");
     expect(env.STORAGE_PATH).toBe("/home/u/.stigmer/storage");
   });
+
+  it("forwards the operator identity only when set, resolved value winning over the base env (oss#796)", () => {
+    const bare = buildServerEnv(config, {});
+    expect(bare.STIGMER_OPERATOR_EMAIL).toBeUndefined();
+    expect(bare.STIGMER_OPERATOR_NAME).toBeUndefined();
+
+    // Contract value authoritative over a stale inherited export — the
+    // ANTHROPIC_API_KEY precedent in buildRunnerEnv.
+    const env = buildServerEnv(
+      { ...config, operatorEmail: "ada@example.com", operatorName: "Ada" },
+      { STIGMER_OPERATOR_EMAIL: "stale@example.com" },
+    );
+    expect(env.STIGMER_OPERATOR_EMAIL).toBe("ada@example.com");
+    expect(env.STIGMER_OPERATOR_NAME).toBe("Ada");
+  });
+
+  it("does not deliver the operator identity to the runner — it resolves identity from session data", () => {
+    const env = buildRunnerEnv({ ...config, operatorEmail: "ada@example.com" }, {});
+    expect(env.STIGMER_OPERATOR_EMAIL).toBeUndefined();
+  });
 });
 
 describe("buildRunnerEnv", () => {

package/src/local/daemon/components.ts

@@ -23,7 +23,7 @@ const SERVER_GATE_TIMEOUT_MS = 30_000;
  */
 export function buildServerEnv(config: DaemonConfig, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const configDir = dirname(config.dataDir); // ~/.stigmer
-  return {
+  const env: NodeJS.ProcessEnv = {
     ...base,
     GRPC_PORT: String(SERVER_PORT),
     TEMPORAL_HOST_PORT: config.temporalAddress,
@@ -37,6 +37,14 @@ export function buildServerEnv(config: DaemonConfig, base: NodeJS.ProcessEnv = p
     // is visible and enforceable here, next to the runner's LOCAL_ARTIFACT_PATH.
     ARTIFACT_LOCAL_BASE_PATH: join(config.dataDir, ARTIFACTS_SUBDIR),
   };
+  // Explicit set (after the base spread) so the launcher-resolved identity wins
+  // over a stale inherited value — the delivery path for a `stigmer setup`-
+  // persisted operator identity (oss#796; the ANTHROPIC_API_KEY precedent in
+  // buildRunnerEnv). Server child only: the runner resolves caller identity
+  // from the session's stamped created_by, never from its own env.
+  if (config.operatorEmail !== undefined) env.STIGMER_OPERATOR_EMAIL = config.operatorEmail;
+  if (config.operatorName !== undefined) env.STIGMER_OPERATOR_NAME = config.operatorName;
+  return env;
 }
 
 /**

package/src/local/daemon/env.test.ts

@@ -28,6 +28,8 @@ describe("buildDaemonEnv + readDaemonConfig", () => {
       cursorApiKey: undefined,
       anthropicApiKey: undefined,
       activityRouting: undefined,
+      operatorEmail: undefined,
+      operatorName: undefined,
     });
   });
 
@@ -61,6 +63,25 @@ describe("buildDaemonEnv + readDaemonConfig", () => {
     expect(config.anthropicApiKey).toBe("sk-ant-env");
   });
 
+  // The operator identity rides the same config-file-only delivery path as the
+  // Anthropic key (oss#796): persisted by `stigmer setup`, absent from the
+  // shell, written into the contract explicitly by the launcher.
+  it("delivers a launcher-resolved operator identity with no help from the base env", () => {
+    const env = buildDaemonEnv(
+      { ...baseInputs, operatorEmail: "ada@example.com", operatorName: "Ada Lovelace" },
+      {},
+    );
+    const config = readDaemonConfig(env);
+    expect(config.operatorEmail).toBe("ada@example.com");
+    expect(config.operatorName).toBe("Ada Lovelace");
+  });
+
+  it("passes a shell-exported operator identity through from the base env", () => {
+    const env = buildDaemonEnv(baseInputs, { STIGMER_OPERATOR_EMAIL: "env@example.com" });
+    expect(readDaemonConfig(env).operatorEmail).toBe("env@example.com");
+    expect(readDaemonConfig(env).operatorName).toBeUndefined();
+  });
+
   // Other provider keys have no contract slot; they reach the runner solely via
   // shell-env inheritance (the child env spreads the base env).
   it("leaves shell-exported non-Anthropic keys in the env without parsing them", () => {

package/src/local/daemon/env.ts

@@ -19,6 +19,8 @@ export const DaemonEnvVar = {
   CursorApiKey: "CURSOR_API_KEY",
   AnthropicApiKey: "ANTHROPIC_API_KEY",
   ActivityRouting: "STIGMER_ACTIVITY_ROUTING",
+  OperatorEmail: "STIGMER_OPERATOR_EMAIL",
+  OperatorName: "STIGMER_OPERATOR_NAME",
 } as const;
 
 /** Resolved runner launch coordinates. */
@@ -41,6 +43,8 @@ export interface DaemonConfig {
   cursorApiKey?: string;
   anthropicApiKey?: string;
   activityRouting?: string;
+  operatorEmail?: string;
+  operatorName?: string;
 }
 
 /** Inputs the launcher already resolved, to encode into the daemon env. */
@@ -60,6 +64,12 @@ export interface DaemonEnvInputs {
   // persisted delivery path — other keys (OPENAI_API_KEY, CURSOR_API_KEY)
   // reach the runner solely via shell-env inheritance.
   anthropicApiKey?: string;
+  // Operator identity resolved by the launcher (env > config file), the same
+  // persisted-delivery reasoning as the Anthropic key (oss#796). Consumed by
+  // the SERVER child only — the runner resolves caller identity from the
+  // session's stamped created_by, never from its own env.
+  operatorEmail?: string;
+  operatorName?: string;
 }
 
 /**
@@ -82,6 +92,8 @@ export function buildDaemonEnv(inputs: DaemonEnvInputs, base: NodeJS.ProcessEnv
     env[DaemonEnvVar.RunnerAppDir] = inputs.runner.appDir;
   }
   if (inputs.anthropicApiKey !== undefined) env[DaemonEnvVar.AnthropicApiKey] = inputs.anthropicApiKey;
+  if (inputs.operatorEmail !== undefined) env[DaemonEnvVar.OperatorEmail] = inputs.operatorEmail;
+  if (inputs.operatorName !== undefined) env[DaemonEnvVar.OperatorName] = inputs.operatorName;
   return env;
 }
 
@@ -105,6 +117,8 @@ export function readDaemonConfig(env: NodeJS.ProcessEnv = process.env): DaemonCo
     cursorApiKey: nonEmpty(env[DaemonEnvVar.CursorApiKey]),
     anthropicApiKey: nonEmpty(env[DaemonEnvVar.AnthropicApiKey]),
     activityRouting: nonEmpty(env[DaemonEnvVar.ActivityRouting]),
+    operatorEmail: nonEmpty(env[DaemonEnvVar.OperatorEmail]),
+    operatorName: nonEmpty(env[DaemonEnvVar.OperatorName]),
   };
 }
 

package/src/local/daemon/launch.ts

@@ -22,6 +22,7 @@ import { findProcessByPort, isProcessAlive, killProcess } from "../state/proc.js
 import { type StartupConfig, removeStartupConfig, saveStartupConfig } from "../state/startup-config.js";
 import { rotateLogs } from "../state/log-rotation.js";
 import { resolveApiKey, resolveProvider } from "../llm-config.js";
+import { resolveOperatorIdentity } from "../operator-config.js";
 import { ensureRunner } from "../runtime/runner.js";
 import { ensureServerBinary } from "../runtime/server.js";
 import { TemporalManager } from "../temporal/manager.js";
@@ -77,6 +78,7 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
       serverBin,
       runner,
       ...resolveLlmKeyInputs(config),
+      ...resolveOperatorIdentityInputs(config),
     },
     process.env,
   );
@@ -235,6 +237,21 @@ function resolveLlmKeyInputs(config: Config): Pick<DaemonEnvInputs, "anthropicAp
   return key === "" ? {} : { anthropicApiKey: key };
 }
 
+// Operator-identity delivery for the server child (oss#796): same persisted-
+// delivery reasoning as the LLM key above — a setup-persisted identity lives
+// only in the config file, so the launcher must write it into the daemon
+// contract explicitly. resolveOperatorIdentity's precedence (env > config,
+// sources never mixed) makes both cases one code path.
+function resolveOperatorIdentityInputs(
+  config: Config,
+): Pick<DaemonEnvInputs, "operatorEmail" | "operatorName"> {
+  const identity = resolveOperatorIdentity(config);
+  if (identity === undefined) return {};
+  return identity.name === undefined
+    ? { operatorEmail: identity.email }
+    : { operatorEmail: identity.email, operatorName: identity.name };
+}
+
 // Default to managed Temporal unless the opaque local config explicitly opts
 // out — zero-config `stigmer up` must work on a fresh machine.
 function isTemporalManaged(config: Config): boolean {

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

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import type { Config } from "../config/config.js";
+import {
+  readOperator,
+  resolveOperatorIdentity,
+  setOperator,
+  validateOperatorIdentity,
+} from "./operator-config.js";
+
+function config(local?: unknown): Config {
+  return { backend: { type: "local", local } };
+}
+
+describe("resolveOperatorIdentity", () => {
+  it("honors env > config, never mixing sources", () => {
+    const cfg = config({ operator: { email: "cfg@example.com", name: "Config Name" } });
+
+    // Env email brings the env name (or none) — the config name must not
+    // ride along under an env identity, that would be attribution lying.
+    expect(resolveOperatorIdentity(cfg, { STIGMER_OPERATOR_EMAIL: "env@example.com" })).toEqual({
+      email: "env@example.com",
+    });
+    expect(
+      resolveOperatorIdentity(cfg, {
+        STIGMER_OPERATOR_EMAIL: "env@example.com",
+        STIGMER_OPERATOR_NAME: "Env Name",
+      }),
+    ).toEqual({ email: "env@example.com", name: "Env Name" });
+
+    expect(resolveOperatorIdentity(cfg, {})).toEqual({
+      email: "cfg@example.com",
+      name: "Config Name",
+    });
+  });
+
+  it("returns undefined when neither source has an email — the anonymous default", () => {
+    expect(resolveOperatorIdentity(config(), {})).toBeUndefined();
+    expect(resolveOperatorIdentity(config({ operator: {} }), {})).toBeUndefined();
+    // Whitespace-only values are unset, matching the server's TrimSpace.
+    expect(resolveOperatorIdentity(config(), { STIGMER_OPERATOR_EMAIL: "  " })).toBeUndefined();
+  });
+
+  it("trims values, matching the server's boot check", () => {
+    const cfg = config({ operator: { email: " ada@example.com ", name: " Ada " } });
+    expect(resolveOperatorIdentity(cfg, {})).toEqual({ email: "ada@example.com", name: "Ada" });
+  });
+});
+
+describe("validateOperatorIdentity", () => {
+  it("mirrors the server's boot rules: minimal @ check, name requires email", () => {
+    expect(validateOperatorIdentity("ada@example.com", "Ada")).toBeUndefined();
+    expect(validateOperatorIdentity("ada@example.com", "")).toBeUndefined();
+    expect(validateOperatorIdentity("", "")).toBeUndefined(); // "no identity" is valid
+
+    expect(validateOperatorIdentity("not-an-email", "")).toContain("missing '@'");
+    expect(validateOperatorIdentity("", "Ada")).toContain("set both or neither");
+  });
+});
+
+describe("setOperator", () => {
+  it("preserves sibling local keys and can clear the section", () => {
+    const cfg = config({ temporal: { managed: true }, llm: { provider: "anthropic" } });
+    const updated = setOperator(cfg, { email: "ada@example.com", name: "Ada" });
+    expect(readOperator(updated)).toEqual({ email: "ada@example.com", name: "Ada" });
+    expect((updated.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
+    expect((updated.backend.local as { llm: unknown }).llm).toEqual({ provider: "anthropic" });
+
+    const cleared = setOperator(updated, undefined);
+    expect(readOperator(cleared)).toBeUndefined();
+    expect((cleared.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
+  });
+});

package/src/local/operator-config.ts

@@ -0,0 +1,95 @@
+// Typed view over `backend.local.operator` — the self-hosted operator
+// identity `setup` persists and the launcher delivers to the server child
+// (oss#796, the UX-completion arm of oss#400's configured operator identity).
+//
+// The lens pattern mirrors llm-config.ts: config/config.ts carries
+// `backend.local` verbatim so unknown siblings are never dropped; this module
+// owns exactly one sub-tree (`local.operator`) and resolves the effective
+// identity with env-override precedence (STIGMER_OPERATOR_EMAIL >
+// config file). Sources never mix: an env-provided email brings the
+// env-provided name (or none), a config-provided email brings the config
+// name — half-and-half identities would be attribution lies.
+//
+// Validation deliberately duplicates the server's boot check
+// (stigmer-server pkg/config/config.go loadOperatorIdentity): trim both
+// values; a non-empty email must contain '@' (nothing more — the server is
+// equally minimal on purpose); a name without an email is refused because
+// the email IS the identity. Checking here surfaces the failure at setup
+// time instead of at the next `stigmer up`.
+
+import type { Config } from "../config/config.js";
+
+/** Operator identity as persisted under `backend.local.operator` (snake_case = YAML keys). */
+export interface OperatorSettings {
+  email?: string;
+  name?: string;
+}
+
+interface LocalSection {
+  operator?: OperatorSettings;
+  [key: string]: unknown;
+}
+
+function localSection(config: Config): LocalSection {
+  const local = config.backend.local;
+  return local !== null && typeof local === "object" ? (local as LocalSection) : {};
+}
+
+/** The persisted operator settings, if any. */
+export function readOperator(config: Config): OperatorSettings | undefined {
+  return localSection(config).operator;
+}
+
+/**
+ * Effective operator identity: env > config file, sources never mixed.
+ * Returns `undefined` when neither source provides an email (the anonymous
+ * default oss#400 preserves).
+ */
+export function resolveOperatorIdentity(
+  config: Config,
+  env: NodeJS.ProcessEnv = process.env,
+): OperatorSettings | undefined {
+  const envEmail = (env.STIGMER_OPERATOR_EMAIL ?? "").trim();
+  if (envEmail !== "") {
+    const envName = (env.STIGMER_OPERATOR_NAME ?? "").trim();
+    return envName === "" ? { email: envEmail } : { email: envEmail, name: envName };
+  }
+  const persisted = readOperator(config);
+  const email = (persisted?.email ?? "").trim();
+  if (email === "") return undefined;
+  const name = (persisted?.name ?? "").trim();
+  return name === "" ? { email } : { email, name };
+}
+
+/**
+ * Validate an operator identity the way the server's boot check will
+ * (byte-similar messages so setup-time and boot-time failures read as one
+ * rule). Returns an error message, or undefined when valid. An empty email
+ * with an empty name is valid — it means "no identity", the wizard's skip.
+ */
+export function validateOperatorIdentity(email: string, name: string): string | undefined {
+  const trimmedEmail = email.trim();
+  const trimmedName = name.trim();
+  if (trimmedEmail !== "" && !trimmedEmail.includes("@")) {
+    return `"${trimmedEmail}" is not an email address (missing '@')`;
+  }
+  if (trimmedName !== "" && trimmedEmail === "") {
+    return "an operator name without an email is not an identity — set both or neither";
+  }
+  return undefined;
+}
+
+/**
+ * Return a copy of `config` with the operator section replaced, preserving
+ * every other key under `backend.local`. Passing `undefined` clears the
+ * section.
+ */
+export function setOperator(config: Config, settings: OperatorSettings | undefined): Config {
+  const local: LocalSection = { ...localSection(config) };
+  if (settings === undefined) {
+    delete local.operator;
+  } else {
+    local.operator = settings;
+  }
+  return { ...config, backend: { ...config.backend, local } };
+}

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

@@ -1,7 +1,14 @@
 import { describe, expect, it } from "vitest";
 import type { Config } from "../../config/config.js";
 import { readLlm } from "../llm-config.js";
-import { PROVIDER_CHOICES, applyChoice, buildLlmForChoice } from "./wizard.js";
+import { readOperator } from "../operator-config.js";
+import {
+  PROVIDER_CHOICES,
+  applyChoice,
+  applyOperatorIdentity,
+  buildLlmForChoice,
+  buildOperatorForInputs,
+} from "./wizard.js";
 
 function config(local?: unknown): Config {
   return { backend: { type: "local", local } };
@@ -47,3 +54,41 @@ describe("applyChoice", () => {
     expect(readLlm(updated)).toBeUndefined();
   });
 });
+
+describe("buildOperatorForInputs", () => {
+  it("persists email (and optional name), trimmed", () => {
+    expect(buildOperatorForInputs(" ada@example.com ", "")).toEqual({ email: "ada@example.com" });
+    expect(buildOperatorForInputs("ada@example.com", " Ada ")).toEqual({
+      email: "ada@example.com",
+      name: "Ada",
+    });
+  });
+
+  it("returns undefined for empty inputs — nothing to persist, identity stays anonymous", () => {
+    expect(buildOperatorForInputs("", "")).toBeUndefined();
+    expect(buildOperatorForInputs("  ", "")).toBeUndefined();
+  });
+
+  // The server's boot rules, surfaced at setup time (oss#796): a malformed
+  // identity must never be persisted only to fail the next `stigmer up`.
+  it("refuses what the server's boot check would refuse", () => {
+    expect(() => buildOperatorForInputs("not-an-email", "")).toThrow(/missing '@'/);
+    expect(() => buildOperatorForInputs("", "Ada")).toThrow(/set both or neither/);
+  });
+});
+
+describe("applyOperatorIdentity", () => {
+  it("writes the identity while preserving siblings", () => {
+    const cfg = config({ temporal: { managed: true }, llm: { provider: "anthropic" } });
+    const updated = applyOperatorIdentity(cfg, "ada@example.com", "Ada");
+    expect(readOperator(updated)).toEqual({ email: "ada@example.com", name: "Ada" });
+    expect(readLlm(updated)).toEqual({ provider: "anthropic" });
+    expect((updated.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
+  });
+
+  it("empty inputs leave the config unchanged (skip, not clear)", () => {
+    const cfg = config({ operator: { email: "keep@example.com" } });
+    const updated = applyOperatorIdentity(cfg, "", "");
+    expect(readOperator(updated)).toEqual({ email: "keep@example.com" });
+  });
+});

package/src/local/setup/wizard.ts

@@ -7,13 +7,19 @@
 // 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. 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).
+// menu, followed by the skippable operator-identity prompt (oss#796). 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";
-import { promptSecret } from "./prompt.js";
+import {
+  type OperatorSettings,
+  setOperator,
+  validateOperatorIdentity,
+} from "../operator-config.js";
+import { promptLine, promptSecret } from "./prompt.js";
 
 /**
  * The providers `stigmer setup` accepts. This is the single source of truth
@@ -47,25 +53,88 @@ export function applyChoice(config: Config, choice: ProviderChoice, inputs: Sele
   return setLlm(config, buildLlmForChoice(choice, inputs));
 }
 
+/**
+ * Resolve operator-identity inputs to the settings to persist, validating the
+ * way the server's boot check will (oss#796) — the pure decision core shared
+ * by the flag path and the interactive prompt, like buildLlmForChoice. An
+ * empty email with an empty name yields `undefined` (nothing to persist —
+ * identity stays whatever it was; the anonymous default is the absence of
+ * the section, not an empty one). Throws on inputs the server would refuse
+ * at boot, so the failure surfaces at setup time.
+ */
+export function buildOperatorForInputs(email: string, name: string): OperatorSettings | undefined {
+  const error = validateOperatorIdentity(email, name);
+  if (error !== undefined) {
+    throw new Error(error);
+  }
+  const trimmedEmail = email.trim();
+  if (trimmedEmail === "") return undefined;
+  const trimmedName = name.trim();
+  return trimmedName === "" ? { email: trimmedEmail } : { email: trimmedEmail, name: trimmedName };
+}
+
+/** Apply operator-identity inputs to a config, returning the updated copy. */
+export function applyOperatorIdentity(config: Config, email: string, name: string): Config {
+  const settings = buildOperatorForInputs(email, name);
+  return settings === undefined ? config : setOperator(config, settings);
+}
+
 /**
  * Run the interactive setup against the current terminal: one Anthropic
- * API-key prompt. A key already in the environment is used without prompting
- * (and never persisted — env precedence makes a copy redundant); an empty
- * entry is an explicit skip.
+ * API-key prompt, then the (skippable) operator-identity prompt. A key
+ * already in the environment is used without prompting (and never persisted —
+ * env precedence makes a copy redundant); an empty entry is an explicit skip.
  */
 export async function runInteractiveWizard(config: Config, env: NodeJS.ProcessEnv = process.env): Promise<Config> {
   process.stderr.write("\nStigmer runs local agents on Anthropic Claude models.\n");
   process.stderr.write("The model is chosen automatically from the platform model registry.\n\n");
 
+  let updated: Config;
   if (env.ANTHROPIC_API_KEY) {
     process.stderr.write("Using ANTHROPIC_API_KEY from environment\n");
-    return applyChoice(config, "anthropic");
+    updated = applyChoice(config, "anthropic");
+  } else {
+    const key = (await promptSecret("Enter your Anthropic API key (press Enter to skip)")).trim();
+    if (key === "") {
+      process.stderr.write("Skipped. Agents won't execute until a provider is configured (stigmer setup).\n");
+      updated = applyChoice(config, "skip");
+    } else {
+      updated = applyChoice(config, "anthropic", { apiKey: key });
+    }
+  }
+
+  return runOperatorIdentityStep(updated, env);
+}
+
+/**
+ * The operator-identity step (oss#796): opt-in, skippable, and env-aware in
+ * the same way the API-key step is — an env-provided identity is used without
+ * prompting and never persisted (env precedence makes a copy redundant). An
+ * invalid entry is refused and NOT persisted (re-run `stigmer setup`), the
+ * same rule the server enforces at boot, just earlier.
+ */
+async function runOperatorIdentityStep(config: Config, env: NodeJS.ProcessEnv): Promise<Config> {
+  process.stderr.write(
+    "\nAn operator identity attributes local creates to you and unlocks identity-gated MCP tools.\n",
+  );
+
+  if ((env.STIGMER_OPERATOR_EMAIL ?? "").trim() !== "") {
+    process.stderr.write("Using STIGMER_OPERATOR_EMAIL from environment\n");
+    return config;
+  }
+
+  const email = (await promptLine("Operator email (press Enter to skip): ")).trim();
+  if (email === "") {
+    return config;
   }
+  const name = (await promptLine("Operator display name (optional): ")).trim();
 
-  const key = (await promptSecret("Enter your Anthropic API key (press Enter to skip)")).trim();
-  if (key === "") {
-    process.stderr.write("Skipped. Agents won't execute until a provider is configured (stigmer setup).\n");
-    return applyChoice(config, "skip");
+  try {
+    return applyOperatorIdentity(config, email, name);
+  } catch (error) {
+    process.stderr.write(
+      `Not saved: ${error instanceof Error ? error.message : String(error)} — re-run stigmer setup.\n`,
+    );
+    return config;
   }
-  return applyChoice(config, "anthropic", { apiKey: key });
 }