@bastani/atomic 0.5.20-0 → 0.5.21-0

package/src/commands/cli/workflow-status.ts

@@ -0,0 +1,330 @@
+/**
+ * `atomic workflow status [<id>]` — query the current state of one or
+ * all running workflows so an orchestrating agent can decide whether
+ * to keep waiting, surface a HIL prompt to the user, or move on.
+ *
+ * Status sources, in priority order:
+ *   1. <sessionDir>/status.json — written by the orchestrator on every
+ *      panel-store mutation. Provides per-stage detail and the
+ *      derived overall state (in_progress | error | completed |
+ *      needs_review).
+ *   2. tmux liveness fallback — when status.json is missing or stale
+ *      we still report whether the tmux session is alive so
+ *      script-driven workflows aren't blind during the brief window
+ *      before the orchestrator first writes its snapshot.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { COLORS, createPainter, type PaletteKey } from "../../theme/colors.ts";
+import {
+  isTmuxInstalled as _isTmuxInstalled,
+  listSessions as _listSessions,
+  sessionExists as _sessionExists,
+} from "../../sdk/workflows/index.ts";
+import {
+  readSnapshot,
+  workflowRunIdFromTmuxName,
+  type WorkflowOverallStatus,
+  type WorkflowStatusSnapshot,
+} from "../../sdk/runtime/status-writer.ts";
+import type { TmuxSession } from "../../sdk/runtime/tmux.ts";
+
+export type StatusFormat = "json" | "text";
+
+/** A single workflow's resolved status, as returned to the caller. */
+export interface WorkflowStatusReport {
+  /** Tmux session name (e.g. `atomic-wf-claude-ralph-a1b2c3d4`). */
+  id: string;
+  /** Workflow run id (the trailing 8-hex segment of the tmux name). */
+  workflowRunId: string;
+  /** Workflow name pulled from the snapshot. Empty when no snapshot exists. */
+  workflowName: string;
+  /** Agent backend (claude / copilot / opencode). */
+  agent: string;
+  overall: WorkflowOverallStatus;
+  /** True when the tmux session is currently alive on the atomic socket. */
+  alive: boolean;
+  /** ISO timestamp of the last snapshot, or null when none exists. */
+  updatedAt: string | null;
+  /** Sessions/stages, mirrored from the snapshot. Empty when no snapshot exists. */
+  sessions: WorkflowStatusSnapshot["sessions"];
+  /** Fatal-error message, if any. */
+  fatalError: string | null;
+}
+
+export interface StatusDeps {
+  isTmuxInstalled: () => boolean;
+  sessionExists: (name: string) => boolean;
+  listSessions: () => TmuxSession[];
+  /**
+   * Read a snapshot from disk. Defaults to the real reader; tests
+   * inject a fake to control the snapshot data without touching the
+   * filesystem.
+   */
+  readSnapshot: typeof readSnapshot;
+  /** Base directory for session dirs. Defaults to `~/.atomic/sessions`. */
+  sessionsBaseDir: string;
+}
+
+const defaultDeps: StatusDeps = {
+  isTmuxInstalled: _isTmuxInstalled,
+  sessionExists: _sessionExists,
+  listSessions: _listSessions,
+  readSnapshot,
+  sessionsBaseDir: join(homedir(), ".atomic", "sessions"),
+};
+
+/**
+ * Build a report for a single workflow. When the on-disk snapshot is
+ * missing we still emit a minimal report so callers can distinguish
+ * "workflow exists but hasn't written a snapshot yet" from "workflow
+ * doesn't exist at all" (the latter returns null upstream).
+ */
+async function buildReport(
+  tmuxName: string,
+  alive: boolean,
+  deps: StatusDeps,
+): Promise<WorkflowStatusReport | null> {
+  const workflowRunId = workflowRunIdFromTmuxName(tmuxName);
+  if (!workflowRunId) return null;
+
+  const sessionDir = join(deps.sessionsBaseDir, workflowRunId);
+  const snapshot = await deps.readSnapshot(sessionDir);
+
+  if (!snapshot) {
+    return {
+      id: tmuxName,
+      workflowRunId,
+      workflowName: "",
+      agent: "",
+      // Without a snapshot we can only say it's still running (or
+      // already gone) — never that it succeeded or errored.
+      overall: alive ? "in_progress" : "error",
+      alive,
+      updatedAt: null,
+      sessions: [],
+      fatalError: alive ? null : "orchestrator exited before writing status",
+    };
+  }
+
+  // If the orchestrator has shut down but the snapshot still says
+  // in_progress, downgrade to error — the process died without
+  // writing a terminal state.
+  const overall: WorkflowOverallStatus =
+    !alive && snapshot.overall === "in_progress" ? "error" : snapshot.overall;
+
+  return {
+    id: tmuxName,
+    workflowRunId,
+    workflowName: snapshot.workflowName,
+    agent: snapshot.agent,
+    overall,
+    alive,
+    updatedAt: snapshot.updatedAt,
+    sessions: snapshot.sessions,
+    fatalError:
+      overall === "error" && snapshot.fatalError === null && !alive
+        ? "orchestrator exited unexpectedly"
+        : snapshot.fatalError,
+  };
+}
+
+export interface WorkflowStatusOptions {
+  /** Filter to a specific workflow by tmux session name. */
+  id?: string;
+  format?: StatusFormat;
+}
+
+/**
+ * Top-level command. Prints either a single report (when `id` is
+ * provided) or the list of all workflow sessions on the atomic
+ * socket. Returns 1 when a requested id can't be found, 0 otherwise.
+ */
+export async function workflowStatusCommand(
+  options: WorkflowStatusOptions,
+  deps: StatusDeps = defaultDeps,
+): Promise<number> {
+  const format: StatusFormat = options.format ?? "json";
+
+  if (!deps.isTmuxInstalled()) {
+    return emit(format, { workflows: [] }, "no sessions running (tmux is not installed)");
+  }
+
+  const allSessions = deps.listSessions();
+  const workflowSessions = allSessions.filter((s) => s.type === "workflow");
+
+  // ── Single-workflow query ────────────────────────────────────────
+  if (options.id !== undefined) {
+    const target = workflowSessions.find((s) => s.name === options.id);
+    // Honour the requested id even when the tmux session is gone but
+    // the on-disk snapshot might still be readable (best-effort
+    // post-mortem). When neither exists we report not found.
+    if (!target) {
+      const fallbackRunId = workflowRunIdFromTmuxName(options.id);
+      if (fallbackRunId) {
+        const report = await buildReport(options.id, false, deps);
+        if (report && report.workflowName !== "") {
+          return emitReport(format, report);
+        }
+      }
+      return reportError(
+        format,
+        `Workflow '${options.id}' not found.`,
+      );
+    }
+    const report = await buildReport(target.name, true, deps);
+    if (!report) {
+      return reportError(format, `Could not parse workflow id '${options.id}'.`);
+    }
+    return emitReport(format, report);
+  }
+
+  // ── All-workflow listing ─────────────────────────────────────────
+  const reports: WorkflowStatusReport[] = [];
+  for (const s of workflowSessions) {
+    const r = await buildReport(s.name, true, deps);
+    if (r) reports.push(r);
+  }
+
+  return emit(
+    format,
+    { workflows: reports },
+    "no workflows running",
+    reports,
+  );
+}
+
+// ─── Output helpers ─────────────────────────────────────────────────
+
+function emit(
+  format: StatusFormat,
+  jsonPayload: { workflows: WorkflowStatusReport[] },
+  emptyMessage: string,
+  reports?: WorkflowStatusReport[],
+): number {
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(jsonPayload, null, 2) + "\n");
+    return 0;
+  }
+  const list = reports ?? jsonPayload.workflows;
+  if (list.length === 0) {
+    const paint = createPainter();
+    process.stdout.write(
+      "\n  " + paint("text", emptyMessage, { bold: true }) + "\n\n",
+    );
+    return 0;
+  }
+  process.stdout.write(renderListText(list));
+  return 0;
+}
+
+function emitReport(format: StatusFormat, report: WorkflowStatusReport): number {
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    process.stdout.write(renderReportText(report));
+  }
+  return 0;
+}
+
+function reportError(format: StatusFormat, message: string): number {
+  if (format === "json") {
+    process.stdout.write(JSON.stringify({ error: message }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`${COLORS.red}Error: ${message}${COLORS.reset}\n`);
+  }
+  return 1;
+}
+
+const OVERALL_COLORS: Record<WorkflowOverallStatus, PaletteKey> = {
+  in_progress: "accent",
+  needs_review: "warning",
+  completed: "success",
+  error: "error",
+};
+
+const OVERALL_INDICATOR: Record<WorkflowOverallStatus, string> = {
+  in_progress: "●",
+  needs_review: "!",
+  completed: "✓",
+  error: "✗",
+};
+
+function renderListText(reports: WorkflowStatusReport[]): string {
+  const paint = createPainter();
+  const lines: string[] = [];
+  const noun = reports.length === 1 ? "workflow" : "workflows";
+  lines.push("");
+  lines.push(
+    "  " +
+      paint("text", String(reports.length), { bold: true }) +
+      " " +
+      paint("dim", noun),
+  );
+  lines.push("");
+  for (const r of reports) {
+    const color = OVERALL_COLORS[r.overall];
+    const indicator = OVERALL_INDICATOR[r.overall];
+    const label =
+      r.workflowName !== "" ? r.workflowName : "(no snapshot)";
+    lines.push(
+      "  " +
+        paint(color, indicator) +
+        " " +
+        paint("text", r.id, { bold: true }) +
+        "  " +
+        paint(color, r.overall) +
+        "  " +
+        paint("dim", label),
+    );
+  }
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+function renderReportText(report: WorkflowStatusReport): string {
+  const paint = createPainter();
+  const color = OVERALL_COLORS[report.overall];
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(
+    "  " +
+      paint(color, OVERALL_INDICATOR[report.overall]) +
+      " " +
+      paint("text", report.id, { bold: true }) +
+      "  " +
+      paint(color, report.overall),
+  );
+  if (report.workflowName !== "") {
+    lines.push(
+      "  " +
+        paint("dim", "workflow: ") +
+        paint("text", report.workflowName) +
+        paint("dim", " · ") +
+        paint("accent", report.agent),
+    );
+  }
+  if (report.fatalError) {
+    lines.push("  " + paint("error", `error: ${report.fatalError}`));
+  }
+  if (report.sessions.length > 0) {
+    lines.push("");
+    lines.push("  " + paint("dim", "stages:"));
+    for (const s of report.sessions) {
+      lines.push(
+        "    " +
+          paint("text", s.name) +
+          "  " +
+          paint("dim", s.status) +
+          (s.error ? "  " + paint("error", s.error) : ""),
+      );
+    }
+  }
+  if (report.updatedAt) {
+    lines.push("");
+    lines.push("  " + paint("dim", `updated: ${report.updatedAt}`));
+  }
+  lines.push("");
+  return lines.join("\n") + "\n";
+}

package/src/sdk/components/orchestrator-panel.tsx

@@ -11,7 +11,7 @@ import { deriveGraphTheme } from "./graph-theme.ts";
 import type { GraphTheme } from "./graph-theme.ts";
 import { PanelStore } from "./orchestrator-panel-store.ts";
 import { StoreContext, ThemeContext, TmuxSessionContext } from "./orchestrator-panel-contexts.ts";
-import type { PanelSession, PanelOptions } from "./orchestrator-panel-types.ts";
+import type { PanelSession, PanelOptions, SessionData } from "./orchestrator-panel-types.ts";
 import { SessionGraphPanel } from "./session-graph-panel.tsx";
 import { ErrorBoundary } from "./error-boundary.tsx";
 
@@ -179,4 +179,39 @@ export class OrchestratorPanel {
       this.renderer.destroy();
     } catch {}
   }
+
+  /**
+   * Subscribe to store mutations. Returned function unsubscribes.
+   *
+   * Used by the orchestrator process to mirror the in-memory panel
+   * state to a `status.json` file on disk so out-of-process consumers
+   * (e.g. `atomic workflow status`) can read the live workflow state.
+   */
+  subscribe(fn: () => void): () => void {
+    return this.store.subscribe(fn);
+  }
+
+  /**
+   * Read-only snapshot of the fields needed by the on-disk status
+   * writer. Defined here (not in PanelStore) because the store keeps
+   * full mutable references; this projection drops the renderer-only
+   * promise resolvers and version counter.
+   */
+  getSnapshot(): {
+    workflowName: string;
+    agent: string;
+    prompt: string;
+    fatalError: string | null;
+    completionReached: boolean;
+    sessions: readonly SessionData[];
+  } {
+    return {
+      workflowName: this.store.workflowName,
+      agent: this.store.agent,
+      prompt: this.store.prompt,
+      fatalError: this.store.fatalError,
+      completionReached: this.store.completionReached,
+      sessions: this.store.sessions,
+    };
+  }
 }

