@stigmer/cli 3.14.1 → 3.15.1

package/src/commands/auth/whoami.test.ts

@@ -0,0 +1,96 @@
+// Unit tests for `stigmer auth whoami`'s result (commands/auth/whoami.ts;
+// 20260911.11 A3): the command runs the SDK's ensureMyIdentityAccount — the
+// same first-sign-in flow the console runs — and RENDERS what it learned.
+// whoamiResult is the pure half: given the account and whether this call
+// created it, the CommandResult a person reads. A first sign-in says so
+// (visibility of system status); a missing organization is a hint, not a
+// failure; an empty profile (the unconfigured laptop's operator) renders
+// only the fields it has. Accounts are built with the generated schema
+// (DD-007: the generated type is the contract; refinement 12, slice 4).
+
+import { create } from "@bufbuild/protobuf";
+import { IdentityAccountSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { describe, expect, it } from "vitest";
+
+import { whoamiResult } from "./whoami.js";
+
+const ALICE = {
+  metadata: { id: "ida_wtr3jcf281yfk9xx61kj59fsme", name: "alice@example.com" },
+  spec: {
+    idpId: "auth0|alice",
+    email: "alice@example.com",
+    firstName: "Alice",
+    lastName: "Liddell",
+    isMachineAccount: false,
+  },
+};
+const ACCOUNT = create(IdentityAccountSchema, ALICE);
+
+function fields(
+  result: ReturnType<typeof whoamiResult>,
+): Record<string, string> {
+  return Object.fromEntries(
+    result.sections.flatMap((s) => s.fields.map((f) => [f.key, f.value])),
+  );
+}
+
+describe("whoamiResult", () => {
+  it("renders an existing account as 'Authenticated' with its identity fields", () => {
+    const result = whoamiResult(ACCOUNT, { created: false, org: "acme" });
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("Authenticated");
+    expect(fields(result)).toEqual({
+      "Account ID": "ida_wtr3jcf281yfk9xx61kj59fsme",
+      Name: "alice@example.com",
+      Email: "alice@example.com",
+      "Full Name": "Alice Liddell",
+      "Account Type": "User Account",
+      Organization: "acme",
+    });
+    expect(result.hints).toEqual([]);
+  });
+
+  it("says so when this call created the account — the first sign-in is visible, never silent", () => {
+    const result = whoamiResult(ACCOUNT, { created: true, org: "acme" });
+    expect(result.status).toBe("success");
+    expect(result.message).toBe(
+      "Authenticated — your account was created on this first sign-in",
+    );
+    expect(fields(result)["Account ID"]).toBe("ida_wtr3jcf281yfk9xx61kj59fsme");
+  });
+
+  it("a missing organization is a hint with the command that sets it", () => {
+    const result = whoamiResult(ACCOUNT, { created: false, org: "" });
+    expect(fields(result).Organization).toBeUndefined();
+    expect(result.hints).toEqual([
+      "No organization set. Use: stigmer config context set --org <slug>",
+    ]);
+  });
+
+  it("renders only the fields an empty profile has (the unconfigured laptop's operator)", () => {
+    const result = whoamiResult(
+      create(IdentityAccountSchema, {
+        metadata: { id: "ida_fn0zdvkkkhhrb4wry43zba8gnn", name: "system" },
+        spec: { idpId: "local|system" },
+      }),
+      { created: false, org: "local" },
+    );
+    expect(fields(result)).toEqual({
+      "Account ID": "ida_fn0zdvkkkhhrb4wry43zba8gnn",
+      Name: "system",
+      "Account Type": "User Account",
+      Organization: "local",
+    });
+  });
+
+  it("names a machine account", () => {
+    const result = whoamiResult(
+      create(IdentityAccountSchema, {
+        ...ALICE,
+        spec: { ...ALICE.spec, isMachineAccount: true },
+      }),
+      { created: false, org: "acme" },
+    );
+    expect(fields(result)["Account Type"]).toBe("Machine Account");
+  });
+});

package/src/commands/auth/whoami.ts

@@ -0,0 +1,87 @@
+// `stigmer auth whoami` — who the connected server says you are.
+//
+// Runs the SDK's ensureMyIdentityAccount, the same first-sign-in flow the
+// console's gate runs (20260911.11 A3): an authenticated caller with no
+// account yet is provisioned here rather than told "not found", so a person
+// who only ever uses the CLI is never left without an account. The result
+// says when THIS call created it — a first sign-in is visible, never silent.
+//
+// whoamiResult is the pure half (given the account and what the call learned,
+// the CommandResult a person reads); runWhoami is the I/O half.
+
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { ensureMyIdentityAccount } from "@stigmer/sdk";
+import {
+  ensureAuthenticated,
+  resolveContextOrganization,
+} from "../../config/index.js";
+import { CommandResult } from "../../output/index.js";
+
+/** What the call learned beyond the account itself. */
+export interface WhoamiContext {
+  /** `true` when this call created the account (a first sign-in). */
+  readonly created: boolean;
+  /** The organization the CLI context resolves to; "" when none is set. */
+  readonly org: string;
+}
+
+/**
+ * Render the caller's account. Every field is optional on the wire and an
+ * empty profile (the unconfigured laptop's operator) renders only what it
+ * has; a missing organization is a hint with the command that sets it, not a
+ * failure.
+ */
+export function whoamiResult(
+  account: IdentityAccount,
+  context: WhoamiContext,
+): CommandResult {
+  const result = CommandResult.success(
+    context.created
+      ? "Authenticated — your account was created on this first sign-in"
+      : "Authenticated",
+  );
+  const section = result.addSection("");
+
+  if (account.metadata !== undefined) {
+    section.field("Account ID", account.metadata.id);
+    if (account.metadata.name !== "")
+      section.field("Name", account.metadata.name);
+  }
+  if (account.spec !== undefined) {
+    if (account.spec.email !== "") section.field("Email", account.spec.email);
+    if (account.spec.firstName !== "" || account.spec.lastName !== "") {
+      section.field(
+        "Full Name",
+        `${account.spec.firstName} ${account.spec.lastName}`.trim(),
+      );
+    }
+    section.field(
+      "Account Type",
+      account.spec.isMachineAccount ? "Machine Account" : "User Account",
+    );
+  }
+
+  if (context.org !== "") {
+    section.field("Organization", context.org);
+  } else {
+    result.hint(
+      "No organization set. Use: stigmer config context set --org <slug>",
+    );
+  }
+
+  return result;
+}
+
+export async function runWhoami(): Promise<CommandResult> {
+  const { connectBackend } = await import("../../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const { account, created } = await ensureMyIdentityAccount(client.stigmer, {
+    onProvisioning: () => process.stderr.write("Setting up your account...\n"),
+  });
+  return whoamiResult(account, {
+    created,
+    org: resolveContextOrganization(client.config),
+  });
+}

