@bastani/atomic 0.6.3-0 → 0.6.4-0

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

@@ -0,0 +1,359 @@
+/**
+ * Claude In-Flight Hook command — internal handler for the workflow's
+ * `SubagentStart` / `SubagentStop` / `TeammateIdle` hooks.
+ *
+ * Invoked as:
+ *   atomic _claude-inflight-hook start   (SubagentStart)
+ *   atomic _claude-inflight-hook stop    (SubagentStop)
+ *   atomic _claude-inflight-hook wait    (TeammateIdle)
+ *
+ * `start` / `stop` maintain a directory of one marker file per in-flight
+ * subagent under `~/.atomic/claude-inflight/<root_session_id>/<agent_id>`.
+ * `<root_session_id>` is the stage's top-level Claude session — for nested
+ * subagents (a subagent spawning its own subagent) we resolve the root by
+ * looking up the parent session's mapping, so all descendants of a stage
+ * funnel into the same marker dir.
+ *
+ * `wait` is the focused completion-signal handler used for `TeammateIdle`:
+ * read `session_id` from the payload, await `waitForInflightDrained`, exit
+ * 0. We don't reuse the Stop hook handler here because Stop also writes
+ * `~/.atomic/claude-stop/<session_id>` (which the runtime's `waitForIdle`
+ * watches) and polls queue/release — those are tied to the stage's root
+ * session, and TeammateIdle's `session_id` may be a teammate's session
+ * that the runtime never enqueues to or releases.
+ *
+ * Two consumers gate on the in-flight dir being empty:
+ *
+ *   1. `claudeStopHookCommand` — won't consume the `claude-release` marker
+ *      until in-flight is empty, so Claude itself doesn't exit while
+ *      backgrounded subagents are still running.
+ *
+ *   2. `clearClaudeSession` — calls `waitForInflightDrained` before tearing
+ *      down the pane, so the executor doesn't advance to the next stage
+ *      while the previous stage's subagents still hold FDs/PTYs on the
+ *      atomic tmux server.
+ *
+ * Always exits 0 — a non-zero exit would surface as a hook error in
+ * Claude's transcript, and silent miss + stale-sweep recovery is preferable
+ * to red noise on every workflow run.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { claudeHookDirs } from "./claude-stop-hook.ts";
+
+/**
+ * Shape of the JSON payload Claude pipes to the Subagent / TeammateIdle
+ * lifecycle hooks via stdin.
+ *
+ *   SubagentStart / SubagentStop  → `agent_id` (uuid), `agent_type`
+ *   TeammateIdle                  → `session_id` only (used by `wait` mode)
+ *
+ * `session_id` is the parent Claude session that triggered the event — for
+ * a top-level subagent, that's the stage's root; for a nested subagent,
+ * that's the spawning agent's session, and we look up its root via
+ * `inflightRoots`.
+ *
+ * Extra fields are ignored; missing ones cause a graceful exit-0 no-op.
+ */
+export interface ClaudeInflightHookPayload {
+  session_id: string;
+  hook_event_name?: string;
+  agent_id?: string;
+  agent_type?: string;
+  cwd?: string;
+}
+
+export type ClaudeInflightHookMode = "start" | "stop" | "wait";
+
+function isClaudeInflightHookPayload(
+  value: unknown,
+): value is ClaudeInflightHookPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj["session_id"] !== "string") return false;
+  return true;
+}
+
+/**
+ * Default TTL for stale-marker sweeps. A marker older than this is treated
+ * as orphaned (subagent crashed without firing SubagentStop) and removed.
+ *
+ * 2 hours is conservative: real subagents researching docs or running tests
+ * can exceed 30 minutes in ralph-style workflows, but no legitimate hook
+ * lifecycle should leave a marker on disk longer than ~2 h. Override at the
+ * environment via `ATOMIC_INFLIGHT_STALE_MS` for shorter runs in tests.
+ */
+const DEFAULT_INFLIGHT_STALE_MS = 2 * 60 * 60 * 1000;
+
+function staleMs(): number {
+  const raw = process.env["ATOMIC_INFLIGHT_STALE_MS"];
+  if (!raw) return DEFAULT_INFLIGHT_STALE_MS;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_INFLIGHT_STALE_MS;
+}
+
+/** Pick the unique id this event represents — `agent_id` for Subagent events. */
+function extractId(payload: ClaudeInflightHookPayload): string | null {
+  if (typeof payload.agent_id === "string" && payload.agent_id.length > 0) {
+    return payload.agent_id;
+  }
+  return null;
+}
+
+/** Path to the roots-mapping file for a given session. */
+function rootsMapPath(sessionId: string): string {
+  return path.join(claudeHookDirs().inflightRoots, sessionId);
+}
+
+/** Path to the marker dir for a given root session. */
+function markerDirFor(rootSessionId: string): string {
+  return path.join(claudeHookDirs().inflight, rootSessionId);
+}
+
+/** Path to a single marker file under a root session. */
+function markerPathFor(rootSessionId: string, id: string): string {
+  return path.join(markerDirFor(rootSessionId), id);
+}
+
+/**
+ * Resolve the stage root for an event's `session_id`. If the parent has a
+ * roots-mapping entry (it was itself spawned as a subagent), follow it.
+ * Otherwise the parent IS the root.
+ */
+async function resolveRoot(parentSessionId: string): Promise<string> {
+  try {
+    const mapped = await fs.readFile(rootsMapPath(parentSessionId), "utf-8");
+    const trimmed = mapped.trim();
+    if (trimmed.length > 0) return trimmed;
+  } catch {
+    // ENOENT (parent has no mapping → it is the root) or any read error
+    // falls through to the default.
+  }
+  return parentSessionId;
+}
+
+/**
+ * Best-effort marker payload — gives the stale sweep something to read for
+ * `ts`, and the Stop hook a way to log who got reaped.
+ */
+function markerBody(
+  payload: ClaudeInflightHookPayload,
+  rootSessionId: string,
+): string {
+  return JSON.stringify({
+    kind: payload.hook_event_name ?? null,
+    parent_session_id: payload.session_id,
+    root: rootSessionId,
+    agent_type: payload.agent_type ?? null,
+    ts: Date.now(),
+  });
+}
+
+/**
+ * Handler for the hidden `_claude-inflight-hook` subcommand.
+ *
+ * Always returns 0 — silently swallows all errors. A buggy tracker must
+ * never kill stages.
+ */
+export async function claudeInflightHookCommand(
+  mode: ClaudeInflightHookMode,
+): Promise<number> {
+  let raw: string;
+  try {
+    raw = await Bun.stdin.text();
+  } catch {
+    return 0;
+  }
+
+  let payload: ClaudeInflightHookPayload;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!isClaudeInflightHookPayload(parsed)) {
+      return 0;
+    }
+    payload = parsed;
+  } catch {
+    return 0;
+  }
+
+  // `wait` is the TeammateIdle path — gate on the root session's in-flight
+  // dir draining and exit. No marker write, no queue/release polling: the
+  // event's `session_id` may be a teammate's session that the runtime never
+  // enqueues to or releases, so reusing the Stop hook would risk hanging
+  // for the whole 24-day timeout.
+  if (mode === "wait") {
+    try {
+      const root = await resolveRoot(payload.session_id);
+      await waitForInflightDrained(root);
+    } catch {
+      // Best-effort — the wait swallows internal errors and resolves on
+      // timeout. A throw here would only happen on a path bug.
+    }
+    return 0;
+  }
+
+  const id = extractId(payload);
+  if (!id) return 0;
+
+  try {
+    const dirs = claudeHookDirs();
+    await fs.mkdir(dirs.inflight, { recursive: true });
+    await fs.mkdir(dirs.inflightRoots, { recursive: true });
+
+    const root = await resolveRoot(payload.session_id);
+
+    if (mode === "start") {
+      // Record the new agent's mapping so its own future descendants can
+      // resolve the same root via `resolveRoot`.
+      try {
+        await Bun.write(rootsMapPath(id), root);
+      } catch {
+        // Best-effort: a missing mapping just means a nested subagent of
+        // this id would mark under its immediate parent instead of the
+        // ultimate root. Stale sweep cleans up either way.
+      }
+
+      await fs.mkdir(markerDirFor(root), { recursive: true });
+      await Bun.write(markerPathFor(root, id), markerBody(payload, root));
+    } else {
+      // mode === "stop"
+      try {
+        await fs.unlink(markerPathFor(root, id));
+      } catch (e: unknown) {
+        const code = (e as NodeJS.ErrnoException | null)?.code;
+        if (code !== "ENOENT") {
+          // Ignore other errors silently — exit 0 is the contract.
+        }
+      }
+    }
+  } catch {
+    // Catch-all: any FS or path failure → silent exit 0.
+  }
+
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers exported for the Stop hook and clearClaudeSession
+// ---------------------------------------------------------------------------
+
+/** True when the per-root marker dir is missing or contains no marker files. */
+export async function inflightDirIsEmpty(rootSessionId: string): Promise<boolean> {
+  try {
+    const entries = await fs.readdir(markerDirFor(rootSessionId));
+    return entries.length === 0;
+  } catch (e: unknown) {
+    const code = (e as NodeJS.ErrnoException | null)?.code;
+    if (code === "ENOENT") return true;
+    // On any other error, assume non-empty so we wait — wedging the wait is
+    // worse than letting it advance with leaked FDs only when the FS is
+    // genuinely broken.
+    return false;
+  }
+}
+
+/**
+ * Remove markers older than `thresholdMs` (default `ATOMIC_INFLIGHT_STALE_MS`
+ * or 2 h). Returns the number of markers reaped. Used by the Stop hook and
+ * `waitForInflightDrained` to recover from subagents that crashed without
+ * firing `SubagentStop`.
+ */
+export async function sweepStaleInflight(
+  rootSessionId: string,
+  thresholdMs?: number,
+): Promise<number> {
+  const dir = markerDirFor(rootSessionId);
+  const cutoff = Date.now() - (thresholdMs ?? staleMs());
+  let reaped = 0;
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const file = path.join(dir, entry);
+    try {
+      const stat = await fs.stat(file);
+      if (stat.mtimeMs < cutoff) {
+        await fs.unlink(file);
+        reaped += 1;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return reaped;
+}
+
+export interface WaitForInflightOptions {
+  /** How long to wait before giving up. Default 30 minutes. */
+  timeoutMs?: number;
+  /** Poll cadence. Default 100 ms. */
+  pollIntervalMs?: number;
+  /** Stale-marker TTL. Default `ATOMIC_INFLIGHT_STALE_MS` or 2 h. */
+  staleMs?: number;
+}
+
+const DEFAULT_DRAIN_TIMEOUT_MS = 30 * 60 * 1000;
+const DEFAULT_DRAIN_POLL_MS = 100;
+
+/**
+ * Resolve when the per-root marker dir is empty. Sweeps stale markers on
+ * every tick. Resolves silently on timeout — the caller can't usefully
+ * recover, so wedging vs. leaking is the only trade.
+ */
+export async function waitForInflightDrained(
+  rootSessionId: string,
+  options: WaitForInflightOptions = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_DRAIN_POLL_MS;
+  const deadline = Date.now() + timeoutMs;
+
+  while (true) {
+    if (await inflightDirIsEmpty(rootSessionId)) return;
+    if (Date.now() >= deadline) return;
+    await sweepStaleInflight(rootSessionId, options.staleMs);
+    if (await inflightDirIsEmpty(rootSessionId)) return;
+    if (Date.now() >= deadline) return;
+    await new Promise<void>((r) => setTimeout(r, pollIntervalMs));
+  }
+}
+
+/**
+ * Remove the per-root marker dir and any roots-mapping entries that point
+ * at this root. Called by `clearClaudeSession` on stage teardown so
+ * leftovers cannot bleed into a future session that reuses the same id
+ * (UUID collision is astronomically unlikely, but stale-sweep + cleanup
+ * costs nothing).
+ */
+export async function clearInflightTracking(rootSessionId: string): Promise<void> {
+  try {
+    await fs.rm(markerDirFor(rootSessionId), { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+  // Sweep roots-mapping entries that point at this root.
+  const dirs = claudeHookDirs();
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dirs.inflightRoots);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    entries.map(async (entry) => {
+      const file = path.join(dirs.inflightRoots, entry);
+      try {
+        const value = (await fs.readFile(file, "utf-8")).trim();
+        if (value === rootSessionId || entry === rootSessionId) {
+          await fs.unlink(file);
+        }
+      } catch {
+        // ignore
+      }
+    }),
+  );
+}

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

@@ -33,6 +33,10 @@ import { watch as watchDir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import {
+  inflightDirIsEmpty,
+  sweepStaleInflight,
+} from "./claude-inflight-hook.ts";
 
 /** Shape of the JSON payload Claude pipes to the Stop hook via stdin. */
 export interface ClaudeStopHookPayload {
@@ -68,8 +72,11 @@ export function claudeHookDirs(): {
   hil: string;
   pid: string;
   ready: string;
+  inflight: string;
+  inflightRoots: string;
 } {
   const base = path.join(os.homedir(), ".atomic");
+  const inflightBase = path.join(base, "claude-inflight");
   return {
     marker: path.join(base, "claude-stop"),
     queue: path.join(base, "claude-queue"),
@@ -85,6 +92,19 @@ export function claudeHookDirs(): {
     // watches this directory to detect readiness — positive signal, unlike
     // racing the JSONL writer.
     ready: path.join(base, "claude-ready"),
+    // Per-root-session marker dirs (`<inflight>/<root_session_id>/<id>`)
+    // populated by the SubagentStart/SubagentStop and TaskCreated/
+    // TaskCompleted hooks. Both `clearClaudeSession` and the Stop hook gate
+    // on this dir being empty before letting the stage advance, so a stage
+    // never tears down while it still has live subagents/tasks holding FDs.
+    inflight: inflightBase,
+    // `<inflight>/.session-roots/<session_id>` → root_session_id mapping.
+    // SubagentStart writes a mapping for every spawned agent so that nested
+    // subagents (a subagent spawning its own subagent) can resolve which
+    // stage's root they belong to and write their marker under the right
+    // root. Lives alongside `inflight/` rather than under it so a `readdir`
+    // of `<inflight>/<root>/` only returns id markers.
+    inflightRoots: path.join(inflightBase, ".session-roots"),
   };
 }
 
@@ -292,10 +312,12 @@ export async function claudeStopHookCommand(
   type Hit = { kind: "release" } | { kind: "queue"; prompt: string };
 
   const check = async (): Promise<Hit | null> => {
-    if (existsSync(releasePath)) {
-      try { await fs.unlink(releasePath); } catch { /* ENOENT is fine */ }
-      return { kind: "release" };
-    }
+    // Queue takes priority over release: if the runtime enqueued a follow-up
+    // prompt, we want to deliver it and let Claude run another turn. The
+    // workflow only writes a release marker when it's actually torn down, so
+    // a queue + release race only happens at session end — and in that case
+    // the queue prompt was authored before teardown, so honoring it first is
+    // correct.
     if (existsSync(queuePath)) {
       let prompt: string;
       try {
@@ -307,6 +329,20 @@ export async function claudeStopHookCommand(
       try { await fs.unlink(queuePath); } catch { /* ENOENT is fine */ }
       return { kind: "queue", prompt };
     }
+    if (existsSync(releasePath)) {
+      // Don't consume the release marker until in-flight subagents/tasks
+      // have drained. Reaping the marker prematurely would let Claude exit
+      // while backgrounded children still hold FDs/PTYs on the atomic tmux
+      // server, which is the failure mode the inflight tracking exists to
+      // prevent. Stale-sweep first so a crashed subagent that never fired
+      // SubagentStop doesn't wedge the wait forever.
+      await sweepStaleInflight(payload.session_id);
+      if (!(await inflightDirIsEmpty(payload.session_id))) {
+        return null;
+      }
+      try { await fs.unlink(releasePath); } catch { /* ENOENT is fine */ }
+      return { kind: "release" };
+    }
     return null;
   };
 

package/src/commands/cli/init/index.ts

@@ -9,6 +9,7 @@
 import type { AgentKey } from "../../../services/config/index.ts";
 import { getConfigRoot } from "../../../services/config/config-path.ts";
 import { syncScmMcpServers } from "../../../services/config/scm-sync.ts";
+import { reconcileOpencodeInstructions } from "../../../services/config/additional-instructions.ts";
 import { applyManagedOnboardingFiles } from "./onboarding.ts";
 
 /**
@@ -29,4 +30,12 @@ export async function ensureProjectSetup(
   const configRoot = getConfigRoot();
   await applyManagedOnboardingFiles(agentKey, projectRoot, configRoot);
   await syncScmMcpServers(projectRoot);
+
+  // OpenCode is the only provider whose CLI/SDK has no flag or env-var
+  // path for additional instructions — it consumes them via its project
+  // config. Reconcile only when targeting OpenCode so we don't touch
+  // `.opencode/opencode.json` from unrelated chat sessions.
+  if (agentKey === "opencode") {
+    await reconcileOpencodeInstructions(projectRoot);
+  }
 }

package/src/lib/spawn.ts

@@ -414,9 +414,13 @@ export async function upgradeGlobalPackages(pkgs: string[]): Promise<void> {
   }
 }
 
-/** Upgrade @playwright/cli and @llamaindex/liteparse globally in one pass. */
+/** Upgrade @playwright/cli, @llamaindex/liteparse, and @ast-grep/cli globally in one pass. */
 export async function upgradeGlobalToolPackages(): Promise<void> {
-  return upgradeGlobalPackages(["@playwright/cli", "@llamaindex/liteparse"]);
+  return upgradeGlobalPackages([
+    "@playwright/cli",
+    "@llamaindex/liteparse",
+    "@ast-grep/cli",
+  ]);
 }
 
 /**

package/src/sdk/providers/claude.ts

@@ -32,6 +32,11 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import { claudeHookDirs } from "../../commands/cli/claude-stop-hook.ts";
+import {
+  clearInflightTracking,
+  waitForInflightDrained,
+} from "../../commands/cli/claude-inflight-hook.ts";
+import { resolveAdditionalInstructionsContent } from "../../services/config/additional-instructions.ts";
 
 // ---------------------------------------------------------------------------
 // Session tracking — ensures createClaudeSession is called before claudeQuery
@@ -59,6 +64,19 @@ const initializedPanes = new Map<string, PaneState>();
  * waiting out the hook's safety timeout.
  *
  * Called by the runtime when a Claude stage is being torn down. Idempotent.
+ *
+ * After writing the release marker, this waits for the per-session in-flight
+ * marker dir (`~/.atomic/claude-inflight/<session_id>/`) to drain. The
+ * marker dir is populated by the SubagentStart/Stop and TaskCreated/Completed
+ * hooks registered in {@link WORKFLOW_HOOK_SETTINGS}. This wait is the
+ * synchronization barrier that prevents the executor from advancing to the
+ * next stage while the previous stage's backgrounded subagents/tasks still
+ * hold FDs/PTYs on the atomic tmux server — the failure mode that surfaced
+ * intermittently as `tmux respawn-pane: fork failed: Device not configured`.
+ *
+ * The wait has its own bounded timeout (default 30 minutes) so a wedged
+ * subagent can't permanently block the workflow; the in-hook stale-sweep
+ * (~2 hours TTL) is the ultimate safety net.
  */
 export async function clearClaudeSession(paneId: string): Promise<void> {
   const state = initializedPanes.get(paneId);
@@ -69,6 +87,15 @@ export async function clearClaudeSession(paneId: string): Promise<void> {
       // Best-effort — if release fails the hook will still exit on its
       // own safety timeout.
     }
+    // Wait for in-flight subagents/tasks to finish before letting the
+    // executor advance. Resolves immediately when the dir is empty/missing
+    // (the common case, including any stage that didn't spawn subagents).
+    try {
+      await waitForInflightDrained(state.claudeSessionId);
+    } catch {
+      // Best-effort — the wait swallows internal errors and resolves on
+      // timeout. A throw here would only happen on a path bug.
+    }
     try {
       await unlinkAtomicPidFile(state.claudeSessionId);
     } catch {
@@ -82,6 +109,12 @@ export async function clearClaudeSession(paneId: string): Promise<void> {
       // a fresh one under its own UUID and clears any prior leftover in
       // `claudeQuery` before respawn.
     }
+    try {
+      await clearInflightTracking(state.claudeSessionId);
+    } catch {
+      // Best-effort — leftover marker files are reaped by the next session's
+      // stale-sweep, and the .session-roots/ entries are tiny.
+    }
   }
   initializedPanes.delete(paneId);
 }
@@ -188,6 +221,20 @@ const READY_HOOK_TIMEOUT_MS = 2_147_483_000;
  *     catch path — see `src/services/tools/toolExecution.ts` in the CLI
  *     source), so registering the same command on both guarantees the
  *     marker clears regardless of which completion path the tool takes.
+ *   - `SubagentStart` / `SubagentStop`: maintain a per-root-session marker
+ *     dir under `~/.atomic/claude-inflight/<root>/` so the Stop hook and
+ *     `clearClaudeSession` can both gate on subagent completion before
+ *     letting the stage advance. Without this gate, a stage that spawned
+ *     `run_in_background: true` subagents would tear down its pane while
+ *     children still hold FDs/PTYs on the atomic tmux server, intermittently
+ *     surfacing as `tmux respawn-pane: fork failed: Device not configured`
+ *     when the next stage tried to spawn.
+ *   - `TeammateIdle`: same gating applied at agent-team teammate idle.
+ *     Unlike Stop, this fires when a teammate (potentially a different
+ *     `session_id` from the stage's root) goes idle, so we route it to a
+ *     focused `_claude-inflight-hook wait` mode that only awaits in-flight
+ *     drain — no claude-stop marker write (that would confuse `waitForIdle`)
+ *     and no queue/release polling (those are keyed on the stage's root).
  *
  * Built once at module load. Contains no single quotes (JSON syntax doesn't
  * produce them and paths rarely do), so POSIX single-quoting at the spawn
@@ -250,6 +297,45 @@ const WORKFLOW_HOOK_SETTINGS = JSON.stringify({
         ],
       },
     ],
+    // SubagentStart/SubagentStop fire per Agent-tool dispatch (no matcher)
+    // and route to a single subcommand that touches/removes one marker file
+    // per `agent_id`. The handler is bulletproof — any error exits 0
+    // silently — so a hook failure can't kill the stage.
+    SubagentStart: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: buildWorkflowHookCommand("_claude-inflight-hook", ["start"]),
+          },
+        ],
+      },
+    ],
+    SubagentStop: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: buildWorkflowHookCommand("_claude-inflight-hook", ["stop"]),
+          },
+        ],
+      },
+    ],
+    // TeammateIdle gets a focused `wait` mode (gates on in-flight drain,
+    // nothing else) — see the WORKFLOW_HOOK_SETTINGS docstring for why this
+    // doesn't reuse the Stop hook handler. Timeout matches Stop's so the
+    // wait can run for as long as the workflow holds onto teammates.
+    TeammateIdle: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: buildWorkflowHookCommand("_claude-inflight-hook", ["wait"]),
+            timeout: STOP_HOOK_TIMEOUT_SECONDS,
+          },
+        ],
+      },
+    ],
   },
 });
 