package/src/sdk/runtime/executor.ts

@@ -55,6 +55,7 @@ import {
 } from "../providers/claude.ts";
 import { OrchestratorPanel } from "./panel.tsx";
 import { GraphFrontierTracker } from "./graph-inference.ts";
+import { buildSnapshot, writeSnapshot } from "./status-writer.ts";
 import { errorMessage } from "../errors.ts";
 import { createPainter } from "../../theme/colors.ts";
 
@@ -1533,11 +1534,47 @@ export async function runOrchestrator(): Promise<void> {
     tmuxSession: tmuxSessionName,
   });
 
+  // Mirror panel-store mutations to <sessionDir>/status.json so
+  // out-of-process consumers (e.g. `atomic workflow status`) can read
+  // the live workflow state without IPC into the orchestrator.
+  // Writes are debounced via a "pending" flag so a burst of mutations
+  // collapses into a single file write.
+  let snapshotPending = false;
+  const persistSnapshot = (): void => {
+    if (snapshotPending) return;
+    snapshotPending = true;
+    queueMicrotask(() => {
+      snapshotPending = false;
+      const snap = panel.getSnapshot();
+      void writeSnapshot(
+        sessionsBaseDir,
+        buildSnapshot({
+          workflowRunId,
+          tmuxSession: tmuxSessionName,
+          ...snap,
+        }),
+      );
+    });
+  };
+  const unsubscribePanel = panel.subscribe(persistSnapshot);
+  // Seed an initial snapshot so the file exists before any session starts.
+  persistSnapshot();
+
   // Idempotent shutdown guard
   let shutdownCalled = false;
   const shutdown = (exitCode = 0) => {
     if (shutdownCalled) return;
     shutdownCalled = true;
+    unsubscribePanel();
+    // Final snapshot reflecting terminal state (completed/error/aborted).
+    void writeSnapshot(
+      sessionsBaseDir,
+      buildSnapshot({
+        workflowRunId,
+        tmuxSession: tmuxSessionName,
+        ...panel.getSnapshot(),
+      }),
+    );
     panel.destroy();
     try {
       tmux.killSession(tmuxSessionName);

package/src/sdk/runtime/status-writer.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Unit tests for the workflow status writer.
+ *
+ * Covers the pure helpers (overall-status derivation, snapshot
+ * construction, tmux-name → run-id parsing) and the file I/O round
+ * trip against a real temp directory.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  buildSnapshot,
+  deriveOverallStatus,
+  readSnapshot,
+  workflowRunIdFromTmuxName,
+  writeSnapshot,
+  type WorkflowStatusSnapshot,
+} from "./status-writer.ts";
+import type { SessionData } from "../components/orchestrator-panel-types.ts";
+
+function session(
+  name: string,
+  status: SessionData["status"],
+  extra: Partial<SessionData> = {},
+): SessionData {
+  return {
+    name,
+    status,
+    parents: [],
+    startedAt: 1000,
+    endedAt: null,
+    ...extra,
+  };
+}
+
+// ─── deriveOverallStatus ────────────────────────────────────────────
+
+describe("deriveOverallStatus", () => {
+  test("returns 'error' when fatalError is set, even if completion is reached", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [],
+        fatalError: "boom",
+        completionReached: true,
+      }),
+    ).toBe("error");
+  });
+
+  test("returns 'error' when any session ended in error", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "complete"), session("b", "error")],
+        fatalError: null,
+        completionReached: false,
+      }),
+    ).toBe("error");
+  });
+
+  test("returns 'needs_review' when any session is awaiting_input", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "running"), session("b", "awaiting_input")],
+        fatalError: null,
+        completionReached: false,
+      }),
+    ).toBe("needs_review");
+  });
+
+  test("'needs_review' wins over 'completed' so a HIL pause near the end isn't reported as done", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "complete"), session("b", "awaiting_input")],
+        fatalError: null,
+        completionReached: true,
+      }),
+    ).toBe("needs_review");
+  });
+
+  test("returns 'completed' when completionReached and nothing errored or paused", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "complete"), session("b", "complete")],
+        fatalError: null,
+        completionReached: true,
+      }),
+    ).toBe("completed");
+  });
+
+  test("returns 'in_progress' as the default", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "running")],
+        fatalError: null,
+        completionReached: false,
+      }),
+    ).toBe("in_progress");
+  });
+});
+
+// ─── workflowRunIdFromTmuxName ──────────────────────────────────────
+
+describe("workflowRunIdFromTmuxName", () => {
+  test("extracts the trailing 8-hex segment from a workflow session name", () => {
+    expect(workflowRunIdFromTmuxName("atomic-wf-claude-ralph-a1b2c3d4")).toBe(
+      "a1b2c3d4",
+    );
+  });
+
+  test("handles workflow names containing hyphens", () => {
+    expect(
+      workflowRunIdFromTmuxName("atomic-wf-claude-deep-research-12345678"),
+    ).toBe("12345678");
+  });
+
+  test("returns null for chat sessions", () => {
+    expect(workflowRunIdFromTmuxName("atomic-chat-claude-deadbeef")).toBeNull();
+  });
+
+  test("returns null when the suffix is not 8-char hex", () => {
+    expect(workflowRunIdFromTmuxName("atomic-wf-claude-ralph-not-hex")).toBeNull();
+  });
+
+  test("returns null for an unrelated session name", () => {
+    expect(workflowRunIdFromTmuxName("my-session")).toBeNull();
+  });
+});
+
+// ─── buildSnapshot ──────────────────────────────────────────────────
+
+describe("buildSnapshot", () => {
+  test("populates schemaVersion + identifying fields and clones session arrays", () => {
+    const fixed = new Date("2026-01-01T00:00:00.000Z");
+    const sourceParents = ["orchestrator"];
+    const sourceSession = session("orchestrator", "running", { parents: sourceParents });
+    const snap = buildSnapshot(
+      {
+        workflowRunId: "abcd1234",
+        tmuxSession: "atomic-wf-claude-ralph-abcd1234",
+        workflowName: "ralph",
+        agent: "claude",
+        prompt: "hello",
+        fatalError: null,
+        completionReached: false,
+        sessions: [sourceSession],
+      },
+      () => fixed,
+    );
+
+    expect(snap.schemaVersion).toBe(1);
+    expect(snap.workflowRunId).toBe("abcd1234");
+    expect(snap.tmuxSession).toBe("atomic-wf-claude-ralph-abcd1234");
+    expect(snap.workflowName).toBe("ralph");
+    expect(snap.agent).toBe("claude");
+    expect(snap.prompt).toBe("hello");
+    expect(snap.overall).toBe("in_progress");
+    expect(snap.updatedAt).toBe("2026-01-01T00:00:00.000Z");
+    expect(snap.sessions).toHaveLength(1);
+    expect(snap.sessions[0]!.name).toBe("orchestrator");
+    // parents must be cloned, not aliased to the input array — otherwise
+    // a later panel-store mutation would silently rewrite a snapshot
+    // that we already handed to a consumer.
+    expect(snap.sessions[0]!.parents).not.toBe(sourceParents);
+    expect(snap.sessions[0]!.parents).toEqual(sourceParents);
+  });
+
+  test("propagates the derived overall status from the inputs", () => {
+    const snap = buildSnapshot({
+      workflowRunId: "abcd1234",
+      tmuxSession: "x",
+      workflowName: "ralph",
+      agent: "claude",
+      prompt: "",
+      fatalError: null,
+      completionReached: true,
+      sessions: [session("a", "complete")],
+    });
+    expect(snap.overall).toBe("completed");
+  });
+});
+
+// ─── write/read round trip ──────────────────────────────────────────
+
+describe("writeSnapshot + readSnapshot", () => {
+  test("persists a snapshot and reads it back unchanged", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      const snap: WorkflowStatusSnapshot = buildSnapshot({
+        workflowRunId: "abcd1234",
+        tmuxSession: "atomic-wf-claude-ralph-abcd1234",
+        workflowName: "ralph",
+        agent: "claude",
+        prompt: "hello",
+        fatalError: null,
+        completionReached: false,
+        sessions: [session("orchestrator", "running")],
+      });
+
+      await writeSnapshot(dir, snap);
+      const back = await readSnapshot(dir);
+      expect(back).not.toBeNull();
+      expect(back!.workflowRunId).toBe("abcd1234");
+      expect(back!.overall).toBe("in_progress");
+      expect(back!.sessions).toHaveLength(1);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns null when status.json does not exist", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      const back = await readSnapshot(dir);
+      expect(back).toBeNull();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns null when status.json is malformed JSON", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      await Bun.write(join(dir, "status.json"), "not-json");
+      const back = await readSnapshot(dir);
+      expect(back).toBeNull();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns null when status.json fails the snapshot shape guard", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      await Bun.write(
+        join(dir, "status.json"),
+        JSON.stringify({ schemaVersion: 99, foo: "bar" }),
+      );
+      const back = await readSnapshot(dir);
+      expect(back).toBeNull();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});