@bastani/atomic 0.5.20 → 0.5.21-1

package/src/sdk/components/workflow-picker-panel.tsx

@@ -42,7 +42,10 @@ import { useState, useEffect, useMemo, useRef, useCallback, useContext, createCo
 import { useLatest } from "./hooks.ts";
 import { resolveTheme, type TerminalTheme } from "../runtime/theme.ts";
 import type { AgentType, WorkflowInput } from "../types.ts";
-import type { WorkflowWithMetadata } from "../runtime/discovery.ts";
+import type {
+  WorkflowWithMetadata,
+  WorkflowMetadataStatus,
+} from "../runtime/discovery.ts";
 import { ErrorBoundary } from "./error-boundary.tsx";
 
 // ─── Theme ──────────────────────────────────────
@@ -258,6 +261,38 @@ export function buildRows(entries: ListEntry[], query: string): ListRow[] {
   return rows;
 }
 
+// ─── Status helpers ─────────────────────────────
+// Non-ok entries stay visible in the picker so the user sees that a
+// workflow from an older SDK release (or one with a load error) still
+// exists on disk — the previous behaviour silently dropped them, which
+// made user/global workflows appear to vanish after an atomic upgrade.
+
+/** Unicode glyph that prefixes a non-ok entry and heads its preview. */
+const STATUS_ICON: Record<WorkflowMetadataStatus["kind"], string> = {
+  ok: " ",
+  incompatible: "⚠",
+  error: "✗",
+};
+
+/** Compact single-word label used in list rows and the bottom hint. */
+const STATUS_LABEL: Record<WorkflowMetadataStatus["kind"], string> = {
+  ok: "",
+  incompatible: "update",
+  error: "broken",
+};
+
+/** Map each status kind to its semantic palette slot. */
+const STATUS_COLOR: Record<WorkflowMetadataStatus["kind"], keyof PickerTheme> = {
+  ok: "success",
+  incompatible: "warning",
+  error: "error",
+};
+
+/** Non-ok rows are inert — Enter / run commands must not transition the picker. */
+function isRunnable(wf: WorkflowWithMetadata): boolean {
+  return wf.status.kind === "ok";
+}
+
 // ─── Validation ─────────────────────────────────
 
 export function isFieldValid(field: WorkflowInput, value: string): boolean {
@@ -385,6 +420,24 @@ const WorkflowList = memo(function WorkflowList({
         const entryIdx = entryIndexByRow.get(i) ?? -1;
         const isFocused = entryIdx === focusedEntryIdx;
         const wf = row.entry.workflow;
+        const statusKind = wf.status.kind;
+        const runnable = statusKind === "ok";
+        // Status indicator sits between the focus marker and the name so
+        // every row shares a 4-character gutter — ok rows render a blank
+        // gutter, so the list stays visually flush while non-ok rows
+        // always occupy a fixed slot (no layout jitter when filtering).
+        const statusIcon = STATUS_ICON[statusKind];
+        const statusCol = theme[STATUS_COLOR[statusKind]];
+        // Non-ok rows fade the name so the "diagnostic, not selectable"
+        // read is immediate even when the user hasn't reached the row
+        // yet — the eye catches the warning glyph + dim text together.
+        const nameCol = runnable
+          ? isFocused
+            ? theme.text
+            : theme.textMuted
+          : isFocused
+            ? theme.textMuted
+            : theme.textDim;
 
         return (
           <box
@@ -399,7 +452,10 @@ const WorkflowList = memo(function WorkflowList({
               <span fg={isFocused ? theme.primary : theme.textDim}>
                 {isFocused ? "▸ " : "  "}
               </span>
-              <span fg={isFocused ? theme.text : theme.textMuted}>
+              <span fg={statusCol}>
+                {statusIcon + " "}
+              </span>
+              <span fg={nameCol}>
                 {wf.name}
               </span>
             </text>
@@ -459,6 +515,59 @@ const ArgumentRow = memo(function ArgumentRow({
   );
 });
 
+/**
+ * Diagnostic block for non-ok workflows. Replaces the description +
+ * arguments sections in the preview pane so the user sees *why* a row
+ * is inert and what to do about it, instead of an empty-looking panel.
+ */
+const StatusDiagnostic = memo(function StatusDiagnostic({
+  status,
+}: {
+  status: Exclude<WorkflowMetadataStatus, { kind: "ok" }>;
+}) {
+  const theme = usePickerTheme();
+  const color = theme[STATUS_COLOR[status.kind]];
+  const icon = STATUS_ICON[status.kind];
+
+  // Headline + sub-copy split: the headline is terse (three words) so
+  // it reads at a glance even on a narrow right pane; the sub-copy
+  // explains *why* and the third paragraph tells the user what to do.
+  const headline =
+    status.kind === "incompatible"
+      ? "update required"
+      : "failed to load";
+  const detail =
+    status.kind === "incompatible"
+      ? `Needs Atomic v${status.requiredVersion}. Installed: v${status.currentVersion}.`
+      : status.message;
+  const remediation =
+    status.kind === "incompatible"
+      ? "Update Atomic, or re-save the workflow against the current SDK."
+      : "Open the workflow file and fix the error above.";
+
+  return (
+    <box flexDirection="column">
+      <text>
+        <span fg={color}>
+          <strong>{icon + " " + headline}</strong>
+        </span>
+      </text>
+
+      <box height={1} />
+
+      <text>
+        <span fg={theme.textMuted}>{detail}</span>
+      </text>
+
+      <box height={1} />
+
+      <text>
+        <span fg={theme.textDim}>{remediation}</span>
+      </text>
+    </box>
+  );
+});
+
 const Preview = memo(function Preview({
   wf,
 }: {
@@ -466,6 +575,7 @@ const Preview = memo(function Preview({
 }) {
   const theme = usePickerTheme();
   const args = wf.inputs;
+  const status = wf.status;
 
   return (
     <box
@@ -493,21 +603,27 @@ const Preview = memo(function Preview({
 
       <box height={2} />
 
-      <text>
-        <span fg={theme.textMuted}>
-          {wf.description || "(no description)"}
-        </span>
-      </text>
-
-      {args.length > 0 && (
+      {status.kind === "ok" ? (
         <>
-          <box height={2} />
-          <SectionLabel label="ARGUMENTS" />
-          <box height={1} />
-          {args.map((f) => (
-            <ArgumentRow key={f.name} field={f} />
-          ))}
+          <text>
+            <span fg={theme.textMuted}>
+              {wf.description || "(no description)"}
+            </span>
+          </text>
+
+          {args.length > 0 && (
+            <>
+              <box height={2} />
+              <SectionLabel label="ARGUMENTS" />
+              <box height={1} />
+              {args.map((f) => (
+                <ArgumentRow key={f.name} field={f} />
+              ))}
+            </>
+          )}
         </>
+      ) : (
+        <StatusDiagnostic status={status} />
       )}
     </box>
   );
@@ -1022,6 +1138,14 @@ const PICK_HINTS: Hint[] = [
   { key: "↵", label: "select" },
   { key: "esc", label: "quit" },
 ];
+// Shown instead of PICK_HINTS when the focused row is non-ok — the dim
+// `↵ unavailable` reads immediately as "this row is navigable but not
+// runnable", which matches the muted row colour and preview diagnostic.
+const PICK_HINTS_UNAVAILABLE: Hint[] = [
+  { key: "↑↓", label: "navigate" },
+  { key: "↵", label: "unavailable", dim: true },
+  { key: "esc", label: "quit" },
+];
 const CONFIRM_HINTS: Hint[] = [
   { key: "y", label: "submit" },
   { key: "n", label: "cancel" },
@@ -1134,7 +1258,26 @@ const Statusline = memo(function Statusline({
       {focusedWf ? (
         <box paddingLeft={1} paddingRight={1} alignItems="center">
           <text>
-            <span fg={theme.text}>{focusedWf.name}</span>
+            {focusedWf.status.kind !== "ok" ? (
+              <span fg={theme[STATUS_COLOR[focusedWf.status.kind]]}>
+                {STATUS_ICON[focusedWf.status.kind] + " "}
+              </span>
+            ) : null}
+            <span
+              fg={
+                focusedWf.status.kind === "ok" ? theme.text : theme.textMuted
+              }
+            >
+              {focusedWf.name}
+            </span>
+            {focusedWf.status.kind !== "ok" ? (
+              <>
+                <span fg={theme.textDim}>{"  ·  "}</span>
+                <span fg={theme[STATUS_COLOR[focusedWf.status.kind]]}>
+                  {STATUS_LABEL[focusedWf.status.kind]}
+                </span>
+              </>
+            ) : null}
           </text>
         </box>
       ) : null}
@@ -1247,7 +1390,10 @@ function usePickerKeyboard(state: PickerKeyboardState): void {
     if (key.name === "return") {
       key.stopPropagation();
       const wf = focusedWfRef.current;
-      if (wf) {
+      // Silently swallow Enter on incompatible / broken entries — the
+      // preview pane already explains the failure; advancing into the
+      // prompt phase would be misleading since the workflow can't run.
+      if (wf && isRunnable(wf)) {
         const initial: Record<string, string> = {};
         for (const f of wf.inputs) {
           initial[f.name] =
@@ -1408,10 +1554,13 @@ export function WorkflowPicker({
     setConfirmOpen,
   });
 
+  const focusedIsRunnable = focusedWf ? isRunnable(focusedWf) : true;
   const hints = confirmOpen
     ? CONFIRM_HINTS
     : phase === "pick"
-      ? PICK_HINTS
+      ? focusedIsRunnable
+        ? PICK_HINTS
+        : PICK_HINTS_UNAVAILABLE
       : isFormValid
         ? PROMPT_HINTS_VALID
         : PROMPT_HINTS_INVALID;

package/src/sdk/define-workflow.ts

@@ -152,6 +152,7 @@ export class WorkflowBuilder<A extends AgentType = AgentType, N extends string =
       name: this.options.name,
       description: this.options.description ?? "",
       inputs,
+      minSDKVersion: this.options.minSDKVersion ?? null,
       run: runFn,
     };
   }

package/src/sdk/errors.ts

@@ -38,6 +38,26 @@ export class InvalidWorkflowError extends Error {
   }
 }
 
+/**
+ * Thrown when a workflow declares a `minSDKVersion` newer than the
+ * bundled CLI. Carries both versions so the CLI can render an
+ * actionable "update atomic or re-save the workflow" hint rather than
+ * a generic load error.
+ */
+export class IncompatibleSDKError extends Error {
+  constructor(
+    public readonly path: string,
+    public readonly requiredVersion: string,
+    public readonly currentVersion: string,
+  ) {
+    super(
+      `${path} requires Atomic SDK v${requiredVersion}, but v${currentVersion} is installed.\n` +
+      `  Update Atomic, or re-save the workflow against the current SDK.`,
+    );
+    this.name = "IncompatibleSDKError";
+  }
+}
+
 /** Extract a human-readable message from an unknown thrown value. */
 export function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);

package/src/sdk/runtime/discovery.ts

@@ -17,6 +17,7 @@ import { homedir } from "node:os";
 import ignore from "ignore";
 import type { AgentType, WorkflowInput } from "../types.ts";
 import { WorkflowLoader } from "./loader.ts";
+import { IncompatibleSDKError } from "../errors.ts";
 
 export interface DiscoveredWorkflow {
   name: string;
@@ -248,47 +249,120 @@ export async function findWorkflow(
   return all.find((w) => w.name === name) ?? null;
 }
 
+/**
+ * Load status for a {@link WorkflowWithMetadata} entry.
+ *
+ * - `ok`            — the workflow compiled cleanly and is ready to run.
+ * - `incompatible`  — the workflow declared a `minSDKVersion` newer
+ *                     than the bundled CLI. The CLI renders it with an
+ *                     "update required" badge so users see the mismatch
+ *                     rather than a silent disappearance.
+ * - `error`         — any other load failure (syntax error, missing
+ *                     `.compile()`, invalid default export, etc.).
+ *                     Rendered with a "failed to load" badge plus the
+ *                     underlying message.
+ */
+export type WorkflowMetadataStatus =
+  | { kind: "ok" }
+  | {
+      kind: "incompatible";
+      requiredVersion: string;
+      currentVersion: string;
+      message: string;
+    }
+  | {
+      kind: "error";
+      stage: "resolve" | "validate" | "load";
+      message: string;
+    };
+
 /**
  * A discovered workflow enriched with the metadata the picker needs to
- * render it: the human description and the declared input schema.
+ * render it: the human description, the declared input schema, and the
+ * load status.
  *
  * Populated by {@link loadWorkflowsMetadata}, which runs each discovered
- * workflow through {@link WorkflowLoader.loadWorkflow} and extracts just
- * the display-relevant fields — the full compiled definition is
- * discarded after extraction so re-imports during execution are cheap.
+ * workflow through {@link WorkflowLoader.loadWorkflow} and extracts the
+ * display-relevant fields — the full compiled definition is discarded
+ * after extraction so re-imports during execution are cheap.
+ *
+ * Broken entries still materialise with empty `description` / `inputs`
+ * and a non-`ok` {@link status}, so the picker can render them as
+ * visible "update required" / "failed to load" rows instead of
+ * silently omitting them (the previous behaviour, which made user and
+ * global workflows vanish whenever the base SDK shape drifted between
+ * releases).
  */
 export interface WorkflowWithMetadata extends DiscoveredWorkflow {
-  /** Workflow description, empty string when none was declared. */
+  /** Workflow description, empty string when none was declared or the workflow failed to load. */
   description: string;
-  /** Picker-ready input schema; free-form workflows materialize a prompt field. */
+  /** Picker-ready input schema; empty for free-form or failed-to-load workflows. */
   inputs: readonly WorkflowInput[];
+  /** Load outcome — non-`ok` entries are rendered as visible diagnostics in the picker/list. */
+  status: WorkflowMetadataStatus;
 }
 
 /**
- * Load metadata (description + picker-ready inputs) for a batch of discovered workflows.
+ * Load metadata (description + picker-ready inputs + status) for a batch
+ * of discovered workflows.
  *
- * Workflows that fail to import are **skipped silently** so one broken
- * entry can never prevent the picker from rendering. Callers that need
- * to surface load errors (e.g. `atomic workflow -n broken`) should use
- * {@link WorkflowLoader.loadWorkflow} directly — that path produces
- * structured error reports.
+ * **Failed workflows are kept in the returned list**, not dropped. Each
+ * broken entry carries a {@link WorkflowMetadataStatus} explaining the
+ * failure so the picker and `atomic workflow -l` can surface it as an
+ * actionable diagnostic. This is the only way end users discover that a
+ * workflow from an older SDK release has gone incompatible after an
+ * `atomic` upgrade — silent filtering would leave them with a missing
+ * entry and no breadcrumb.
+ *
+ * Callers that want to execute a workflow should still route through
+ * {@link WorkflowLoader.loadWorkflow} — this function throws away the
+ * compiled definition so re-running the loader on a confirmed pick is
+ * unavoidable.
  */
 export async function loadWorkflowsMetadata(
   discovered: DiscoveredWorkflow[],
 ): Promise<WorkflowWithMetadata[]> {
-  const results = await Promise.all(
-    discovered.map(async (wf): Promise<WorkflowWithMetadata | null> => {
+  return Promise.all(
+    discovered.map(async (wf): Promise<WorkflowWithMetadata> => {
       const loaded = await WorkflowLoader.loadWorkflow(wf);
-      if (!loaded.ok) return null;
+      if (loaded.ok) {
+        return {
+          ...wf,
+          description: loaded.value.definition.description,
+          inputs: loaded.value.definition.inputs,
+          status: { kind: "ok" },
+        };
+      }
+
+      // Incompatible SDK version is a first-class status so the UI can
+      // show a dedicated "update required" hint. Every other failure
+      // maps to a generic `error` variant — the picker renders the
+      // message but doesn't try to interpret it further.
+      if (loaded.error instanceof IncompatibleSDKError) {
+        return {
+          ...wf,
+          description: "",
+          inputs: [],
+          status: {
+            kind: "incompatible",
+            requiredVersion: loaded.error.requiredVersion,
+            currentVersion: loaded.error.currentVersion,
+            message: loaded.message,
+          },
+        };
+      }
+
       return {
         ...wf,
-        description: loaded.value.definition.description,
-        inputs: loaded.value.definition.inputs,
+        description: "",
+        inputs: [],
+        status: {
+          kind: "error",
+          stage: loaded.stage,
+          message: loaded.message,
+        },
       };
     }),
   );
-  return results.filter(
-    (r): r is WorkflowWithMetadata => r !== null,
-  );
 }
 

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/loader.ts

@@ -12,10 +12,17 @@
 
 import type { WorkflowDefinition, AgentType } from "../types.ts";
 import type { DiscoveredWorkflow } from "./discovery.ts";
-import { errorMessage, WorkflowNotCompiledError, InvalidWorkflowError } from "../errors.ts";
+import {
+  errorMessage,
+  WorkflowNotCompiledError,
+  InvalidWorkflowError,
+  IncompatibleSDKError,
+} from "../errors.ts";
 import { validateCopilotWorkflow } from "../providers/copilot.ts";
 import { validateOpenCodeWorkflow } from "../providers/opencode.ts";
 import { validateClaudeWorkflow } from "../providers/claude.ts";
+import { satisfiesMinVersion } from "./version-compat.ts";
+import { VERSION } from "../../version.ts";
 
 export namespace WorkflowLoader {
   // ---------------------------------------------------------------------------
@@ -180,9 +187,29 @@ export namespace WorkflowLoader {
         };
       }
 
+      const def = definition as WorkflowDefinition;
+
+      // Refuse workflows whose declared minSDKVersion is newer than the
+      // bundled CLI — the workflow author opted in to a version gate
+      // exactly so the loader could surface a clear upgrade hint
+      // instead of letting a shape-drift error bubble up at run time.
+      if (!satisfiesMinVersion(VERSION, def.minSDKVersion)) {
+        const err = new IncompatibleSDKError(
+          validated.path,
+          def.minSDKVersion ?? "",
+          VERSION,
+        );
+        return {
+          ok: false,
+          stage: "load",
+          error: err,
+          message: err.message,
+        };
+      }
+
       return {
         ok: true,
-        value: { ...validated, definition: definition as WorkflowDefinition },
+        value: { ...validated, definition: def },
       };
     } catch (error) {
       return {