@stigmer/cli 3.0.8

package/src/local/temporal/download.ts

@@ -0,0 +1,54 @@
+// On-demand download of the Temporal CLI binary from GitHub releases.
+//
+// `up` needs a `temporal` binary and the upstream release is a small, public,
+// stable artifact. The fetch/gunzip/untar/write mechanics are shared with the
+// stigmer-server downloader in `../artifact.ts`; this module only owns Temporal's
+// asset-naming and the default version.
+//
+// Parity note: like the Go CLI, this does not verify a checksum (the stigmer
+// -server downloader does, per DD-003). A checksum-hardening follow-up is filed;
+// until then the integrity guarantee is HTTPS + GitHub's release immutability.
+
+import { existsSync } from "node:fs";
+import { fetchTarballBinary, mapReleaseArch, mapReleaseOs } from "../artifact.js";
+
+// Re-exported so existing consumers (temporal/index.ts, download.test.ts) keep
+// importing the tar reader from here.
+export { extractTarEntry } from "../artifact.js";
+
+/** Default Temporal CLI version (matches the Go CLI's `DefaultTemporalVersion`). */
+export const DEFAULT_TEMPORAL_VERSION = "1.5.1";
+
+export interface TemporalDownloadTarget {
+  /** Temporal CLI version, e.g. "1.5.1". */
+  version: string;
+  /** Absolute path to write the extracted `temporal` binary to. */
+  binPath: string;
+  /** Node platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Node arch (defaults to process.arch). */
+  arch?: string;
+  /** Override the fetch implementation (tests). */
+  fetchImpl?: typeof fetch;
+}
+
+/** Download and install the Temporal CLI binary to `binPath`. */
+export async function downloadTemporalCli(target: TemporalDownloadTarget): Promise<void> {
+  const goos = mapReleaseOs(target.platform ?? process.platform);
+  const goarch = mapReleaseArch(target.arch ?? process.arch);
+  const archive = `temporal_cli_${target.version}_${goos}_${goarch}.tar.gz`;
+  const url = `https://github.com/temporalio/cli/releases/download/v${target.version}/${archive}`;
+
+  await fetchTarballBinary({
+    url,
+    entryName: "temporal",
+    binPath: target.binPath,
+    label: "Temporal CLI",
+    fetchImpl: target.fetchImpl,
+  });
+}
+
+/** True if a Temporal binary is already present at `binPath`. */
+export function isTemporalInstalled(binPath: string): boolean {
+  return existsSync(binPath);
+}

package/src/local/temporal/index.ts

@@ -0,0 +1,6 @@
+// Public surface of the Temporal subsystem.
+
+export { DEFAULT_TEMPORAL_VERSION, downloadTemporalCli, extractTarEntry, isTemporalInstalled } from "./download.js";
+export { isLikelyTemporal, processCommandLine } from "./inspect.js";
+export { TemporalManager, type TemporalManagerOptions } from "./manager.js";
+export { type SupervisedTarget, type SupervisorOptions, TemporalSupervisor } from "./supervisor.js";

package/src/local/temporal/inspect.ts

