@stigmer/cli 3.0.8

package/src/commands/logs.ts

@@ -0,0 +1,73 @@
+// `stigmer logs` — view daemon component logs, with `kubectl logs`-style
+// defaults: follow all components live, showing a tail snapshot first.
+//
+//   stigmer logs                       # follow all components
+//   stigmer logs --no-follow --tail 100
+//   stigmer logs --component runner    # just the runner
+
+import type { Command } from "commander";
+import { homedir } from "node:os";
+
+interface LogsFlags {
+  follow?: boolean; // false when --no-follow is passed
+  tail?: string;
+  component?: string;
+  all?: boolean; // false when --no-all is passed
+}
+
+export function registerLogs(program: Command): void {
+  program
+    .command("logs")
+    .description("view logs from the local Stigmer stack")
+    .option("-f, --no-follow", "do not stream new log lines (show the tail and exit)")
+    .option("-n, --tail <lines>", "number of recent lines to show before streaming", "50")
+    .option("-c, --component <name>", "show a single component (stigmer-server, runner, or temporal)")
+    .option("--no-all", "with --component unset, restrict to the default component")
+    .action((options: LogsFlags) => runLogs(options));
+}
+
+async function runLogs(options: LogsFlags): Promise<void> {
+  const { allComponents, componentByName, followAll, printTail } = await import("../local/logs/view.js");
+  const { logDir } = await import("../local/paths.js");
+  const { CliExitError } = await import("../errors/cli-exit-error.js");
+  const { ExitCode } = await import("../errors/exit-codes.js");
+
+  const dir = logDir(homedir());
+  const tail = Number.parseInt(options.tail ?? "50", 10);
+  const tailLines = Number.isNaN(tail) ? 50 : tail;
+  const follow = options.follow !== false;
+
+  // A single component is selected explicitly; otherwise show all unless the
+  // user opted out of the all-view (then fall back to the server's logs).
+  const useAll = options.component === undefined && options.all !== false;
+  const components = useAll
+    ? allComponents(dir)
+    : [
+        componentByName(dir, options.component ?? "stigmer-server") ??
+          (() => {
+            throw new CliExitError(`unknown component: ${options.component}`, ExitCode.Usage, [
+              "Valid components: stigmer-server, runner, temporal",
+            ]);
+          })(),
+      ];
+
+  printTail(components, tailLines, process.stdout);
+
+  if (!follow) return;
+  await streamUntilInterrupt(() => followAll(components, process.stdout));
+}
+
+// Follow until SIGINT, then stop cleanly. Resolves on Ctrl-C so the process can
+// exit 0 rather than dumping a stack trace.
+function streamUntilInterrupt(start: () => { stop(): void }): Promise<void> {
+  return new Promise((resolve) => {
+    const handle = start();
+    const onSignal = (): void => {
+      handle.stop();
+      process.removeListener("SIGINT", onSignal);
+      process.stderr.write("\n");
+      resolve();
+    };
+    process.on("SIGINT", onSignal);
+  });
+}