package/src/commands/draft.ts

@@ -8,9 +8,14 @@
 // unless detached or a local workspace is in play.
 
 import type { Command } from "commander";
-import { ensureAuthenticated, isCloudMode, resolveOrganization } from "../config/index.js";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
 import { UsageError } from "../errors/index.js";
-import { addAgentExecFlags, type AgentExecOptions, toAgentExecFlags } from "./agent-exec-flags.js";
+import {
+  addAgentExecFlags,
+  type AgentExecOptions,
+  toAgentExecFlags,
+} from "./agent-exec-flags.js";
 import { globalOrg } from "./shared.js";
 
 // The org that owns the system agent blueprints (installed by the seedpack),
@@ -31,9 +36,21 @@ interface DraftConfig {
 }
 
 const CONFIGS: readonly DraftConfig[] = [
-  { name: "skill", resourceType: "Skill", summary: "create a skill with AI assistance" },
-  { name: "agent", resourceType: "Agent", summary: "create an agent with AI assistance" },
-  { name: "mcp-server", resourceType: "McpServer", summary: "create an MCP server config with AI assistance" },
+  {
+    name: "skill",
+    resourceType: "Skill",
+    summary: "create a skill with AI assistance",
+  },
+  {
+    name: "agent",
+    resourceType: "Agent",
+    summary: "create an agent with AI assistance",
+  },
+  {
+    name: "mcp-server",
+    resourceType: "McpServer",
+    summary: "create an MCP server config with AI assistance",
+  },
 ];
 
 // System agent slug per subcommand (Go's draftConfig.AgentName: "<type>-creator").