@@ -1037,6 +1123,36 @@ export function mergeDisallowedTools(
   return merged;
 }
 
+/**
+ * Fold the atomic-managed additional instructions into a caller's
+ * `systemPrompt` value. Behavior, in order of precedence:
+ *
+ *   - **No caller value** → return a `claude_code` preset with our content
+ *     in `append`. Preserves the SDK's full Claude Code persona.
+ *   - **Caller passed a preset object** → concatenate our content onto the
+ *     existing `append` (newline-separated when both are present).
+ *   - **Caller passed a custom string or array** → leave it alone. The
+ *     caller has explicitly opted into a custom prompt, and silently
+ *     prepending the persona-style preset text would break that contract.
+ *
+ * Exported for unit testing.
+ */
+export function mergeSystemPromptAppend(
+  existing: SDKOptions["systemPrompt"],
+  extra: string,
+): SDKOptions["systemPrompt"] {
+  if (!extra) return existing;
+  if (existing === undefined) {
+    return { type: "preset", preset: "claude_code", append: extra };
+  }
+  if (typeof existing === "object" && !Array.isArray(existing) && existing.type === "preset") {
+    const prevAppend = existing.append ?? "";
+    const merged = prevAppend ? `${prevAppend}\n\n${extra}` : extra;
+    return { ...existing, append: merged };
+  }
+  return existing;
+}
+
 /**
  * Synthetic client wrapper for Claude stages.
  * Auto-starts the Claude CLI in the tmux pane during `start()`.
@@ -1193,6 +1309,13 @@ export function resolveHeadlessClaudeBin(): string {
  */
 export class HeadlessClaudeSessionWrapper {
   readonly paneId = "";
+  /**
+   * Project root the workflow is operating against. Used to resolve
+   * project-scoped config (e.g. `additional-instructions`) against the
+   * workflow's actual root rather than `process.cwd()`, which can drift
+   * when workflows are invoked programmatically or from a subdirectory.
+   */
+  private readonly _projectRoot: string;
   /**
    * The Claude session UUID of the most recently completed `query()`. Exposed
    * via `s.sessionId` so workflows can pass it to `s.save(s.sessionId)` and
@@ -1200,6 +1323,10 @@ export class HeadlessClaudeSessionWrapper {
    * Claude stages run in parallel (each call gets its own SDK-assigned UUID).
    */
   private _lastSessionId: string = "";
+
+  constructor(projectRoot: string) {
+    this._projectRoot = projectRoot;
+  }
   /**
    * Validated structured output captured from the most recent `query()`'s
    * `result` message. Populated only when callers pass
@@ -1226,6 +1353,7 @@ export class HeadlessClaudeSessionWrapper {
     // agent can call it and the SDK query will sit blocked forever since no
     // human is attached to answer.
     const sdkOpts = options ?? {};
+    const additional = await resolveAdditionalInstructionsContent(this._projectRoot);
     const headlessSdkOpts: Partial<SDKOptions> = {
       ...sdkOpts,
       pathToClaudeCodeExecutable:
@@ -1233,6 +1361,9 @@ export class HeadlessClaudeSessionWrapper {
       disallowedTools: mergeDisallowedTools(sdkOpts.disallowedTools, [
         "AskUserQuestion",
       ]),
+      ...(additional
+        ? { systemPrompt: mergeSystemPromptAppend(sdkOpts.systemPrompt, additional) }
+        : {}),
     };
 
     let sdkSessionId = "";