package/src/commands/mcp-server.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import type { Config } from "../config/config.js";
+import { applyConfigEnv, applyFlagsEnv } from "./mcp-server.js";
+
+describe("applyConfigEnv", () => {
+  it("points a local backend at the local server", () => {
+    const env: NodeJS.ProcessEnv = {};
+    applyConfigEnv({ backend: { type: "local" } }, env);
+    expect(env.STIGMER_SERVER_ADDRESS).toBe("localhost:7234");
+    expect(env.STIGMER_API_KEY).toBeUndefined();
+  });
+
+  it("contributes the cloud endpoint and token", () => {
+    const env: NodeJS.ProcessEnv = {};
+    const config: Config = {
+      backend: { type: "cloud", cloud: { endpoint: "api.stigmer.ai:443", token: "tok-123" } },
+    };
+    applyConfigEnv(config, env);
+    expect(env.STIGMER_SERVER_ADDRESS).toBe("api.stigmer.ai:443");
+    expect(env.STIGMER_API_KEY).toBe("tok-123");
+  });
+
+  it("never overrides a value already present in the environment", () => {
+    const env: NodeJS.ProcessEnv = { STIGMER_SERVER_ADDRESS: "preset:7234" };
+    applyConfigEnv({ backend: { type: "local" } }, env);
+    expect(env.STIGMER_SERVER_ADDRESS).toBe("preset:7234");
+  });
+});
+
+describe("applyFlagsEnv", () => {
+  it("maps every set flag to its environment variable", () => {
+    const env: NodeJS.ProcessEnv = {};
+    applyFlagsEnv(
+      {
+        transport: "http",
+        port: "9090",
+        serverAddress: "host:7234",
+        apiKey: "key",
+        logFormat: "json",
+        logLevel: "debug",
+      },
+      env,
+    );
+    expect(env).toMatchObject({
+      STIGMER_MCP_TRANSPORT: "http",
+      STIGMER_MCP_HTTP_PORT: "9090",
+      STIGMER_SERVER_ADDRESS: "host:7234",
+      STIGMER_API_KEY: "key",
+      STIGMER_MCP_LOG_FORMAT: "json",
+      STIGMER_MCP_LOG_LEVEL: "debug",
+    });
+  });
+
+  it("overrides config-derived values (flags win)", () => {
+    const env: NodeJS.ProcessEnv = { STIGMER_SERVER_ADDRESS: "from-config:7234" };
+    applyFlagsEnv({ serverAddress: "from-flag:7234" }, env);
+    expect(env.STIGMER_SERVER_ADDRESS).toBe("from-flag:7234");
+  });
+
+  it("ignores unset flags", () => {
+    const env: NodeJS.ProcessEnv = {};
+    applyFlagsEnv({}, env);
+    expect(Object.keys(env)).toHaveLength(0);
+  });
+});

package/src/commands/mcp-server.ts

