@bastani/atomic 0.5.21 → 0.5.22-0

package/src/commands/cli/claude-stop-hook.test.ts

@@ -2,22 +2,27 @@
  * Tests for claudeStopHookCommand.
  *
  * Strategy: monkey-patch `Bun.stdin.text` to return preset strings so we can
- * call the function directly without spawning subprocesses.  This is
+ * call the function directly without spawning subprocesses. This is
  * consistent with how other CLI-command tests in this directory work.
  *
  * Filesystem isolation: we use `crypto.randomUUID()` for unique session IDs
  * and clean up in `afterEach` so test runs never collide with each other
- * or with real marker files.
+ * or with real marker/queue/release files.
+ *
+ * The hook's default wait for a queued follow-up prompt is 15 minutes.
+ * Every test here passes a short `waitTimeoutMs` so the hook exits quickly
+ * when no queue entry is present — we are testing the branching logic,
+ * not the real-world wait budget.
  */
 
-import { describe, test, expect, afterEach, mock, spyOn } from "bun:test";
-import { access, rm } from "node:fs/promises";
+import { describe, test, expect, afterEach, spyOn } from "bun:test";
+import { access, rm, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { homedir } from "node:os";
-import { claudeStopHookCommand } from "./claude-stop-hook.ts";
+import { claudeStopHookCommand, claudeHookDirs } from "./claude-stop-hook.ts";
+
+const { marker: markerDir, queue: queueDir, release: releaseDir } = claudeHookDirs();
 
-// Paths we'll need in every test.
-const markerDir = join(homedir(), ".atomic", "claude-stop");
+const SHORT_TIMEOUT_MS = 300;
 
 /** Returns true when a file exists at `filePath`. */
 async function fileExists(filePath: string): Promise<boolean> {
@@ -31,9 +36,6 @@ async function fileExists(filePath: string): Promise<boolean> {
 
 /** Patch `Bun.stdin.text` for the duration of one test. */
 function mockStdin(text: string): void {
-  // Bun.stdin is a readonly property on the global `Bun` object.
-  // We reach it through the prototype chain the same way other tests
-  // in this repo patch globals (e.g. process.stdout.write).
   (Bun.stdin as { text: () => Promise<string> }).text = () =>
     Promise.resolve(text);
 }
@@ -45,10 +47,12 @@ function mockStdin(text: string): void {
 const sessionIdsToClean: string[] = [];
 
 afterEach(async () => {
-  // Remove any marker files created during the test.
   for (const id of sessionIdsToClean) {
-    await rm(join(markerDir, id), { force: true });
-    await rm(join(markerDir, `${id}.tmp`), { force: true });
+    await Promise.all([
+      rm(join(markerDir, id), { force: true }),
+      rm(join(queueDir, id), { force: true }),
+      rm(join(releaseDir, id), { force: true }),
+    ]);
   }
   sessionIdsToClean.length = 0;
 });
@@ -65,37 +69,63 @@ describe("claudeStopHookCommand", () => {
 
     mockStdin(JSON.stringify({ session_id: sessionId }));
 
-    const code = await claudeStopHookCommand();
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
 
     expect(code).toBe(0);
     expect(await fileExists(join(markerDir, sessionId))).toBe(true);
+    // No .tmp file should ever be created — we write directly to final path.
     expect(await fileExists(join(markerDir, `${sessionId}.tmp`))).toBe(false);
   });
 
-  // 2. stop_hook_active: true → no-op
-  test("stop_hook_active:true is a no-op and returns 0", async () => {
+  // 2. stop_hook_active: true still writes marker and polls the queue
+  //
+  // Claude Code sets `stopHookActive: true` on every Stop hook invocation
+  // after a prior `{decision:"block"}` response (see `src/query.ts` →
+  // `transition: { reason: 'stop_hook_blocking' }`). Multi-turn workflows
+  // therefore see `stop_hook_active=true` on every turn past the first. The
+  // hook must still write the marker so `waitForIdle` unblocks, and must
+  // still poll for queued follow-ups so the next `s.session.query(...)` can
+  // reach Claude.
+  test("stop_hook_active:true still writes marker and polls the queue", async () => {
     const sessionId = crypto.randomUUID();
     sessionIdsToClean.push(sessionId);
 
+    const queuedPrompt = "Third turn follow-up";
+    await mkdir(queueDir, { recursive: true });
+    await writeFile(join(queueDir, sessionId), queuedPrompt, "utf-8");
+
     mockStdin(
       JSON.stringify({ session_id: sessionId, stop_hook_active: true }),
     );
 
-    const code = await claudeStopHookCommand();
+    const stdoutChunks: string[] = [];
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(
+      (chunk: unknown) => {
+        stdoutChunks.push(String(chunk));
+        return true;
+      },
+    );
+
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
+
+    stdoutSpy.mockRestore();
 
     expect(code).toBe(0);
-    expect(await fileExists(join(markerDir, sessionId))).toBe(false);
-    expect(await fileExists(join(markerDir, `${sessionId}.tmp`))).toBe(false);
+    // Marker must be written so waitForIdle unblocks on every turn.
+    expect(await fileExists(join(markerDir, sessionId))).toBe(true);
+    // Queue entry consumed and emitted as a block decision.
+    expect(await fileExists(join(queueDir, sessionId))).toBe(false);
+    const parsed: unknown = JSON.parse(stdoutChunks.join(""));
+    expect(parsed).toEqual({ decision: "block", reason: queuedPrompt });
   });
 
   // 3. Malformed JSON → returns 0, logs to console.error
   test("malformed JSON returns 0 and logs an error", async () => {
     mockStdin("not json {{{");
 
-    // Spy on console.error so the error doesn't bleed into test output.
     const errorSpy = spyOn(console, "error").mockImplementation(() => {});
 
-    const code = await claudeStopHookCommand();
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
 
     expect(code).toBe(0);
     expect(errorSpy).toHaveBeenCalled();
@@ -109,7 +139,7 @@ describe("claudeStopHookCommand", () => {
 
     const errorSpy = spyOn(console, "error").mockImplementation(() => {});
 
-    const code = await claudeStopHookCommand();
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
 
     expect(code).toBe(0);
     expect(errorSpy).toHaveBeenCalled();
@@ -131,10 +161,111 @@ describe("claudeStopHookCommand", () => {
       }),
     );
 
-    const code = await claudeStopHookCommand();
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
 
     expect(code).toBe(0);
     expect(await fileExists(join(markerDir, sessionId))).toBe(true);
     expect(await fileExists(join(markerDir, `${sessionId}.tmp`))).toBe(false);
   });
+
+  // 6. Queue file present at entry → emit block+reason, consume queue
+  test("queued prompt is emitted as a block decision and the queue file is consumed", async () => {
+    const sessionId = crypto.randomUUID();
+    sessionIdsToClean.push(sessionId);
+
+    const queuedPrompt = "Now translate your previous greeting into pig latin.";
+    await mkdir(queueDir, { recursive: true });
+    await writeFile(join(queueDir, sessionId), queuedPrompt, "utf-8");
+
+    mockStdin(JSON.stringify({ session_id: sessionId }));
+
+    const stdoutChunks: string[] = [];
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(
+      (chunk: unknown) => {
+        stdoutChunks.push(String(chunk));
+        return true;
+      },
+    );
+
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
+
+    stdoutSpy.mockRestore();
+
+    expect(code).toBe(0);
+    // Marker still written, since the workflow's waitForIdle depends on it.
+    expect(await fileExists(join(markerDir, sessionId))).toBe(true);
+    // Queue entry consumed.
+    expect(await fileExists(join(queueDir, sessionId))).toBe(false);
+    // Block decision emitted with the queued prompt as `reason`.
+    const emitted = stdoutChunks.join("");
+    const parsed: unknown = JSON.parse(emitted);
+    expect(parsed).toEqual({ decision: "block", reason: queuedPrompt });
+  });
+
+  // 7. Queue file appears during wait → still consumed and emitted
+  test("queue file written during the wait is consumed and emitted", async () => {
+    const sessionId = crypto.randomUUID();
+    sessionIdsToClean.push(sessionId);
+
+    const queuedPrompt = "Follow-up written mid-wait";
+
+    mockStdin(JSON.stringify({ session_id: sessionId }));
+
+    const stdoutChunks: string[] = [];
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(
+      (chunk: unknown) => {
+        stdoutChunks.push(String(chunk));
+        return true;
+      },
+    );
+
+    // Kick the hook off, then write the queue file partway through its wait.
+    const hookPromise = claudeStopHookCommand({
+      waitTimeoutMs: 2_000,
+      pollIntervalMs: 25,
+    });
+
+    await Bun.sleep(120);
+    await mkdir(queueDir, { recursive: true });
+    await writeFile(join(queueDir, sessionId), queuedPrompt, "utf-8");
+
+    const code = await hookPromise;
+    stdoutSpy.mockRestore();
+
+    expect(code).toBe(0);
+    expect(await fileExists(join(queueDir, sessionId))).toBe(false);
+    const parsed: unknown = JSON.parse(stdoutChunks.join(""));
+    expect(parsed).toEqual({ decision: "block", reason: queuedPrompt });
+  });
+
+  // 8. Release file present → exit 0, no stdout, consume release
+  test("release file lets the hook exit promptly without a decision", async () => {
+    const sessionId = crypto.randomUUID();
+    sessionIdsToClean.push(sessionId);
+
+    await mkdir(releaseDir, { recursive: true });
+    await writeFile(join(releaseDir, sessionId), "", "utf-8");
+
+    mockStdin(JSON.stringify({ session_id: sessionId }));
+
+    const stdoutChunks: string[] = [];
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(
+      (chunk: unknown) => {
+        stdoutChunks.push(String(chunk));
+        return true;
+      },
+    );
+
+    const code = await claudeStopHookCommand({ waitTimeoutMs: SHORT_TIMEOUT_MS });
+
+    stdoutSpy.mockRestore();
+
+    expect(code).toBe(0);
+    // Release consumed so it doesn't carry over.
+    expect(await fileExists(join(releaseDir, sessionId))).toBe(false);
+    // Marker still written.
+    expect(await fileExists(join(markerDir, sessionId))).toBe(true);
+    // No block decision emitted.
+    expect(stdoutChunks.join("")).toBe("");
+  });
 });

package/src/commands/cli/claude-stop-hook.ts

@@ -2,9 +2,19 @@
  * Claude Stop Hook command — internal handler for Claude Code's Stop hook.
  *
  * Claude invokes `atomic _claude-stop-hook` at the end of every turn,
- * piping a JSON payload via stdin. This handler writes a marker file that
- * another part of the system watches via `fs.watch`, replacing tmux-pane-
- * scraping idle detection with a clean event-driven approach.
+ * piping a JSON payload via stdin. This handler has two jobs:
+ *
+ *   1. Write a per-session marker file that the workflow runtime watches via
+ *      `fs.watch` to detect turn completion (replacing tmux-pane scraping).
+ *
+ *   2. Deliver follow-up prompts without tmux send-keys. After the marker is
+ *      written, this process block-polls `~/.atomic/claude-queue/<session_id>`.
+ *      If the workflow enqueues a prompt there, we read it, delete the queue
+ *      entry, and emit `{"decision":"block","reason":<prompt>}` on stdout.
+ *      Claude Code treats `reason` as the next user message and keeps the
+ *      agent loop running on the same session — no TUI keystrokes required.
+ *      If the workflow instead signals session end via
+ *      `~/.atomic/claude-release/<session_id>`, we exit 0 and let Claude stop.
  *
  * Usage (configured in Claude's Stop hook):
  *   atomic _claude-stop-hook
@@ -19,6 +29,7 @@
  */
 
 import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 
@@ -43,6 +54,32 @@ function isClaudeStopHookPayload(value: unknown): value is ClaudeStopHookPayload
   return true;
 }
 
+/**
+ * Directory paths used by the Stop hook and the workflow runtime to exchange
+ * per-session signals.
+ *
+ * Exported so tests and `src/sdk/providers/claude.ts` share one source of truth.
+ */
+export function claudeHookDirs(): { marker: string; queue: string; release: string } {
+  const base = path.join(os.homedir(), ".atomic");
+  return {
+    marker: path.join(base, "claude-stop"),
+    queue: path.join(base, "claude-queue"),
+    release: path.join(base, "claude-release"),
+  };
+}
+
+/** Options for {@link claudeStopHookCommand}. Primarily used by tests to shrink the wait budget. */
+export interface ClaudeStopHookOptions {
+  /** Maximum time the hook waits for a queued follow-up prompt before letting Claude stop. */
+  waitTimeoutMs?: number;
+  /** Polling interval for queue/release detection. */
+  pollIntervalMs?: number;
+}
+
+const DEFAULT_WAIT_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+
 /**
  * Handler for the hidden `_claude-stop-hook` subcommand.
  *
@@ -52,7 +89,12 @@ function isClaudeStopHookPayload(value: unknown): value is ClaudeStopHookPayload
  * We always return 0 — a non-zero exit would surface as a hook error in
  * Claude's transcript, which is not what we want.
  */
-export async function claudeStopHookCommand(): Promise<number> {
+export async function claudeStopHookCommand(
+  options: ClaudeStopHookOptions = {},
+): Promise<number> {
+  const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
   // 1. Read stdin
   const raw = await Bun.stdin.text();
 
@@ -70,21 +112,85 @@ export async function claudeStopHookCommand(): Promise<number> {
     return 0;
   }
 
-  // 3. Guard against infinite Stop-hook loops
-  if (payload.stop_hook_active === true) {
-    return 0;
-  }
+  // NOTE: we intentionally do NOT early-exit on `stop_hook_active === true`.
+  //
+  // Claude Code sets `stopHookActive: true` in its query state after any Stop
+  // hook returns a `{decision:"block"}` response, and that flag stays true for
+  // every subsequent Stop hook invocation in the same session (see
+  // `src/query.ts` → `transition: { reason: 'stop_hook_blocking' }`). In a
+  // multi-turn workflow, every follow-up turn after the first is therefore
+  // invoked with `stop_hook_active=true`. Returning early here would skip the
+  // marker write, leaving `waitForIdle` hanging until its 15-minute safety
+  // timeout, and would skip the queue poll so the workflow's next
+  // `s.session.query(...)` would never reach Claude.
+  //
+  // Our design doesn't need the generic loop guard: the hook only emits a
+  // `block` decision when the workflow runtime has written a prompt to the
+  // queue file. Infinite loops are bounded by the workflow (which either
+  // enqueues a finite number of prompts or writes a release marker on
+  // teardown via `clearClaudeSession`).
+  const dirs = claudeHookDirs();
+  await Promise.all([
+    fs.mkdir(dirs.marker, { recursive: true }),
+    fs.mkdir(dirs.queue, { recursive: true }),
+    fs.mkdir(dirs.release, { recursive: true }),
+  ]);
 
-  // 4. Write the marker file atomically
-  const markerDir = path.join(os.homedir(), ".atomic", "claude-stop");
-  await fs.mkdir(markerDir, { recursive: true });
+  // 4. Write the marker file directly.
+  //
+  // We intentionally do NOT use a tmp+rename dance here. On Linux, inotify
+  // emits the rename event with `filename=<session_id>.tmp` (the source),
+  // which made `waitForIdle`'s `event.filename === session_id` filter miss
+  // the event entirely and hang forever. A direct write on a tiny payload is
+  // effectively atomic at the page-cache level and generates a single event
+  // whose filename matches the session id — which is all `waitForIdle` needs.
+  const markerPath = path.join(dirs.marker, payload.session_id);
+  await Bun.write(markerPath, raw);
 
-  const tmpPath = path.join(markerDir, `${payload.session_id}.tmp`);
-  const finalPath = path.join(markerDir, payload.session_id);
+  // 5. Block-poll for either a queued follow-up prompt or a release signal.
+  //
+  // The workflow's `waitForIdle` has already been unblocked by the marker
+  // write above and is now returning control to the user's stage callback.
+  // One of three things happens next:
+  //
+  //   a. The callback calls `s.session.query(next)`, which writes the next
+  //      prompt to `~/.atomic/claude-queue/<session_id>`. We read it, delete
+  //      the queue entry, and emit `{"decision":"block","reason":<prompt>}`
+  //      on stdout. Claude Code feeds `reason` back as the next user message
+  //      and keeps the turn loop running — no tmux keystrokes involved.
+  //
+  //   b. The callback returns and the runtime writes a release marker at
+  //      `~/.atomic/claude-release/<session_id>`. We exit 0 with no stdout
+  //      payload and Claude stops as usual.
+  //
+  //   c. Neither happens within `waitTimeoutMs`. We exit 0 on timeout as a
+  //      safety net — Claude stops rather than hanging its Stop hook forever.
+  const queuePath = path.join(dirs.queue, payload.session_id);
+  const releasePath = path.join(dirs.release, payload.session_id);
 
-  // Write contents — the watcher only cares that the file appears.
-  await Bun.write(tmpPath, raw);
-  await fs.rename(tmpPath, finalPath);
+  const deadline = Date.now() + waitTimeoutMs;
+  while (Date.now() <= deadline) {
+    if (existsSync(releasePath)) {
+      try { await fs.unlink(releasePath); } catch { /* ENOENT is fine */ }
+      return 0;
+    }
+    if (existsSync(queuePath)) {
+      let prompt: string;
+      try {
+        prompt = await fs.readFile(queuePath, "utf-8");
+      } catch {
+        return 0;
+      }
+      try { await fs.unlink(queuePath); } catch { /* ENOENT is fine */ }
+      process.stdout.write(JSON.stringify({
+        decision: "block",
+        reason: prompt,
+      }));
+      return 0;
+    }
+    await Bun.sleep(pollIntervalMs);
+  }
 
+  // Timeout — no queued prompt arrived. Let Claude stop normally.
   return 0;
 }

package/src/commands/cli/workflow.ts

@@ -14,6 +14,9 @@ import { AGENT_CONFIG, type AgentKey } from "../../services/config/index.ts";
 import { COLORS, createPainter, type PaletteKey } from "../../theme/colors.ts";
 import { isCommandInstalled } from "../../services/system/detect.ts";
 import { ensureTmuxInstalled, ensureBunInstalled } from "../../lib/spawn.ts";
+import { ensureProjectSetup } from "./init/index.ts";
+import { ensureAtomicGlobalAgentConfigs } from "../../services/config/atomic-global-config.ts";
+import { getConfigRoot } from "../../services/config/config-path.ts";
 import {
   isTmuxInstalled,
   discoverWorkflows,
@@ -264,6 +267,13 @@ export async function workflowCommand(options: {
   const preflightCode = await runPrereqChecks(agent);
   if (preflightCode !== 0) return preflightCode;
 
+  // ── Preflight: global config sync + project onboarding files ──
+  // Mirrors `atomic chat` so workflow runs see the same MCP configs,
+  // agent settings, and global agent folders the chat command auto-heals.
+  const projectRoot = cwd ?? process.cwd();
+  await ensureAtomicGlobalAgentConfigs(getConfigRoot());
+  await ensureProjectSetup(agent, projectRoot);
+
   // ── Picker mode: -a <agent>, no -n ──
   if (!options.name) {
     return runPickerMode(agent, passthroughArgs, cwd, detach);