@@ -0,0 +1,32 @@
+// Process-identity check guarding against PID reuse.
+//
+// A PID file can outlive the process it named; the OS may then assign that PID
+// to something unrelated. Before trusting a PID as "our Temporal", we confirm
+// the live process's command line actually looks like the Temporal dev server.
+// POSIX-only (uses `ps`); returns false on any uncertainty.
+
+import { execFileSync } from "node:child_process";
+
+/** Full command line of a process via `ps`, or null if it cannot be read. */
+export function processCommandLine(pid: number): string | null {
+  try {
+    return execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Heuristically confirm that `pid` is the Temporal server we manage: its command
+ * line mentions "temporal" and either our binary path or a "server" subcommand.
+ */
+export function isLikelyTemporal(pid: number, binPath: string): boolean {
+  const cmd = processCommandLine(pid);
+  if (cmd === null) return false;
+  const lower = cmd.toLowerCase();
+  if (!lower.includes("temporal")) return false;
+  return cmd.includes(binPath) || lower.includes("server");
+}

package/src/local/temporal/manager.test.ts

@@ -0,0 +1,31 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { temporalPidFile } from "../paths.js";
+import { writePidFile } from "../state/pidfile.js";
+import { TemporalManager } from "./manager.js";
+
+function tempHome(): string {
+  return mkdtempSync(join(tmpdir(), "stigmer-home-"));
+}
+
+describe("TemporalManager", () => {
+  it("exposes the frontend address", () => {
+    const manager = TemporalManager.forHome(tempHome());
+    expect(manager.address).toBe("127.0.0.1:7233");
+  });
+
+  it("reads the PID from the ~/.stigmer/temporal.pid location", () => {
+    const home = tempHome();
+    const manager = TemporalManager.forHome(home);
+    expect(manager.getPid()).toBeNull();
+    writePidFile(temporalPidFile(home), 5151);
+    expect(manager.getPid()).toBe(5151);
+  });
+
+  it("reports not-running when there is no PID file", async () => {
+    const manager = TemporalManager.forHome(tempHome());
+    expect(await manager.isRunning()).toBe(false);
+  });
+});

package/src/local/temporal/manager.ts

@@ -0,0 +1,247 @@
+// Lifecycle manager for the local Temporal dev server.
+//
+// Faithful TS port of the Go CLI's `temporal.Manager`, reorganized around the
+// shared primitives (file lock, PID file, TCP readiness). It installs the
+// `temporal` binary on demand, starts the dev server in its own process group,
+// and answers "is it really running?" with the same layered check the Go CLI
+// uses (PID present -> alive -> actually Temporal -> port listening). Start is
+// idempotent: a healthy instance — ours or another process's — is reused.
+
+import { mkdirSync, openSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+import { log } from "../../logger.js";
+import { CliExitError } from "../../errors/cli-exit-error.js";
+import { ExitCode } from "../../errors/exit-codes.js";
+import { tcpConnects, waitForTcp } from "../net/tcp.js";
+import { binDir, logDir, temporalDataDir, temporalLockFile, temporalPidFile } from "../paths.js";
+import { TEMPORAL_PORT, TEMPORAL_UI_PORT } from "../constants.js";
+import { type FileLock, acquireLock } from "../state/lock.js";
+import { readPidFile, removePidFile, writePidFile } from "../state/pidfile.js";
+import { findProcessByPort, isProcessAlive, killProcessGroup } from "../state/proc.js";
+import { DEFAULT_TEMPORAL_VERSION, downloadTemporalCli, isTemporalInstalled } from "./download.js";
+import { isLikelyTemporal } from "./inspect.js";
+
+const READY_TIMEOUT_MS = 10_000;
+const STOP_POLL_MS = 500;
+const STOP_TIMEOUT_MS = 10_000;
+
+export interface TemporalManagerOptions {
+  /** Path to the temporal binary (~/.stigmer/bin/temporal). */
+  binPath: string;
+  /** Temporal dev-server data directory (~/.stigmer/temporal-data). */
+  dataDir: string;
+  /** Log file the dev server's output is appended to. */
+  logFile: string;
+  /** PID file (kept for debugging; the lock is the source of truth). */
+  pidFile: string;
+  /** Single-instance lock file. */
+  lockFile: string;
+  version?: string;
+  port?: number;
+  uiPort?: number;
+}
+
+export class TemporalManager {
+  private readonly binPath: string;
+  private readonly dataDir: string;
+  private readonly logFile: string;
+  private readonly pidFile: string;
+  private readonly lockFile: string;
+  private readonly version: string;
+  private readonly port: number;
+  private readonly uiPort: number;
+  private lock: FileLock | null = null;
+
+  constructor(options: TemporalManagerOptions) {
+    this.binPath = options.binPath;
+    this.dataDir = options.dataDir;
+    this.logFile = options.logFile;
+    this.pidFile = options.pidFile;
+    this.lockFile = options.lockFile;
+    this.version = options.version ?? DEFAULT_TEMPORAL_VERSION;
+    this.port = options.port ?? TEMPORAL_PORT;
+    this.uiPort = options.uiPort ?? TEMPORAL_UI_PORT;
+  }
+
+  /** Build a manager from the standard ~/.stigmer layout. */
+  static forHome(home: string = homedir()): TemporalManager {
+    return new TemporalManager({
+      binPath: join(binDir(home), "temporal"),
+      dataDir: temporalDataDir(home),
+      logFile: join(logDir(home), "temporal.log"),
+      pidFile: temporalPidFile(home),
+      lockFile: temporalLockFile(home),
+    });
+  }
+
+  /** host:port of the Temporal frontend. */
+  get address(): string {
+    return `127.0.0.1:${this.port}`;
+  }
+
+  /** PID of the running dev server, or null. */
+  getPid(): number | null {
+    return readPidFile(this.pidFile);
+  }
+
+  /** Install the Temporal binary on demand if it is not already present. */
+  async ensureInstalled(): Promise<void> {
+    if (isTemporalInstalled(this.binPath)) {
+      log.debug("temporal CLI already installed", { path: this.binPath });
+      return;
+    }
+    log.info("downloading Temporal CLI", { version: this.version });
+    await downloadTemporalCli({ version: this.version, binPath: this.binPath });
+    log.info("Temporal CLI installed", { path: this.binPath });
+  }
+
+  /**
+   * Start the dev server. Idempotent: reuses a healthy instance, reclaims a lock
+   * left by a dead daemon, and refuses to start only when another live process
+   * holds the lock without a responding server.
+   */
+  async start(): Promise<void> {
+    if (await this.isRunning()) {
+      log.info("Temporal already running and healthy — reusing", { address: this.address });
+      return;
+    }
+
+    // A lock we still hold means Temporal died under us; drop it so we can
+    // re-acquire cleanly.
+    if (this.lock !== null) {
+      log.info("releasing stale Temporal lock (server died while we held it)");
+      this.lock.release();
+      this.lock = null;
+      removePidFile(this.pidFile);
+    }
+
+    this.cleanupStaleProcesses();
+
+    const lock = acquireLock(this.lockFile);
+    if (lock === null) {
+      // Another live process owns the lock. If its server answers, reuse it;
+      // otherwise we cannot safely start a competing instance.
+      if (await this.isPortInUse()) {
+        log.info("Temporal lock held by another process and port is active — reusing");
+        return;
+      }
+      throw new CliExitError("Temporal lock held by another process but the service is not responding", ExitCode.General);
+    }
+    this.lock = lock;
+
+    try {
+      await this.ensureInstalled();
+      mkdirSync(this.dataDir, { recursive: true });
+      mkdirSync(dirname(this.logFile), { recursive: true });
+
+      const pid = this.spawnServer();
+      writePidFile(this.pidFile, pid);
+      log.info("Temporal dev server started", { pid, port: this.port });
+
+      await waitForTcp({ port: this.port, timeoutMs: READY_TIMEOUT_MS, label: "temporal dev server" });
+      log.info("Temporal is ready", { address: this.address });
+    } catch (err) {
+      const pid = this.getPid();
+      if (pid !== null) killProcessGroup(pid, "SIGKILL");
+      removePidFile(this.pidFile);
+      this.lock?.release();
+      this.lock = null;
+      throw err;
+    }
+  }
+
+  /** Stop the dev server gracefully (SIGTERM, then SIGKILL), releasing the lock. */
+  async stop(): Promise<void> {
+    const pid = this.getPid();
+    if (pid === null) {
+      this.lock?.release();
+      this.lock = null;
+      return;
+    }
+
+    killProcessGroup(pid, "SIGTERM");
+    log.info("sent SIGTERM to Temporal process group", { pid });
+
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      if (!(await this.isRunning())) {
+        this.finishStop();
+        log.info("Temporal stopped");
+        return;
+      }
+      await sleep(STOP_POLL_MS);
+    }
+
+    log.warn("Temporal did not stop gracefully — force killing process group", { pid });
+    killProcessGroup(pid, "SIGKILL");
+    this.finishStop();
+  }
+
+  /** Layered liveness: PID present -> alive -> actually Temporal -> port open. */
+  async isRunning(): Promise<boolean> {
+    const pid = this.getPid();
+    if (pid === null) return false;
+    if (!isProcessAlive(pid)) return false;
+    if (!isLikelyTemporal(pid, this.binPath)) return false;
+    return this.isPortInUse();
+  }
+
+  private isPortInUse(): Promise<boolean> {
+    return tcpConnects(this.port, "127.0.0.1", 100);
+  }
+
+  private finishStop(): void {
+    removePidFile(this.pidFile);
+    this.lock?.release();
+    this.lock = null;
+  }
+
+  // Start the dev server detached in its own process group so the whole tree can
+  // later be signaled, with output appended to the Temporal log file.
+  private spawnServer(): number {
+    const out = openSync(this.logFile, "a");
+    const child = spawn(
+      this.binPath,
+      [
+        "server",
+        "start-dev",
+        "--port",
+        String(this.port),
+        "--db-filename",
+        join(this.dataDir, "temporal.db"),
+        "--ui-port",
+        String(this.uiPort),
+        "--log-format",
+        "json",
+      ],
+      { detached: true, stdio: ["ignore", out, out] },
+    );
+    child.unref();
+    if (child.pid === undefined) {
+      throw new CliExitError("failed to start Temporal process", ExitCode.General);
+    }
+    return child.pid;
+  }
+
+  // Remove a stale PID file, or kill an orphaned Temporal occupying our port.
+  private cleanupStaleProcesses(): void {
+    const pid = this.getPid();
+    if (pid !== null) {
+      if (!isProcessAlive(pid) || !isLikelyTemporal(pid, this.binPath)) {
+        removePidFile(this.pidFile);
+      }
+      return;
+    }
+    const orphan = findProcessByPort(this.port);
+    if (orphan !== null && isLikelyTemporal(orphan, this.binPath)) {
+      log.warn("killing orphaned Temporal found via port", { pid: orphan, port: this.port });
+      killProcessGroup(orphan, "SIGKILL");
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/local/temporal/supervisor.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it, vi } from "vitest";
+import { type Logger } from "../../logger.js";
+import { type SupervisedTarget, TemporalSupervisor } from "./supervisor.js";
+
+const silentLog: Logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+function makeTarget(overrides: Partial<SupervisedTarget> = {}): SupervisedTarget & {
+  isRunning: ReturnType<typeof vi.fn>;
+  start: ReturnType<typeof vi.fn>;
+} {
+  return {
+    isRunning: vi.fn(async () => true),
+    start: vi.fn(async () => {}),
+    ...overrides,
+  } as never;
+}
+
+function makeSupervisor(target: SupervisedTarget) {
+  return new TemporalSupervisor(target, { backoffMs: 0, sleep: async () => {}, log: silentLog });
+}
+
+describe("TemporalSupervisor.checkHealthAndRestart", () => {
+  it("does nothing while the target is healthy", async () => {
+    const target = makeTarget({ isRunning: vi.fn(async () => true) });
+    await makeSupervisor(target).checkHealthAndRestart();
+    expect(target.start).not.toHaveBeenCalled();
+  });
+
+  it("restarts when the target is unhealthy", async () => {
+    const target = makeTarget({ isRunning: vi.fn(async () => false) });
+    await makeSupervisor(target).checkHealthAndRestart();
+    expect(target.start).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows a restart failure (retried on the next tick)", async () => {
+    const target = makeTarget({
+      isRunning: vi.fn(async () => false),
+      start: vi.fn(async () => {
+        throw new Error("boom");
+      }),
+    });
+    await expect(makeSupervisor(target).checkHealthAndRestart()).resolves.toBeUndefined();
+    expect(target.start).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not restart if stopped during the backoff", async () => {
+    const target = makeTarget({ isRunning: vi.fn(async () => false) });
+    const supervisor = new TemporalSupervisor(target, {
+      backoffMs: 0,
+      // Stop the supervisor while it is "sleeping" through the backoff.
+      sleep: async () => {
+        supervisor.stop();
+      },
+      log: silentLog,
+    });
+    await supervisor.checkHealthAndRestart();
+    expect(target.start).not.toHaveBeenCalled();
+  });
+});
+
+describe("TemporalSupervisor start/stop", () => {
+  it("schedules ticks and stops cleanly", async () => {
+    vi.useFakeTimers();
+    try {
+      const target = makeTarget({ isRunning: vi.fn(async () => true) });
+      const supervisor = new TemporalSupervisor(target, { intervalMs: 1000, log: silentLog });
+      supervisor.start();
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(target.isRunning).toHaveBeenCalledTimes(1);
+      supervisor.stop();
+      await vi.advanceTimersByTimeAsync(5000);
+      expect(target.isRunning).toHaveBeenCalledTimes(1); // no further ticks after stop
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/local/temporal/supervisor.ts

@@ -0,0 +1,97 @@
+// Self-healing supervisor for the Temporal dev server.
+//
+// On a fixed interval it asks "is Temporal healthy?" and, if not, restarts it
+// via the idempotent start path (which reuses healthy instances and cleans up
+// stale ones). This is intentionally separate from the daemon's child
+// supervisor: Temporal owns its own lifecycle and lock, so it carries its own
+// watchdog — exactly the split the Go CLI uses.
+//
+// The check and backoff are dependency-injected (clock) so the policy is unit-
+// testable without real time, and the loop never overlaps with itself.
+
+import { type Logger, log as defaultLog } from "../../logger.js";
+
+const DEFAULT_INTERVAL_MS = 5_000;
+const DEFAULT_BACKOFF_MS = 1_000;
+
+/** The minimal surface the supervisor drives. TemporalManager satisfies it. */
+export interface SupervisedTarget {
+  isRunning(): Promise<boolean>;
+  start(): Promise<void>;
+}
+
+export interface SupervisorOptions {
+  intervalMs?: number;
+  backoffMs?: number;
+  /** Injectable sleep, for deterministic tests. */
+  sleep?: (ms: number) => Promise<void>;
+  log?: Logger;
+}
+
+export class TemporalSupervisor {
+  private readonly target: SupervisedTarget;
+  private readonly intervalMs: number;
+  private readonly backoffMs: number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly log: Logger;
+  private timer: NodeJS.Timeout | null = null;
+  private stopped = false;
+  private ticking = false;
+
+  constructor(target: SupervisedTarget, options: SupervisorOptions = {}) {
+    this.target = target;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+    this.sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.log = options.log ?? defaultLog;
+  }
+
+  /** Begin monitoring. Returns immediately; the loop runs on a timer. */
+  start(): void {
+    if (this.timer !== null) return;
+    this.stopped = false;
+    this.log.info("starting Temporal supervisor", { interval_ms: this.intervalMs });
+    const tick = (): void => {
+      void this.checkHealthAndRestart().finally(() => {
+        if (!this.stopped) this.timer = setTimeout(tick, this.intervalMs);
+      });
+    };
+    this.timer = setTimeout(tick, this.intervalMs);
+  }
+
+  /** Stop monitoring. Safe to call multiple times. */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.log.info("stopping Temporal supervisor");
+  }
+
+  /**
+   * One health check + conditional restart. Public for unit testing: it is the
+   * whole supervision policy, exercised without real timers.
+   */
+  async checkHealthAndRestart(): Promise<void> {
+    if (this.ticking) return; // never overlap a previous tick
+    this.ticking = true;
+    try {
+      if (await this.target.isRunning()) {
+        this.log.debug("Temporal health check passed");
+        return;
+      }
+      this.log.warn("Temporal health check failed — attempting restart");
+      await this.sleep(this.backoffMs);
+      if (this.stopped) return; // bailed out during backoff
+      try {
+        await this.target.start();
+        this.log.info("Temporal restarted");
+      } catch (err) {
+        this.log.error("failed to restart Temporal — will retry next check", { error: String(err) });
+      }
+    } finally {
+      this.ticking = false;
+    }
+  }
+}

package/src/local/webconsole/index.ts

@@ -0,0 +1,13 @@
+// Embedded web-console availability.
+//
+// The Go CLI embeds the console's static assets via go:embed and serves them on
+// :8234. There is no TS equivalent bundled in T05, so the daemon detects the
+// console as unavailable and skips it cleanly (recording a "stopped" state),
+// exactly as the Go daemon does when built without assets. Real serving — and
+// the asset-bundling decision behind it — is deferred to T06.
+
+/** Whether an embedded web console is available to serve. Always false until
+ * T06 wires asset bundling + an HTTP handler. */
+export function isWebConsoleAvailable(): boolean {
+  return false;
+}

package/src/logger.ts

@@ -0,0 +1,39 @@
+// Diagnostic logger for the CLI. Writes only to stderr so structured command
+// output on stdout stays clean for piping. `debug` is silent unless `--debug`
+// is set, so scripts never see diagnostics on the happy path; `info`/`warn`/
+// `error` always emit, which is what the supervised daemon relies on to record
+// its lifecycle into daemon.log (its stderr is redirected there).
+
+import { isDebug } from "./runtime.js";
+
+function emit(level: string, msg: string, fields?: Record<string, unknown>): void {
+  const suffix = fields
+    ? " " +
+      Object.entries(fields)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+        .join(" ")
+    : "";
+  process.stderr.write(`${level} ${msg}${suffix}\n`);
+}
+
+export const log = {
+  /** Emit a diagnostic line; a no-op unless `--debug` is active. */
+  debug(msg: string, fields?: Record<string, unknown>): void {
+    if (isDebug()) emit("debug", msg, fields);
+  },
+  /** Emit an informational line (always). */
+  info(msg: string, fields?: Record<string, unknown>): void {
+    emit("info", msg, fields);
+  },
+  /** Emit a warning line (always). */
+  warn(msg: string, fields?: Record<string, unknown>): void {
+    emit("warn", msg, fields);
+  },
+  /** Emit an error line (always). */
+  error(msg: string, fields?: Record<string, unknown>): void {
+    emit("error", msg, fields);
+  },
+};
+
+/** The logger interface, for dependency injection in tests. */
+export type Logger = typeof log;

package/src/output/command-result.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { CommandResult, resultToHuman, resultToJson, resultToQuiet } from "./command-result.js";
+
+describe("resultToJson", () => {
+  it("emits status as a lowercase string", () => {
+    expect(JSON.parse(resultToJson(CommandResult.success("ok"))).status).toBe("success");
+    expect(JSON.parse(resultToJson(CommandResult.warning("w"))).status).toBe("warning");
+    expect(JSON.parse(resultToJson(CommandResult.error("e"))).status).toBe("error");
+  });
+
+  it("omits empty sections and hints", () => {
+    const parsed = JSON.parse(resultToJson(CommandResult.success("done")));
+    expect(parsed).not.toHaveProperty("sections");
+    expect(parsed).not.toHaveProperty("hints");
+  });
+
+  it("serializes sections (fields + items) and hints", () => {
+    const result = CommandResult.success("Created");
+    result.addSection("Details").field("ID", "abc").field("Name", "agent");
+    result.addSection("Items").item("first").item("second");
+    result.hint("try this").hint("and that");
+
+    const parsed = JSON.parse(resultToJson(result));
+    expect(parsed.sections).toHaveLength(2);
+    expect(parsed.sections[0]).toEqual({
+      title: "Details",
+      fields: [
+        { key: "ID", value: "abc" },
+        { key: "Name", value: "agent" },
+      ],
+    });
+    expect(parsed.sections[1]).toEqual({ title: "Items", items: ["first", "second"] });
+    expect(parsed.hints).toEqual(["try this", "and that"]);
+  });
+});
+
+describe("resultToHuman (plain, no color)", () => {
+  it("renders the status icon, message, fields, and hints", () => {
+    const result = CommandResult.success("Created agent");
+    result.addSection("Details").field("ID", "agt-123");
+    result.hint("Run: stigmer get agent agt-123");
+
+    const out = resultToHuman(result, false);
+    expect(out).toContain("✓ Created agent");
+    expect(out).toContain("Details:");
+    expect(out).toContain("ID");
+    expect(out).toContain("agt-123");
+    expect(out).toContain("Run: stigmer get agent agt-123");
+  });
+
+  it("uses an error icon for error results", () => {
+    expect(resultToHuman(CommandResult.error("boom"), false)).toContain("✗ boom");
+  });
+});
+
+describe("resultToQuiet (plain, no color)", () => {
+  it("renders only the status line", () => {
+    const result = CommandResult.success("Done");
+    result.addSection("Details").field("ID", "abc");
+    const out = resultToQuiet(result, false);
+    expect(out).toBe("✓ Done\n");
+    expect(out).not.toContain("Details");
+  });
+});