@@ -0,0 +1,124 @@
+// `stigmer mcp-server` — start the Stigmer MCP server.
+//
+// The server is the TypeScript `@stigmer/mcp-server` package, and the CLI runs it
+// IN-PROCESS via its `run(cfg, signal)` embed API — the module exists precisely
+// so a host like the CLI embeds it rather than shelling out (the Go CLI shelled
+// out only because Go cannot import TypeScript). This avoids a child process, an
+// npx/tsx resolution dance, and a second Node startup.
+//
+// MCP clients (Cursor, Claude Desktop, Windsurf) spawn `stigmer mcp-server` and
+// speak the protocol over stdio, so stdout must carry ONLY MCP frames: the CLI's
+// logger writes to stderr (see logger.ts) and the server logs to stderr too. The
+// CLI owns the shutdown signal and aborts the server's AbortController on
+// SIGINT/SIGTERM.
+//
+// Configuration precedence (matches the Go CLI): flags > env > ~/.stigmer config
+// > server defaults. We realize that precedence by bridging config into the
+// environment only where unset, then letting explicit flags override, and finally
+// letting the server read its Config from the environment.
+
+import type { Command } from "commander";
+import type { Config } from "../config/config.js";
+
+/** Flags the command bridges into the server's environment. */
+export interface McpServerFlags {
+  transport?: string;
+  port?: string;
+  serverAddress?: string;
+  apiKey?: string;
+  logFormat?: string;
+  logLevel?: string;
+}
+
+const HELP_AFTER = `
+Environment variables:
+  STIGMER_SERVER_ADDRESS         gRPC address (default: CLI config, else localhost:7234)
+  STIGMER_API_KEY                API key (auto-resolved from CLI config for cloud)
+  STIGMER_MCP_TRANSPORT          stdio | http | both (default: stdio)
+  STIGMER_MCP_HTTP_PORT          HTTP listen port (default: 8080)
+  STIGMER_MCP_LOG_FORMAT         text | json (default: text)
+  STIGMER_MCP_LOG_LEVEL          debug | info | warn | error (default: info)
+
+Examples:
+  # STDIO mode (default — what MCP clients spawn)
+  $ stigmer mcp-server
+
+  # HTTP mode on a custom port
+  $ stigmer mcp-server --transport http --port 9090
+
+  # Cursor mcp.json:
+  # { "command": "stigmer", "args": ["mcp-server"] }`;
+
+export function registerMcpServer(program: Command): void {
+  program
+    .command("mcp-server")
+    .description("start the MCP server that exposes Stigmer resources to AI coding assistants")
+    .option("--transport <mode>", "transport mode: stdio, http, or both (env: STIGMER_MCP_TRANSPORT)")
+    .option("--port <port>", "HTTP listen port (env: STIGMER_MCP_HTTP_PORT)")
+    .option("--server-address <addr>", "gRPC address of stigmer-server (env: STIGMER_SERVER_ADDRESS)")
+    .option("--api-key <key>", "API key for stigmer-server (env: STIGMER_API_KEY)")
+    .option("--log-format <fmt>", "log encoding: text or json (env: STIGMER_MCP_LOG_FORMAT)")
+    .option("--log-level <level>", "minimum log level: debug, info, warn, or error (env: STIGMER_MCP_LOG_LEVEL)")
+    .addHelpText("after", HELP_AFTER)
+    .action((flags: McpServerFlags) => runMcpServer(flags));
+}
+
+async function runMcpServer(flags: McpServerFlags): Promise<void> {
+  const { load } = await import("../config/config.js");
+  applyConfigEnv(load(), process.env);
+  applyFlagsEnv(flags, process.env);
+
+  // Imported lazily so `stigmer --help`/`version` never pull in the MCP stack.
+  const { run, defaultConfig } = await import("@stigmer/mcp-server");
+
+  const controller = new AbortController();
+  const onSignal = (): void => controller.abort();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  try {
+    await run(defaultConfig(), controller.signal);
+  } finally {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  }
+}
+
+/**
+ * Bridge CLI config into the server's environment, but only where unset, so a
+ * pre-existing environment variable (or a flag bridged before this) wins. Local
+ * backends connect to the local server without auth; cloud backends contribute
+ * the stored endpoint and token.
+ */
+export function applyConfigEnv(config: Config, env: NodeJS.ProcessEnv): void {
+  if (config.backend.type === "local") {
+    setIfEmpty(env, "STIGMER_SERVER_ADDRESS", "localhost:7234");
+    return;
+  }
+  const cloud = config.backend.cloud;
+  if (cloud !== undefined) {
+    setIfEmpty(env, "STIGMER_SERVER_ADDRESS", cloud.endpoint);
+    setIfEmpty(env, "STIGMER_API_KEY", cloud.token);
+  }
+}
+
+/** Bridge explicitly-set flags into the server's environment (highest precedence). */
+export function applyFlagsEnv(flags: McpServerFlags, env: NodeJS.ProcessEnv): void {
+  setIfPresent(env, "STIGMER_MCP_TRANSPORT", flags.transport);
+  setIfPresent(env, "STIGMER_MCP_HTTP_PORT", flags.port);
+  setIfPresent(env, "STIGMER_SERVER_ADDRESS", flags.serverAddress);
+  setIfPresent(env, "STIGMER_API_KEY", flags.apiKey);
+  setIfPresent(env, "STIGMER_MCP_LOG_FORMAT", flags.logFormat);
+  setIfPresent(env, "STIGMER_MCP_LOG_LEVEL", flags.logLevel);
+}
+
+function setIfEmpty(env: NodeJS.ProcessEnv, key: string, value: string | undefined): void {
+  if (value !== undefined && value !== "" && (env[key] === undefined || env[key] === "")) {
+    env[key] = value;
+  }
+}
+
+function setIfPresent(env: NodeJS.ProcessEnv, key: string, value: string | undefined): void {
+  if (value !== undefined && value !== "") {
+    env[key] = value;
+  }
+}

