@bastani/atomic 0.5.20 → 0.5.21-1

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/commands/cli/workflow.test.ts

@@ -6,7 +6,10 @@ import {
   renderWorkflowList,
 } from "./workflow.ts";
 import type { WorkflowInput } from "../../sdk/workflows/index.ts";
-import type { DiscoveredWorkflow } from "../../sdk/workflows/index.ts";
+import type {
+  DiscoveredWorkflow,
+  WorkflowWithMetadata,
+} from "../../sdk/workflows/index.ts";
 
 // ─── Colour handling ────────────────────────────────────────────────────────
 // The renderer emits ANSI sequences when the host terminal claims truecolor
@@ -190,12 +193,16 @@ function wf(
   name: string,
   agent: DiscoveredWorkflow["agent"],
   source: DiscoveredWorkflow["source"],
-): DiscoveredWorkflow {
+  status: WorkflowWithMetadata["status"] = { kind: "ok" },
+): WorkflowWithMetadata {
   return {
     name,
     agent,
     source,
     path: `/tmp/fake/${source}/${name}/${agent}/index.ts`,
+    description: "",
+    inputs: [],
+    status,
   };
 }
 
@@ -216,7 +223,7 @@ describe("renderWorkflowList", () => {
   });
 
   test("groups entries by source → provider and sorts names", () => {
-    const workflows: DiscoveredWorkflow[] = [
+    const workflows: WorkflowWithMetadata[] = [
       wf("zebra", "claude", "local"),
       wf("apple", "claude", "local"),
       wf("middle", "opencode", "local"),

package/src/commands/cli/workflow.ts

@@ -27,6 +27,7 @@ import type {
   AgentType,
   DiscoveredWorkflow,
   WorkflowInput,
+  WorkflowMetadataStatus,
   WorkflowWithMetadata,
 } from "../../sdk/workflows/index.ts";
 import { WorkflowPickerPanel } from "../../sdk/components/workflow-picker-panel.tsx";
@@ -227,8 +228,11 @@ export async function workflowCommand(options: {
       options.agent as AgentType | undefined,
       { merge: false },
     );
-    // Filter out workflows that fail to load (type errors, missing
-    // .compile(), etc.) so the list only shows workflows ready to run.
+    // Keep workflows that failed to load in the list — their status is
+    // surfaced inline as a "needs update" or "broken" tag so the user
+    // can see that a workflow still exists on disk even after an SDK
+    // bump invalidated it. Silent filtering was the original cause of
+    // the "workflow vanished after upgrade" report.
     const workflows = await loadWorkflowsMetadata(discovered);
     process.stdout.write(renderWorkflowList(workflows));
     return 0;
@@ -477,9 +481,13 @@ async function runNamedMode(
       `  ~/.atomic/workflows/${name}/${agent}/index.ts ${COLORS.dim}(global)${COLORS.reset}`,
     );
 
-    const available = await loadWorkflowsMetadata(
-      await discoverWorkflows(cwd, agent),
-    );
+    // Only suggest runnable alternatives — broken/incompatible workflows
+    // are visible via `atomic workflow -l` where their status is surfaced;
+    // listing them here would mask the real problem (the name the user
+    // typed does not exist) behind a dead-end suggestion.
+    const available = (
+      await loadWorkflowsMetadata(await discoverWorkflows(cwd, agent))
+    ).filter((w) => w.status.kind === "ok");
     if (available.length > 0) {
       console.error(`\nAvailable ${agent} workflows:`);
       for (const wf of available) {
@@ -608,6 +616,29 @@ const SOURCE_COLORS: Record<DiscoveredWorkflow["source"], PaletteKey> = {
   builtin: "info",  // sky    — ships with atomic, foundational
 };
 
+/**
+ * Per-row status badge shown in `atomic workflow -l` output. `ok` rows
+ * render with no badge (the list is already dense; flagging only
+ * non-ok rows keeps the happy path untouched). Incompatible rows
+ * include the required version so the user can compare at a glance;
+ * error rows stay terse and defer detail to `atomic workflow -n
+ * <name>` which surfaces the structured loader message.
+ */
+function renderStatusBadge(
+  paint: ReturnType<typeof createPainter>,
+  status: WorkflowMetadataStatus,
+): string {
+  if (status.kind === "ok") return "";
+  if (status.kind === "incompatible") {
+    return (
+      "  " +
+      paint("warning", "⚠ needs v" + status.requiredVersion) +
+      paint("dim", `  (installed v${status.currentVersion})`)
+    );
+  }
+  return "  " + paint("error", "✗ broken");
+}
+
 /**
  * Render `atomic workflow --list` output as a printable string.
  *
@@ -635,7 +666,7 @@ const SOURCE_COLORS: Record<DiscoveredWorkflow["source"], PaletteKey> = {
  * Exported for testing — the pure-function shape makes coverage for the
  * renderer trivial without spinning up a full CLI invocation.
  */
-export function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
+export function renderWorkflowList(workflows: WorkflowWithMetadata[]): string {
   const paint = createPainter();
   const lines: string[] = [];
 
@@ -653,9 +684,11 @@ export function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
     return lines.join("\n") + "\n";
   }
 
-  // Group by source → agent → sorted names. This gives the renderer O(1)
-  // lookups at both nesting levels and keeps the output deterministic.
-  type ByAgent = Map<AgentType, string[]>;
+  // Group by source → agent → sorted entries. Entries carry the full
+  // metadata (name + status) so the row renderer can append a status
+  // badge to non-ok rows without another lookup.
+  type EntrySummary = { name: string; status: WorkflowMetadataStatus };
+  type ByAgent = Map<AgentType, EntrySummary[]>;
   const bySource = new Map<DiscoveredWorkflow["source"], ByAgent>();
   for (const wf of workflows) {
     let byAgent = bySource.get(wf.source);
@@ -663,13 +696,13 @@ export function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
       byAgent = new Map();
       bySource.set(wf.source, byAgent);
     }
-    const names = byAgent.get(wf.agent) ?? [];
-    names.push(wf.name);
-    byAgent.set(wf.agent, names);
+    const entries = byAgent.get(wf.agent) ?? [];
+    entries.push({ name: wf.name, status: wf.status });
+    byAgent.set(wf.agent, entries);
   }
   for (const byAgent of bySource.values()) {
-    for (const names of byAgent.values()) {
-      names.sort((a, b) => a.localeCompare(b));
+    for (const entries of byAgent.values()) {
+      entries.sort((a, b) => a.name.localeCompare(b.name));
     }
   }
 
@@ -702,8 +735,8 @@ export function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
     );
 
     for (const agent of AGENT_ORDER) {
-      const names = byAgent.get(agent);
-      if (!names || names.length === 0) continue;
+      const entries = byAgent.get(agent);
+      if (!entries || entries.length === 0) continue;
 
       // Provider heading: bold accent blue — a clearly different layer from
       // both the semantic source heading above and the neutral entries below.
@@ -712,8 +745,14 @@ export function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
         "    " + paint("accent", AGENT_DISPLAY_NAMES[agent], { bold: true }),
       );
 
-      for (const name of names) {
-        lines.push("      " + paint("text", name));
+      for (const entry of entries) {
+        // Dim the name on non-ok rows so the eye lands on the status
+        // badge rather than the workflow name — the badge is where the
+        // actionable info lives, and the name is already unrunnable.
+        const nameCol: PaletteKey = entry.status.kind === "ok" ? "text" : "dim";
+        lines.push(
+          "      " + paint(nameCol, entry.name) + renderStatusBadge(paint, entry.status),
+        );
       }
     }
   }

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,
+    };
+  }
 }