@@ -42,17 +59,28 @@ function agentSlug(name: string): string {
 }
 
 export function registerDraft(program: Command): void {
-  const draft = program.command("draft").description("create resource configurations with AI assistance");
+  const draft = program
+    .command("draft")
+    .description("create resource configurations with AI assistance");
   for (const config of CONFIGS) {
     const sub = draft.command(config.name).description(config.summary);
     addAgentExecFlags(sub, true)
-      .option("-o, --output <dir>", "directory to save generated artifacts (default: current directory)")
+      .option(
+        "-o, --output <dir>",
+        "directory to save generated artifacts (default: current directory)",
+      )
       .option("--json", "stream events as newline-delimited JSON")
-      .action((options: DraftFlags, command: Command) => runDraft(config, options, command));
+      .action((options: DraftFlags, command: Command) =>
+        runDraft(config, options, command),
+      );
   }
 }
 
-async function runDraft(config: DraftConfig, options: DraftFlags, command: Command): Promise<void> {
+async function runDraft(
+  config: DraftConfig,
+  options: DraftFlags,
+  command: Command,
+): Promise<void> {
   const { connectBackend } = await import("../backend.js");
   const client = connectBackend();
   ensureAuthenticated(client.config);
@@ -63,29 +91,52 @@ async function runDraft(config: DraftConfig, options: DraftFlags, command: Comma
     );
   }
 
-  const [{ prepareAgentExec }, { executeResolvedAgent }, { resolveAgentRef }, { localWorkspaceRoots }] =
-    await Promise.all([
-      import("../resources/run/prepare.js"),
-      import("../resources/run/agent-exec.js"),
-      import("../resources/run/resolve.js"),
-      import("../resources/run/workspace.js"),
-    ]);
-
-  const agent = await resolveDraftAgent(resolveAgentRef, client.stigmer, config);
-
-  const prepared = await prepareAgentExec(toAgentExecFlags(options), client.stigmer, org, stderrProgress(), {
-    cloudBackend: isCloudMode(client.config),
-  });
+  const [
+    { prepareAgentExec },
+    { executeResolvedAgent },
+    { resolveAgentRef },
+    { localWorkspaceRoots },
+  ] = await Promise.all([
+    import("../resources/run/prepare.js"),
+    import("../resources/run/agent-exec.js"),
+    import("../resources/run/resolve.js"),
+    import("../resources/run/workspace.js"),
+  ]);
+
+  const agent = await resolveDraftAgent(
+    resolveAgentRef,
+    client.stigmer,
+    config,
+  );
+
+  const prepared = await prepareAgentExec(
+    toAgentExecFlags(options),
+    client.stigmer,
+    org,
+    stderrProgress(),
+    {
+      // The kind's tier against the server's reported edition, as `run` asks it.
+      accountPreferencesAvailable: await client.isResourceAvailable(
+        ApiResourceKind.identity_account,
+      ),
+    },
+  );
 
   if (prepared.attachments.length + prepared.workspaceFileRefs.length > 0) {
-    process.stderr.write(`Attached ${prepared.attachments.length + prepared.workspaceFileRefs.length} file(s) as context\n`);
+    process.stderr.write(
+      `Attached ${prepared.attachments.length + prepared.workspaceFileRefs.length} file(s) as context\n`,
+    );
   }
 
   await executeResolvedAgent({
     agent,
     prepared,
     org,
-    downloadDir: resolveDownloadDir(options.output ?? "", prepared.detach, localWorkspaceRoots(prepared.workspaceEntries)),
+    downloadDir: resolveDownloadDir(
+      options.output ?? "",
+      prepared.detach,
+      localWorkspaceRoots(prepared.workspaceEntries),
+    ),
     outputMode: options.json === true ? "json" : "inline",
     client,
   });
@@ -100,7 +151,11 @@ async function resolveDraftAgent(
 ): Promise<import("@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb").Agent> {
   const slug = agentSlug(config.name);
   try {
-    return await resolveAgentRef(client, `${SYSTEM_AGENT_ORG}/${slug}`, SYSTEM_AGENT_ORG);
+    return await resolveAgentRef(
+      client,
+      `${SYSTEM_AGENT_ORG}/${slug}`,
+      SYSTEM_AGENT_ORG,
+    );
   } catch {
     throw new UsageError(
       `${slug} agent not found in organization "${SYSTEM_AGENT_ORG}"\n\n` +
@@ -117,7 +172,11 @@ async function resolveDraftAgent(
 //   explicit -o     → that directory
 //   local workspace → skip (the agent writes directly to disk)
 //   otherwise       → current directory
-function resolveDownloadDir(output: string, detach: boolean, localRoots: readonly string[]): string {
+function resolveDownloadDir(
+  output: string,
+  detach: boolean,
+  localRoots: readonly string[],
+): string {
   if (detach) return "";
   if (output !== "") return output;
   if (localRoots.length > 0) return "";

package/src/commands/internal-daemon.ts

@@ -1,6 +1,7 @@
 // `stigmer internal-daemon` (hidden) — the long-lived supervised daemon process
 // that `up` re-execs. It is not meant to be invoked directly; it runs the local
 // stack until it receives SIGTERM/SIGINT, then exits with the daemon's code.
+// (`stigmer up --foreground` runs the same body in the launching process.)
 
 import type { Command } from "commander";
 
@@ -9,17 +10,8 @@ export function registerInternalDaemon(program: Command): void {
     .command("internal-daemon", { hidden: true })
     .description("internal: run the supervised local-stack daemon (do not invoke directly)")
     .action(async () => {
-      const { runInternalDaemon } = await import("../local/daemon/process.js");
+      const { runInternalDaemon, waitForShutdownSignal } = await import("../local/daemon/process.js");
       const code = await runInternalDaemon({ waitForShutdown: waitForShutdownSignal });
       process.exit(code);
     });
 }
-
-// Resolve when the first SIGTERM/SIGINT arrives — the daemon's shutdown trigger.
-function waitForShutdownSignal(): Promise<void> {
-  return new Promise((resolve) => {
-    const onSignal = (): void => resolve();
-    process.once("SIGTERM", onSignal);
-    process.once("SIGINT", onSignal);
-  });
-}

package/src/commands/run.ts

@@ -5,10 +5,14 @@
 // the differ) load lazily inside the action so `--help` stays fast (DD-001).
 
 import type { Command } from "commander";
-import { ensureAuthenticated, isCloudMode, resolveOrganization } from "../config/index.js";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
 import { UsageError } from "../errors/index.js";
 import { interactiveBrowseEnabled } from "../resources/picker/tty.js";
-import { addAgentExecFlags, type AgentExecOptions } from "./agent-exec-flags.js";
+import {
+  addAgentExecFlags,
+  type AgentExecOptions,
+} from "./agent-exec-flags.js";
 import { globalOrg } from "./shared.js";
 
 interface RunFlags extends AgentExecOptions {
@@ -23,8 +27,13 @@ export function registerRun(program: Command): void {
   addAgentExecFlags(run)
     .option("--json", "stream events as newline-delimited JSON")
     .option("--download <dir>", "download artifacts to directory when complete")
-    .action((type: string | undefined, reference: string | undefined, options: RunFlags, command: Command) =>
-      runRun(type, reference, options, command),
+    .action(
+      (
+        type: string | undefined,
+        reference: string | undefined,
+        options: RunFlags,
+        command: Command,
+      ) => runRun(type, reference, options, command),
     );
 }
 
@@ -76,7 +85,8 @@ async function runSmart(
   outputMode: "inline" | "json",
   client: import("../client/index.js").BackendClient,
 ): Promise<void> {
-  const { isSessionId, hasResourceIdPrefix, isAgentId, validateResourceId } = await import("../resources/reference.js");
+  const { isSessionId, hasResourceIdPrefix, isAgentId, validateResourceId } =
+    await import("../resources/reference.js");
 
   if (isSessionId(value)) {
     throw new UsageError(
@@ -126,13 +136,14 @@ async function runExplicit(
   client: import("../client/index.js").BackendClient,
 ): Promise<void> {
   const { defaultRegistry, Verb } = await import("../registry/index.js");
-  const { ApiResourceKind } = await import(
-    "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb"
-  );
+  const { ApiResourceKind } =
+    await import("@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb");
 
   const info = defaultRegistry().getByAlias(type);
   if (info === undefined) {
-    throw new UsageError(`unknown resource type: ${type}\n\nAvailable types: agent, workflow`);
+    throw new UsageError(
+      `unknown resource type: ${type}\n\nAvailable types: agent, workflow`,
+    );
   }
   if (!info.supportedVerbs.has(Verb.Run)) {
     throw new UsageError(`${info.displayName} does not support 'run'`);
@@ -168,15 +179,26 @@ async function runResolvedAgent(
   client: import("../client/index.js").BackendClient,
 ): Promise<void> {
   const { prepareAgentExec } = await import("../resources/run/prepare.js");
-  const { executeResolvedAgent } = await import("../resources/run/agent-exec.js");
+  const { executeResolvedAgent } =
+    await import("../resources/run/agent-exec.js");
   const { toAgentExecFlags } = await import("./agent-exec-flags.js");
 
-  const prepared = await prepareAgentExec(toAgentExecFlags(options), client.stigmer, org, stderrProgress(), {
-    cloudBackend: isCloudMode(client.config),
-    // run opts into the account default_harness fill; draft deliberately
-    // does not (see the option's doc comment for the D5 rationale).
-    applyAccountHarnessDefault: true,
-  });
+  const prepared = await prepareAgentExec(
+    toAgentExecFlags(options),
+    client.stigmer,
+    org,
+    stderrProgress(),
+    {
+      // The kind's tier against the server's reported edition — the same
+      // question the console asks — never the config's backend type.
+      accountPreferencesAvailable: await client.isResourceAvailable(
+        ApiResourceKind.identity_account,
+      ),
+      // run opts into the account default_harness fill; draft deliberately
+      // does not (see the option's doc comment for the D5 rationale).
+      applyAccountHarnessDefault: true,
+    },
+  );
   await executeResolvedAgent({
     agent,
     prepared,
@@ -199,15 +221,21 @@ async function runWorkflow(
   client: import("../client/index.js").BackendClient,
 ): Promise<void> {
   if (options.workspace.length > 0) {
-    throw new UsageError("--workspace is not supported for workflows (workspace is an agent-level concept)");
+    throw new UsageError(
+      "--workspace is not supported for workflows (workspace is an agent-level concept)",
+    );
   }
-  const [{ resolveWorkflowRef }, { createWorkflowExecution }, { loadAndMergeEnv }, { parseApprovalAction }] =
-    await Promise.all([
-      import("../resources/run/resolve.js"),
-      import("../resources/run/create.js"),
-      import("../resources/run/env.js"),
-      import("../resources/run/prepare.js"),
-    ]);
+  const [
+    { resolveWorkflowRef },
+    { createWorkflowExecution },
+    { loadAndMergeEnv },
+    { parseApprovalAction },
+  ] = await Promise.all([
+    import("../resources/run/resolve.js"),
+    import("../resources/run/create.js"),
+    import("../resources/run/env.js"),
+    import("../resources/run/prepare.js"),
+  ]);
 
   const workflow = await resolveWorkflowRef(client.stigmer, reference, org);
   const runtimeEnv = loadAndMergeEnv({
@@ -220,27 +248,37 @@ async function runWorkflow(
     runtimeEnv.STIGMER_ORG_ID = { value: org, isSecret: false };
   }
 
-  const execution = await createWorkflowExecution(client.controller.bind(client), {
-    workflowId: workflow.metadata?.id ?? "",
-    orgId: org,
-    message: options.message ?? "",
-    runtimeEnv,
-  });
+  const execution = await createWorkflowExecution(
+    client.controller.bind(client),
+    {
+      workflowId: workflow.metadata?.id ?? "",
+      orgId: org,
+      message: options.message ?? "",
+      runtimeEnv,
+    },
+  );
   const id = execution.metadata?.id ?? "";
 
   if (options.detach === true) {
     process.stdout.write(`Workflow execution created: ${id}\n`);
-    process.stdout.write(`Track it with: stigmer execution logs ${id} --follow\n`);
+    process.stdout.write(
+      `Track it with: stigmer execution logs ${id} --follow\n`,
+    );
     return;
   }
 
-  const { ApprovalAction } = await import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb");
-  const { streamWorkflowExecution } = await import("../resources/run/workflow-stream.js");
+  const { ApprovalAction } =
+    await import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb");
+  const { streamWorkflowExecution } =
+    await import("../resources/run/workflow-stream.js");
   await streamWorkflowExecution({
     client: client.stigmer,
     executionId: id,
     outputMode,
-    defaultAction: options.autoApprove === true ? ApprovalAction.APPROVE_ALL : parseApprovalAction(options.approveDefault ?? ""),
+    defaultAction:
+      options.autoApprove === true
+        ? ApprovalAction.APPROVE_ALL
+        : parseApprovalAction(options.approveDefault ?? ""),
   });
 }
 
@@ -260,7 +298,11 @@ async function browseAndRunAgent(
   client: import("../client/index.js").BackendClient,
 ): Promise<void> {
   const { pickAgent } = await import("../resources/picker/ink.js");
-  const selected = await pickAgent({ client: client.stigmer, org, initialQuery });
+  const selected = await pickAgent({
+    client: client.stigmer,
+    org,
+    initialQuery,
+  });
   if (selected === undefined) return;
   await runAgent(selected.id, options, org, outputMode, client);
 }

package/src/commands/up.ts

@@ -1,6 +1,7 @@
 // `stigmer up [server]` — start the local Stigmer stack (managed Temporal, the
 // control-plane server, and the unified runner) as a supervised background
-// daemon. `up server` brings up only the control plane.
+// daemon, or with `--foreground` as this very process. `up server` brings up
+// only the control plane.
 //
 // Thin handler: parse flags, delegate to the local daemon launcher, render the
 // outcome. The launcher (and the heavy resolvers it pulls in) load lazily so
@@ -9,6 +10,8 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { Command } from "commander";
+import { CliExitError } from "../errors/cli-exit-error.js";
+import { ExitCode } from "../errors/exit-codes.js";
 import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
 import { HEALTH_STATE_FILE, SERVER_PORT } from "../local/constants.js";
 import { addResultFlags, resultFormat } from "./shared.js";
@@ -16,6 +19,13 @@ import { addResultFlags, resultFormat } from "./shared.js";
 interface UpFlags extends OutputFlags {
   serverOnly?: boolean;
   web?: boolean; // false when --no-web is passed
+  foreground?: boolean;
+}
+
+interface UpRun {
+  serverOnly: boolean;
+  noWeb: boolean;
+  foreground: boolean;
 }
 
 // The server serves the web console from its unified port (DD-012); the
@@ -23,14 +33,23 @@ interface UpFlags extends OutputFlags {
 // process, one origin — there is no separate console to not-start).
 const NO_WEB_HELP = "don't report the web console URL";
 
+// Foreground is the shape a supervisor wants — a container entrypoint, a
+// systemd unit, a tmux pane: one process to watch, signals delivered to it,
+// the stack's output on its stdio — instead of a detached daemon to poll.
+const FOREGROUND_HELP = "run the stack in this process until Ctrl-C or SIGTERM (for containers and service managers)";
+
 export function registerUp(program: Command): void {
   const up = program
     .command("up")
     .description("start the local Stigmer stack (server, runner, Temporal)")
     .option("--server-only", "start only the control plane (no runners)")
     .option("--no-web", NO_WEB_HELP)
+    .option("--foreground", FOREGROUND_HELP)
     .action((options: UpFlags) =>
-      runUp({ serverOnly: options.serverOnly === true, noWeb: options.web === false }, options),
+      runUp(
+        { serverOnly: options.serverOnly === true, noWeb: options.web === false, foreground: options.foreground === true },
+        options,
+      ),
     );
   addResultFlags(up);
 
@@ -38,16 +57,40 @@ export function registerUp(program: Command): void {
     .command("server")
     .description("start only the control plane (no runners)")
     .option("--no-web", NO_WEB_HELP)
-    .action((options: UpFlags) => runUp({ serverOnly: true, noWeb: options.web === false }, options));
+    .option("--foreground", FOREGROUND_HELP)
+    .action((options: UpFlags) =>
+      runUp({ serverOnly: true, noWeb: options.web === false, foreground: options.foreground === true }, options),
+    );
   addResultFlags(server);
 }
 
-async function runUp(opts: { serverOnly: boolean; noWeb: boolean }, flags: OutputFlags): Promise<void> {
+async function runUp(run: UpRun, flags: OutputFlags): Promise<void> {
   process.stderr.write("Starting Stigmer local stack… (first run may take a moment)\n");
-  const { up } = await import("../local/daemon/launch.js");
-  await up(opts);
+  const launch = await import("../local/daemon/launch.js");
+
+  if (!run.foreground) {
+    await launch.up(run);
+    await renderUpCard(run, flags);
+    return;
+  }
+
+  // The card renders when the stack is serving and seeded — the moment the
+  // detached shape would have returned — and the process then stays up,
+  // mirroring the server's and runner's output, until a shutdown signal.
+  const code = await launch.upForeground(run, homedir(), {
+    onReady: () => renderUpCard(run, flags),
+  });
+  if (code !== 0) {
+    // The daemon body has already logged which component failed and why.
+    const { logDir } = await import("../local/paths.js");
+    throw new CliExitError("the local stack did not start", ExitCode.General, [
+      `Check the component logs under ${logDir(homedir())}.`,
+    ]);
+  }
+}
 
-  const result = CommandResult.success(opts.serverOnly ? "Stigmer control plane is up" : "Stigmer local stack is up");
+async function renderUpCard(run: UpRun, flags: OutputFlags): Promise<void> {
+  const result = CommandResult.success(run.serverOnly ? "Stigmer control plane is up" : "Stigmer local stack is up");
   const section = result.addSection("Endpoints");
   section.field("server", `http://localhost:${SERVER_PORT}`);
   if (await consoleReported()) {
@@ -56,7 +99,8 @@ async function runUp(opts: { serverOnly: boolean; noWeb: boolean }, flags: Outpu
     // server without one must not advertise a dead URL.
     section.field("console", `http://localhost:${SERVER_PORT}`);
   }
-  result.hint("Check status with: stigmer status").hint("Stop it with:    stigmer down");
+  result.hint("Check status with: stigmer status");
+  result.hint(run.foreground ? "Stop it with:    Ctrl-C (or stigmer down from another shell)" : "Stop it with:    stigmer down");
   renderResult(result, resultFormat(flags));
 }