package/src/commands/push.ts

@@ -0,0 +1,205 @@
+// `stigmer push <type> [path]` — package and upload an artifact to the registry.
+// Only skills are pushable today. Two source modes: a local directory (default,
+// git provenance auto-detected) or a remote repo via --git-url (cloned to a
+// temp dir, then pushed). Heavy modules are lazy-imported so `--help` stays fast.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { defaultRegistry, Verb } from "../registry/index.js";
+import { globalOrg } from "./shared.js";
+
+interface PushFlags {
+  tag?: string;
+  message?: string;
+  dryRun?: boolean;
+  gitUrl?: string;
+  gitRef?: string;
+  subdir?: string;
+  ignore?: string[];
+  include?: string[];
+  gitignore?: boolean; // false when --no-gitignore is passed (commander negation)
+  verbose?: boolean;
+}
+
+const collect = (value: string, previous: string[]): string[] => [...previous, value];
+
+export function registerPush(program: Command): void {
+  program
+    .command("push <type> [path]")
+    .description("push an artifact to the registry (supported types: skill)")
+    .option("--tag <tag>", "version tag for the artifact", "latest")
+    .option("-m, --message <message>", "version message describing what changed")
+    .option("--dry-run", "validate without pushing")
+    .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("--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")
+    .option("--verbose", "show detailed output including ignore decisions")
+    .action((type: string, path: string | undefined, options: PushFlags, command: Command) =>
+      runPush(type, path, options, command),
+    );
+}
+
+async function runPush(type: string, path: string | undefined, options: PushFlags, command: Command): Promise<void> {
+  const info = defaultRegistry().getByAlias(type);
+  if (info === undefined) {
+    throw new UsageError(`unknown resource type: ${type}\n\nAvailable types: skill`);
+  }
+  if (!info.supportedVerbs.has(Verb.Push)) {
+    throw new UsageError(`${info.displayName} does not support 'push'`);
+  }
+  if (info.kind !== ApiResourceKind.skill) {
+    throw new UsageError(`push not implemented for ${info.displayName}`);
+  }
+
+  const [{ connectBackend }, skill] = await Promise.all([import("../backend.js"), import("../resources/skill.js")]);
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+
+  const ignoreOptions = {
+    respectGitignore: options.gitignore !== false,
+    extraIgnore: options.ignore ?? [],
+    extraInclude: options.include ?? [],
+  };
+  const decisionSink = options.verbose === true ? (line: string) => process.stderr.write(`${line}\n`) : undefined;
+  const tag = options.tag ?? "latest";
+  const message = options.message ?? "";
+
+  if (options.gitUrl !== undefined && options.gitUrl !== "") {
+    await pushRemote(client.stigmer, skill, { org, tag, message, ignoreOptions, decisionSink, options });
+    return;
+  }
+
+  const directory = path !== undefined && path !== "" ? path : process.cwd();
+  if (!skill.hasSkillFile(directory)) {
+    throw new UsageError(
+      `SKILL.md not found in ${directory}\n\nA skill directory must contain a SKILL.md file defining the skill interface`,
+    );
+  }
+  // Validate metadata early so dry-run and real pushes fail the same way.
+  skill.parseSkillMetadata(directory);
+
+  if (options.dryRun === true) {
+    process.stdout.write(renderDryRun(directory, skill.analyzeDryRun(directory, ignoreOptions), skill));
+    return;
+  }
+
+  const result = await skill.pushSkill(client.stigmer, directory, org, tag, message, ignoreOptions, decisionSink);
+  process.stdout.write(renderResult(result, skill));
+}
+
+interface RemoteContext {
+  org: string;
+  tag: string;
+  message: string;
+  ignoreOptions: { respectGitignore: boolean; extraIgnore: string[]; extraInclude: string[] };
+  decisionSink?: (line: string) => void;
+  options: PushFlags;
+}
+
+async function pushRemote(
+  client: import("@stigmer/sdk").Stigmer,
+  skill: typeof import("../resources/skill.js"),
+  ctx: RemoteContext,
+): Promise<void> {
+  const gitUrl = ctx.options.gitUrl ?? "";
+  const gitRef = ctx.options.gitRef ?? "";
+  const subdir = ctx.options.subdir ?? "";
+
+  if (ctx.options.dryRun === true) {
+    process.stdout.write(renderRemoteDryRun(gitUrl, gitRef, subdir, ctx));
+    return;
+  }
+
+  const { cloneRepository } = await import("../resources/git.js");
+  const tempDir = mkdtempSync(join(tmpdir(), "stigmer-skill-"));
+  try {
+    cloneRepository(gitUrl, gitRef, tempDir);
+    const skillDir = subdir !== "" ? join(tempDir, subdir) : tempDir;
+    if (!skill.hasSkillFile(skillDir)) {
+      throw new UsageError(
+        `SKILL.md not found in ${subdir !== "" ? subdir : "repository root"}\n\n` +
+          "The skill directory must contain a SKILL.md file with YAML frontmatter",
+      );
+    }
+    const result = await skill.pushSkillFromClone(
+      client,
+      skillDir,
+      { gitUrl, gitRef, subdir, org: ctx.org, tag: ctx.tag, message: ctx.message, options: ctx.ignoreOptions },
+      ctx.decisionSink,
+    );
+    process.stdout.write(renderResult(result, skill));
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function renderResult(result: import("../resources/skill.js").PushResult, skill: typeof import("../resources/skill.js")): string {
+  const status = result.isNewResource ? "new resource" : result.versionChanged ? "new version" : "unchanged";
+  const lines = [
+    "",
+    `Pushed skill '${result.skillName}'`,
+    `  ID:       ${result.id}`,
+    `  Slug:     ${result.slug}`,
+    `  Tag:      ${result.tag}`,
+    `  Version:  ${skill.shortHash(result.versionHash)}`,
+    `  Size:     ${skill.formatBytes(result.artifactSize)}`,
+    `  Status:   ${status}`,
+  ];
+  if (result.message !== "") lines.push(`  Message:  ${result.message}`);
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderDryRun(
+  directory: string,
+  analysis: import("../resources/skill.js").DryRunAnalysis,
+  skill: typeof import("../resources/skill.js"),
+): string {
+  const { stats } = analysis;
+  const lines = [
+    "",
+    `Dry run - analyzing skill directory: ${directory}`,
+    "",
+    "Pattern sources:",
+    ...analysis.patternSources.map((s) => `  - ${s}`),
+    "",
+    `Files to include:    ${stats.filesIncluded} (${skill.formatBytes(stats.totalSize)})`,
+    `Files ignored:       ${stats.filesIgnored}`,
+    `Directories skipped: ${stats.dirsSkipped}`,
+  ];
+  if (analysis.sampleIncluded.length > 0) {
+    lines.push("", "Sample included:", ...analysis.sampleIncluded.map((f) => `  + ${f}`));
+  }
+  if (analysis.sampleIgnored.length > 0) {
+    lines.push("", "Sample ignored:", ...analysis.sampleIgnored.map((f) => `  - ${f}`));
+  }
+  lines.push("", "Run without --dry-run to push the skill artifact.", "");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderRemoteDryRun(gitUrl: string, gitRef: string, subdir: string, ctx: RemoteContext): string {
+  const lines = ["", "Dry run mode - would push skill from remote git repository:", "", "Git Source:", `  URL:    ${gitUrl}`];
+  if (gitRef !== "") lines.push(`  Ref:    ${gitRef}`);
+  if (subdir !== "") lines.push(`  Subdir: ${subdir}`);
+  lines.push(`  Tag:    ${ctx.tag}`, "", "Ignore Configuration:");
+  lines.push(`  Gitignore:         ${ctx.ignoreOptions.respectGitignore ? "enabled" : "disabled"}`);
+  lines.push("  Security defaults: enabled");
+  lines.push("  Stigmerignore:     will load if present");
+  if (ctx.ignoreOptions.extraIgnore.length > 0) lines.push(`  Extra ignore:      ${ctx.ignoreOptions.extraIgnore.join(", ")}`);
+  if (ctx.ignoreOptions.extraInclude.length > 0) lines.push(`  Force include:     ${ctx.ignoreOptions.extraInclude.join(", ")}`);
+  lines.push(
+    "",
+    "Note: Full analysis requires cloning the repository.",
+    "Run without --dry-run to push the skill artifact.",
+    "",
+  );
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/reset.ts

@@ -0,0 +1,57 @@
+// `stigmer reset` — stop the stack and wipe all persistent local state, then
+// (unless config was removed) restart fresh. Destructive, so it confirms first
+// unless `--force` is given. Configuration is preserved unless --include-config.
+
+import type { Command } from "commander";
+import { homedir } from "node:os";
+import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+interface ResetFlags extends OutputFlags {
+  force?: boolean;
+  includeConfig?: boolean;
+}
+
+export function registerReset(program: Command): void {
+  const reset = program
+    .command("reset")
+    .description("stop the stack and remove all local state, then restart fresh")
+    .option("--force", "skip the confirmation prompt")
+    .option("--include-config", "also remove configuration (API keys, preferences)")
+    .action((options: ResetFlags) => runReset(options));
+  addResultFlags(reset);
+}
+
+async function runReset(options: ResetFlags): Promise<void> {
+  const { reset } = await import("../local/reset.js");
+  const { up } = await import("../local/daemon/launch.js");
+  const { confirm } = await import("../local/setup/prompt.js");
+  const { configDir } = await import("../local/paths.js");
+
+  if (options.force !== true) {
+    const scope = options.includeConfig === true ? " INCLUDING configuration (config.yaml)" : " (configuration preserved)";
+    const ok = await confirm(`This will remove all runtime data in ${configDir(homedir())}${scope}.\nContinue?`);
+    if (!ok) {
+      renderResult(CommandResult.warning("Reset cancelled"), resultFormat(options));
+      return;
+    }
+  }
+
+  const outcome = await reset({ includeConfig: options.includeConfig === true });
+
+  const result = CommandResult.success("Reset complete");
+  const removed = result.addSection("Removed");
+  if (outcome.servicesStopped) removed.item("services stopped");
+  for (const path of outcome.removedPaths) removed.item(path);
+
+  if (options.includeConfig === true) {
+    result.hint("Run 'stigmer up' to reconfigure and start fresh");
+    renderResult(result, resultFormat(options));
+    return;
+  }
+
+  renderResult(result, resultFormat(options));
+
+  process.stderr.write("\nRestarting Stigmer local stack…\n");
+  await up({}, homedir());
+}

package/src/commands/resume.ts

@@ -0,0 +1,121 @@
+// `stigmer resume [session-id-or-text]` — re-open an existing session. Thin
+// handler: classify the argument (Go's executeResumeSmart), then delegate to the
+// resume orchestrator. Resource IDs that aren't sessions are redirected to `run`;
+// text/0-arg would open the session picker (a separate, not-yet-wired task).
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import { interactiveBrowseEnabled } from "../resources/picker/tty.js";
+import { globalOrg } from "./shared.js";
+
+interface ResumeFlags {
+  verbose?: boolean;
+  mode?: string;
+  json?: boolean;
+}
+
+export function registerResume(program: Command): void {
+  program
+    .command("resume [reference]")
+    .description("resume an existing session by ID")
+    .option("-v, --verbose", "show all execution events")
+    .option("--mode <mode>", 'follow-up interaction mode: "agent" (default) or "plan" (read-only)')
+    .option("--json", "stream events as newline-delimited JSON")
+    .action((reference: string | undefined, options: ResumeFlags, command: Command) =>
+      runResume(reference, options, command),
+    );
+}
+
+async function runResume(reference: string | undefined, options: ResumeFlags, command: Command): Promise<void> {
+  const { validateMode } = await import("../resources/run/prepare.js");
+  // Call through a plain signature: TS forbids assertion functions reached via a
+  // destructured dynamic-import binding (TS2775); we only need the throw-on-invalid
+  // side effect here, not the narrowing.
+  (validateMode as (mode: string) => void)(options.mode ?? "");
+
+  const { connectBackend } = await import("../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+  if (org === "") {
+    throw new UsageError(
+      "organization not set\n\nSet it with:\n  stigmer config context set --org <org>\n  stigmer resume --org <org> ...",
+    );
+  }
+
+  const outputMode = options.json === true ? "json" : "inline";
+  const mode = (options.mode ?? "") as import("../resources/run/prepare.js").RunMode;
+
+  if (reference === undefined) {
+    if (interactiveBrowseEnabled(outputMode)) {
+      await browseAndResumeSession("", client, org, mode, outputMode);
+      return;
+    }
+    throw browseUnavailableError();
+  }
+
+  const { isSessionId, isAgentId, isWorkflowId, hasResourceIdPrefix, validateResourceId } = await import(
+    "../resources/reference.js"
+  );
+
+  // Agent/workflow IDs belong to `run`.
+  if (isAgentId(reference) || isWorkflowId(reference)) {
+    throw new UsageError(`Resource IDs like "${reference}" are not sessions\n\nTo run a resource:\n  stigmer run ${reference}`);
+  }
+
+  if (isSessionId(reference)) {
+    if (validateResourceId(reference) !== null) {
+      throw new UsageError(
+        `Incomplete session ID: ${reference}\n\nProvide the full session ID (e.g. ses_01abc123xyz456789012345678)`,
+      );
+    }
+    const { openSession } = await import("../resources/run/resume.js");
+    await openSession({ client, sessionId: reference, org, mode, outputMode });
+    return;
+  }
+
+  // Any other resource-ID prefix is not a session.
+  if (hasResourceIdPrefix(reference)) {
+    throw new UsageError(
+      `Resource IDs like "${reference}" are not sessions\n\n` +
+        "To resume a session, provide a session ID (ses_…) or search text:\n" +
+        "  stigmer resume <session-id>",
+    );
+  }
+
+  // Bare text → interactive session picker (pre-filtered by the text) on a TTY;
+  // otherwise actionable guidance.
+  if (interactiveBrowseEnabled(outputMode)) {
+    await browseAndResumeSession(reference, client, org, mode, outputMode);
+    return;
+  }
+  throw browseUnavailableError(reference);
+}
+
+// Mount the session picker; on selection, re-open the chosen session through the
+// existing resume orchestrator. Cancel (Esc/Ctrl+C → undefined) returns cleanly
+// so the command exits 0. Loaded lazily to honor the DD-001 boundary.
+async function browseAndResumeSession(
+  initialQuery: string,
+  client: import("../client/index.js").BackendClient,
+  org: string,
+  mode: import("../resources/run/prepare.js").RunMode,
+  outputMode: "inline" | "json",
+): Promise<void> {
+  const { pickSession } = await import("../resources/picker/ink.js");
+  const selected = await pickSession({ client: client.stigmer, initialQuery });
+  if (selected === undefined) return;
+  const sessionId = selected.metadata?.id ?? "";
+  if (sessionId === "") return;
+  const { openSession } = await import("../resources/run/resume.js");
+  await openSession({ client, sessionId, org, mode, outputMode });
+}
+
+function browseUnavailableError(query?: string): UsageError {
+  const head =
+    query === undefined || query === ""
+      ? "Interactive session browsing requires an interactive terminal"
+      : `Searching sessions for "${query}" requires an interactive terminal`;
+  return new UsageError(`${head}\n\nSpecify a full session ID:\n  stigmer resume <session-id>`);
+}