@neotx/core 0.1.0-alpha.14 → 0.1.0-alpha.19

package/dist/index.js

@@ -406,11 +406,10 @@ var Semaphore = class {
 };
 
 // src/config.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
 import path4 from "path";
-import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
-import { z as z2 } from "zod";
+import { parse as parseYaml3, stringify as stringifyYaml } from "yaml";
 
 // src/paths.ts
 import { homedir } from "os";
@@ -458,8 +457,12 @@ function getSupervisorEventsPath(name) {
 function getSupervisorLockPath(name) {
   return path3.join(getSupervisorDir(name), "daemon.lock");
 }
+function getSupervisorDecisionsPath(name) {
+  return path3.join(getSupervisorDir(name), "decisions.jsonl");
+}
 
-// src/config.ts
+// src/config/schema.ts
+import { z as z2 } from "zod";
 var httpMcpServerSchema = z2.object({
   type: z2.literal("http"),
   url: z2.string(),
@@ -484,26 +487,54 @@ var repoConfigSchema = z2.object({
   pushRemote: z2.string().default("origin"),
   gitStrategy: gitStrategySchema
 });
+var concurrencyConfigSchema = z2.object({
+  maxSessions: z2.number().default(5),
+  maxPerRepo: z2.number().default(4),
+  queueMax: z2.number().default(50)
+}).default({ maxSessions: 5, maxPerRepo: 4, queueMax: 50 });
+var budgetConfigSchema = z2.object({
+  dailyCapUsd: z2.number().default(500),
+  alertThresholdPct: z2.number().default(80)
+}).default({ dailyCapUsd: 500, alertThresholdPct: 80 });
+var recoveryConfigSchema = z2.object({
+  maxRetries: z2.number().default(3),
+  backoffBaseMs: z2.number().default(3e4)
+}).default({ maxRetries: 3, backoffBaseMs: 3e4 });
+var sessionsConfigSchema = z2.object({
+  initTimeoutMs: z2.number().default(12e4),
+  maxDurationMs: z2.number().default(36e5),
+  dir: z2.string().default("/tmp/neo-sessions")
+}).default({ initTimeoutMs: 12e4, maxDurationMs: 36e5, dir: "/tmp/neo-sessions" });
+var supervisorConfigSchema = z2.object({
+  port: z2.number().default(7777),
+  secret: z2.string().optional(),
+  heartbeatTimeoutMs: z2.number().default(3e5),
+  maxConsecutiveFailures: z2.number().default(3),
+  maxEventsPerSec: z2.number().default(10),
+  dailyCapUsd: z2.number().default(50),
+  /** How often consolidation runs (ms) */
+  consolidationIntervalMs: z2.number().default(3e5),
+  /** How often compaction runs (ms) */
+  compactionIntervalMs: z2.number().default(36e5),
+  /** Safety timeout for waitForWork (ms) */
+  eventTimeoutMs: z2.number().default(3e5),
+  instructions: z2.string().optional()
+}).default({
+  port: 7777,
+  heartbeatTimeoutMs: 3e5,
+  maxConsecutiveFailures: 3,
+  maxEventsPerSec: 10,
+  dailyCapUsd: 50,
+  consolidationIntervalMs: 3e5,
+  compactionIntervalMs: 36e5,
+  eventTimeoutMs: 3e5
+});
 var globalConfigSchema = z2.object({
   repos: z2.array(repoConfigSchema).default([]),
-  concurrency: z2.object({
-    maxSessions: z2.number().default(5),
-    maxPerRepo: z2.number().default(4),
-    queueMax: z2.number().default(50)
-  }).default({ maxSessions: 5, maxPerRepo: 4, queueMax: 50 }),
-  budget: z2.object({
-    dailyCapUsd: z2.number().default(500),
-    alertThresholdPct: z2.number().default(80)
-  }).default({ dailyCapUsd: 500, alertThresholdPct: 80 }),
-  recovery: z2.object({
-    maxRetries: z2.number().default(3),
-    backoffBaseMs: z2.number().default(3e4)
-  }).default({ maxRetries: 3, backoffBaseMs: 3e4 }),
-  sessions: z2.object({
-    initTimeoutMs: z2.number().default(12e4),
-    maxDurationMs: z2.number().default(36e5),
-    dir: z2.string().default("/tmp/neo-sessions")
-  }).default({ initTimeoutMs: 12e4, maxDurationMs: 36e5, dir: "/tmp/neo-sessions" }),
+  concurrency: concurrencyConfigSchema,
+  budget: budgetConfigSchema,
+  recovery: recoveryConfigSchema,
+  sessions: sessionsConfigSchema,
   webhooks: z2.array(
     z2.object({
       url: z2.string().url(),
@@ -512,30 +543,7 @@ var globalConfigSchema = z2.object({
       timeoutMs: z2.number().default(5e3)
     })
   ).default([]),
-  supervisor: z2.object({
-    port: z2.number().default(7777),
-    secret: z2.string().optional(),
-    heartbeatTimeoutMs: z2.number().default(3e5),
-    maxConsecutiveFailures: z2.number().default(3),
-    maxEventsPerSec: z2.number().default(10),
-    dailyCapUsd: z2.number().default(50),
-    /** How often consolidation runs (ms) */
-    consolidationIntervalMs: z2.number().default(3e5),
-    /** How often compaction runs (ms) */
-    compactionIntervalMs: z2.number().default(36e5),
-    /** Safety timeout for waitForWork (ms) */
-    eventTimeoutMs: z2.number().default(3e5),
-    instructions: z2.string().optional()
-  }).default({
-    port: 7777,
-    heartbeatTimeoutMs: 3e5,
-    maxConsecutiveFailures: 3,
-    maxEventsPerSec: 10,
-    dailyCapUsd: 50,
-    consolidationIntervalMs: 3e5,
-    compactionIntervalMs: 36e5,
-    eventTimeoutMs: 3e5
-  }),
+  supervisor: supervisorConfigSchema,
   memory: z2.object({
     embeddings: z2.boolean().default(true)
   }).default({ embeddings: true }),
@@ -548,6 +556,296 @@ var globalConfigSchema = z2.object({
   }).optional()
 });
 var neoConfigSchema = globalConfigSchema;
+var repoOverrideConfigSchema = z2.object({
+  concurrency: concurrencyConfigSchema.unwrap().partial().optional(),
+  budget: budgetConfigSchema.unwrap().partial().optional(),
+  recovery: recoveryConfigSchema.unwrap().partial().optional(),
+  sessions: sessionsConfigSchema.unwrap().partial().optional()
+}).partial();
+
+// src/config/dotNotation.ts
+function getConfigValue(config, path19) {
+  if (path19 === "") {
+    return config;
+  }
+  const keys = path19.split(".");
+  let current = config;
+  for (const key of keys) {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    if (typeof current !== "object") {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+// src/config/merge.ts
+var defaultConfig = {
+  repos: [],
+  concurrency: concurrencyConfigSchema.parse(void 0),
+  budget: budgetConfigSchema.parse(void 0),
+  recovery: recoveryConfigSchema.parse(void 0),
+  sessions: sessionsConfigSchema.parse(void 0),
+  webhooks: [],
+  supervisor: {
+    port: 7777,
+    heartbeatTimeoutMs: 3e5,
+    maxConsecutiveFailures: 3,
+    maxEventsPerSec: 10,
+    dailyCapUsd: 50,
+    consolidationIntervalMs: 3e5,
+    compactionIntervalMs: 36e5,
+    eventTimeoutMs: 3e5
+  },
+  memory: { embeddings: true }
+};
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key];
+    const targetValue = target[key];
+    if (sourceValue === void 0) {
+      continue;
+    }
+    if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue) && targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue)) {
+      result[key] = deepMerge(
+        targetValue,
+        sourceValue
+      );
+    } else {
+      result[key] = sourceValue;
+    }
+  }
+  return result;
+}
+function deepFreeze(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      deepFreeze(item);
+    }
+    return Object.freeze(obj);
+  }
+  for (const value of Object.values(obj)) {
+    deepFreeze(value);
+  }
+  return Object.freeze(obj);
+}
+function mergeConfigs(defaults, globalConfig, repoConfig) {
+  let result = { ...defaults };
+  if (globalConfig) {
+    result = deepMerge(result, globalConfig);
+  }
+  if (repoConfig) {
+    result = deepMerge(result, repoConfig);
+  }
+  return deepFreeze(result);
+}
+
+// src/config/ConfigStore.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join } from "path";
+import { parse as parseYaml2 } from "yaml";
+var ConfigStore = class {
+  repoPath;
+  config = null;
+  constructor(repoPath) {
+    this.repoPath = repoPath;
+  }
+  // ─── Public API ────────────────────────────────────────
+  /**
+   * Loads and merges config files from all locations.
+   * Must be called before get() or getAll().
+   */
+  async load() {
+    const globalConfig = await this.loadGlobalConfig();
+    const repoConfig = await this.loadRepoConfig();
+    this.config = mergeConfigs(defaultConfig, globalConfig, repoConfig);
+  }
+  /**
+   * Gets a config value using dot notation.
+   *
+   * @param key - Dot-separated path (e.g., "budget.dailyCapUsd")
+   * @returns The value at the path
+   * @throws Error if load() has not been called
+   *
+   * @example
+   * store.get<number>('budget.dailyCapUsd') // 500
+   * store.get<string>('sessions.dir') // '/tmp/neo-sessions'
+   */
+  get(key) {
+    if (this.config === null) {
+      throw new Error("ConfigStore not loaded. Call load() first.");
+    }
+    return getConfigValue(this.config, key);
+  }
+  /**
+   * Returns the full merged configuration.
+   *
+   * @throws Error if load() has not been called
+   */
+  getAll() {
+    if (this.config === null) {
+      throw new Error("ConfigStore not loaded. Call load() first.");
+    }
+    return this.config;
+  }
+  /**
+   * Returns the repository path, if one was provided.
+   * Used by ConfigWatcher to determine which files to watch.
+   */
+  getRepoPath() {
+    return this.repoPath;
+  }
+  // ─── Private loaders ───────────────────────────────────
+  /**
+   * Loads global config from ~/.neo/config.yml
+   */
+  async loadGlobalConfig() {
+    const globalPath = join(homedir2(), ".neo", "config.yml");
+    const raw = await this.loadFile(globalPath);
+    if (raw === null) {
+      return null;
+    }
+    const parsed = neoConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+      return null;
+    }
+    return parsed.data;
+  }
+  /**
+   * Loads repo-level overrides from <repoPath>/.neo/config.yml
+   */
+  async loadRepoConfig() {
+    if (!this.repoPath) {
+      return null;
+    }
+    const repoConfigPath = join(this.repoPath, ".neo", "config.yml");
+    const raw = await this.loadFile(repoConfigPath);
+    if (raw === null) {
+      return null;
+    }
+    const parsed = repoOverrideConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+      return null;
+    }
+    return parsed.data;
+  }
+  /**
+   * Loads and parses a YAML config file.
+   *
+   * @param filePath - Absolute path to the config file
+   * @returns Parsed YAML content or null if file doesn't exist
+   */
+  async loadFile(filePath) {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const parsed = parseYaml2(content);
+      if (parsed === null || typeof parsed !== "object") {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/config/ConfigWatcher.ts
+import { EventEmitter } from "events";
+import { homedir as homedir3 } from "os";
+import { join as join2 } from "path";
+import { watch } from "chokidar";
+var ConfigWatcher = class extends EventEmitter {
+  store;
+  debounceMs;
+  repoPath;
+  watcher = null;
+  debounceTimer = null;
+  constructor(store, options) {
+    super();
+    this.store = store;
+    this.debounceMs = options?.debounceMs ?? 500;
+    this.repoPath = store.getRepoPath();
+  }
+  /**
+   * Starts watching config files for changes.
+   * Watches both global (~/.neo/config.yml) and repo config files.
+   */
+  start() {
+    if (this.watcher) {
+      return;
+    }
+    const paths = this.getConfigPaths();
+    this.watcher = watch(paths, {
+      ignoreInitial: true,
+      // Don't error if files don't exist — they may be created later
+      ignorePermissionErrors: true
+    });
+    this.watcher.on("change", () => this.handleChange());
+    this.watcher.on("add", () => this.handleChange());
+    this.watcher.on("unlink", () => this.handleChange());
+  }
+  /**
+   * Stops watching config files.
+   */
+  stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+  // ─── Private ─────────────────────────────────────────────
+  /**
+   * Returns the list of config file paths to watch.
+   */
+  getConfigPaths() {
+    const globalPath = join2(homedir3(), ".neo", "config.yml");
+    const paths = [globalPath];
+    if (this.repoPath) {
+      const repoConfigPath = join2(this.repoPath, ".neo", "config.yml");
+      paths.push(repoConfigPath);
+    }
+    return paths;
+  }
+  /**
+   * Handles file change events with debouncing.
+   */
+  handleChange() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this.reloadConfig();
+    }, this.debounceMs);
+  }
+  /**
+   * Reloads the config and emits 'change' event.
+   */
+  async reloadConfig() {
+    try {
+      await this.store.load();
+      this.emit("change");
+    } catch {
+    }
+  }
+};
+
+// src/config.ts
 var DEFAULT_GLOBAL_CONFIG = {
   repos: [],
   concurrency: {
@@ -562,7 +860,7 @@ var DEFAULT_GLOBAL_CONFIG = {
 };
 function parseYamlFile(raw, filePath) {
   try {
-    return parseYaml2(raw);
+    return parseYaml3(raw);
   } catch (err) {
     throw new Error(
       `Invalid YAML in ${filePath}: ${err instanceof Error ? err.message : String(err)}. Check YAML syntax at the indicated line.`
@@ -590,7 +888,7 @@ async function loadConfig(configPath) {
 }
 async function loadGlobalConfig() {
   const configPath = path4.join(getDataDir(), "config.yml");
-  if (!existsSync(configPath)) {
+  if (!existsSync2(configPath)) {
     await mkdir(getDataDir(), { recursive: true });
     await writeFile(configPath, stringifyYaml(DEFAULT_GLOBAL_CONFIG), "utf-8");
     return globalConfigSchema.parse(DEFAULT_GLOBAL_CONFIG);
@@ -698,9 +996,9 @@ var CostJournal = class {
 };
 
 // src/events/emitter.ts
-import { EventEmitter } from "events";
+import { EventEmitter as EventEmitter2 } from "events";
 var NeoEventEmitter = class {
-  emitter = new EventEmitter();
+  emitter = new EventEmitter2();
   emit(event) {
     this.safeEmit(event.type, event);
     this.safeEmit("*", event);
@@ -842,7 +1140,7 @@ function toSerializable(event) {
 
 // src/isolation/clone.ts
 import { execFile } from "child_process";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { mkdir as mkdir3, readdir as readdir2, rm } from "fs/promises";
 import { dirname, resolve } from "path";
 import { promisify } from "util";
@@ -886,14 +1184,14 @@ async function createSessionClone(options) {
 }
 async function removeSessionClone(sessionPath) {
   const absPath = resolve(sessionPath);
-  if (!existsSync2(absPath)) {
+  if (!existsSync3(absPath)) {
     return;
   }
   await rm(absPath, { recursive: true, force: true });
 }
 async function listSessionClones(sessionsBaseDir) {
   const absBase = resolve(sessionsBaseDir);
-  if (!existsSync2(absBase)) {
+  if (!existsSync3(absBase)) {
     return [];
   }
   const entries = await readdir2(absBase, { withFileTypes: true });
@@ -1191,11 +1489,11 @@ function loopDetection(options) {
 // src/orchestrator.ts
 import { randomUUID as randomUUID3 } from "crypto";
 import { existsSync as existsSync6 } from "fs";
-import { mkdir as mkdir6, readFile as readFile7 } from "fs/promises";
-import path11 from "path";
+import { mkdir as mkdir6, readFile as readFile6 } from "fs/promises";
+import path10 from "path";
 
 // src/orchestrator/run-store.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir5, readdir as readdir3, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
 import path7 from "path";
 
@@ -1245,7 +1543,7 @@ var RunStore = class {
    * Returns them so the caller can emit failure events and update status.
    */
   async recoverOrphanedRuns() {
-    if (!existsSync3(this.runsDir)) return [];
+    if (!existsSync4(this.runsDir)) return [];
     const orphaned = [];
     try {
       const jsonFiles = await this.collectRunFiles();
@@ -1296,9 +1594,137 @@ var RunStore = class {
   }
 };
 
-// src/runner/session-executor.ts
+// src/orchestrator/prompt-builder.ts
 import { readFile as readFile5 } from "fs/promises";
 import path8 from "path";
+var INSTRUCTIONS_PATH = ".neo/INSTRUCTIONS.md";
+async function loadRepoInstructions(repoPath) {
+  const filePath = path8.join(repoPath, INSTRUCTIONS_PATH);
+  try {
+    return await readFile5(filePath, "utf-8");
+  } catch {
+    return void 0;
+  }
+}
+function buildGitStrategyInstructions(strategy, agent, branch, baseBranch, remote, metadata) {
+  const prNumber = metadata?.prNumber;
+  if (agent.sandbox !== "writable") {
+    if (prNumber) {
+      return `## Pull Request
+
+PR #${String(prNumber)} is open for this task. After your review, leave your findings as a comment: \`gh pr comment ${String(prNumber)} --body "..."\`.`;
+    }
+    return null;
+  }
+  if (strategy === "pr") {
+    if (prNumber) {
+      return `## Git workflow
+
+You are on branch \`${branch}\`.
+An open PR exists: #${String(prNumber)}.
+After committing, push your changes to the branch. The PR will be updated automatically.
+Leave a review comment on the PR summarizing what you did: \`gh pr comment ${String(prNumber)} --body "..."\`.`;
+    }
+    return `## Git workflow
+
+You are on branch \`${branch}\` (base: \`${baseBranch}\`).
+After committing:
+1. Push: \`git push -u ${remote} ${branch}\`
+2. Create a PR against \`${baseBranch}\` \u2014 choose a title and description that reflect the work you completed. End the PR body with: \`\u{1F916} Generated with [neo](https://neotx.dev)\`
+3. Output the PR URL on a dedicated line: \`PR_URL: <url>\``;
+  }
+  return `## Git workflow
+
+You are on branch \`${branch}\` (base: \`${baseBranch}\`).
+Commit your changes. The branch will be pushed automatically.`;
+}
+function buildReportingInstructions(_runId) {
+  return `## Reporting & Memory
+
+You have two tools to communicate what you learn and do: \`neo log\` (real-time visibility) and \`neo memory\` (persistent knowledge for future agents). Use both deliberately throughout your work.
+
+### Progress reporting \u2014 \`neo log\`
+
+Chain \`neo log\` with the command that triggered the event \u2014 never call it standalone.
+
+<log-types>
+| Type | When to use | Example |
+|------|------------|---------|
+| \`milestone\` | A meaningful goal is achieved (tests pass, build succeeds, feature complete) | \`neo log milestone "auth middleware passing all tests"\` |
+| \`action\` | You performed a significant action (push, PR, deploy) | \`neo log action "pushed 3 commits to feat/auth"\` |
+| \`decision\` | You made a non-obvious choice \u2014 record WHY | \`neo log decision "chose JWT over sessions \u2014 stateless, simpler for MVP"\` |
+| \`blocker\` | Something is preventing progress | \`neo log blocker "CI fails: missing DATABASE_URL in test env"\` |
+| \`discovery\` | You found something surprising or important about the codebase | \`neo log discovery "API rate limiter is disabled in dev \u2014 tests hit real endpoints"\` |
+| \`progress\` | General progress update | \`neo log progress "3/5 endpoints migrated"\` |
+</log-types>
+
+<log-rules>
+- **Chain with commands**: \`pnpm test && neo log milestone "tests passing" || neo log blocker "tests failing"\`
+- **Log decisions with reasoning**: the "why" is more valuable than the "what"
+- **Log blockers immediately**: do not continue silently \u2014 surface problems so the supervisor can act
+- **Log at natural boundaries**: after completing a subtask, before switching context, when hitting an obstacle
+</log-rules>
+
+### Memory \u2014 \`neo memory\`
+
+Memory is persistent knowledge injected into future agent prompts. Write a memory when you learn something that would change HOW the next agent approaches work on this repo.
+
+<memory-types>
+| Type | When to write | Example |
+|------|--------------|---------|
+| \`fact\` | Stable truth that affects workflow decisions | Build quirks, CI config, auth patterns, deployment constraints |
+| \`procedure\` | Non-obvious multi-step workflow learned from failure | "Run X before Y otherwise Z breaks" |
+</memory-types>
+
+<memory-decision-tree>
+Before writing a memory, apply this test:
+1. Can \`cat package.json\`, \`ls\`, or reading the README answer this? \u2192 Do NOT memorize.
+2. Would knowing this change how you approach the task? \u2192 Write a \`fact\`.
+3. Did you fail before discovering this workflow? \u2192 Write a \`procedure\`.
+4. Is this just a detail about what you did (file counts, line numbers, component names)? \u2192 Do NOT memorize.
+</memory-decision-tree>
+
+<memory-examples type="good">
+# Affects workflow \u2014 non-obvious build/CI constraints
+neo memory write --type fact --scope $NEO_REPOSITORY "CI requires pnpm build before push \u2014 no auto-rebuild in pipeline"
+neo memory write --type fact --scope $NEO_REPOSITORY "Biome enforces complexity max 20 \u2014 extract helpers for large functions"
+
+# Learned from failure \u2014 save the next agent from the same mistake
+neo memory write --type procedure --scope $NEO_REPOSITORY "Run pnpm db:generate after any schema.prisma change \u2014 TypeScript types won't update otherwise"
+neo memory write --type procedure --scope $NEO_REPOSITORY "E2E tests need STRIPE_TEST_KEY in .env.test \u2014 tests hang silently without it"
+</memory-examples>
+
+<memory-examples type="bad">
+# NEVER write these \u2014 trivial or derivable
+# "packages/core has 71 files" \u2192 derivable from ls
+# "Uses React 19" \u2192 visible in package.json
+# "Main entry is src/index.ts" \u2192 visible in package.json
+# "Tests use vitest" \u2192 visible in config files
+</memory-examples>
+
+<when-to-write>
+Write memories at these key moments:
+- **After resolving a non-obvious issue**: the fix revealed a constraint future agents should know
+- **After discovering a build/CI/deploy quirk**: the next agent will hit the same wall without this
+- **Before finishing your task**: review what you learned \u2014 anything that would save the next agent 10+ minutes?
+- **After a failed attempt**: if you tried something that seemed right but failed, document why
+</when-to-write>`;
+}
+function buildFullPrompt(agentPrompt, repoInstructions, gitInstructions, taskPrompt, memoryContext, cwdInstructions, reportingInstructions) {
+  const sections = [];
+  if (agentPrompt) sections.push(agentPrompt);
+  if (cwdInstructions) sections.push(cwdInstructions);
+  if (memoryContext) sections.push(memoryContext);
+  if (repoInstructions) sections.push(`## Repository instructions
+
+${repoInstructions}`);
+  if (gitInstructions) sections.push(gitInstructions);
+  if (reportingInstructions) sections.push(reportingInstructions);
+  sections.push(`## Task
+
+${taskPrompt}`);
+  return sections.join("\n\n---\n\n");
+}
 
 // src/runner/output-parser.ts
 function extractJson(raw) {
@@ -1542,115 +1968,27 @@ async function runWithRecovery(options) {
 }
 
 // src/runner/session-executor.ts
-var INSTRUCTIONS_PATH = ".neo/INSTRUCTIONS.md";
-async function loadRepoInstructions(repoPath) {
-  const filePath = path8.join(repoPath, INSTRUCTIONS_PATH);
-  try {
-    return await readFile5(filePath, "utf-8");
-  } catch {
-    return void 0;
-  }
+function buildMiddlewareContext(runId, step, agent, repo, getContextValue) {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    runId,
+    step,
+    agent,
+    repo,
+    get: ((key) => {
+      const value = getContextValue(key);
+      if (value !== void 0) return value;
+      return store.get(key);
+    }),
+    set: ((key, value) => {
+      store.set(key, value);
+    })
+  };
 }
-function buildGitStrategyInstructions(strategy, agent, branch, baseBranch, remote, metadata) {
-  const prNumber = metadata?.prNumber;
-  if (agent.sandbox !== "writable") {
-    if (prNumber) {
-      return `## Pull Request
-
-PR #${String(prNumber)} is open for this task. After your review, leave your findings as a comment: \`gh pr comment ${String(prNumber)} --body "..."\`.`;
-    }
-    return null;
-  }
-  if (strategy === "pr") {
-    if (prNumber) {
-      return `## Git workflow
-
-You are on branch \`${branch}\`.
-An open PR exists: #${String(prNumber)}.
-After committing, push your changes to the branch. The PR will be updated automatically.
-Leave a review comment on the PR summarizing what you did: \`gh pr comment ${String(prNumber)} --body "..."\`.`;
-    }
-    return `## Git workflow
-
-You are on branch \`${branch}\` (base: \`${baseBranch}\`).
-After committing:
-1. Push: \`git push -u ${remote} ${branch}\`
-2. Create a PR against \`${baseBranch}\` \u2014 choose a title and description that reflect the work you completed. End the PR body with: \`\u{1F916} Generated with [neo](https://neotx.dev)\`
-3. Output the PR URL on a dedicated line: \`PR_URL: <url>\``;
-  }
-  return `## Git workflow
-
-You are on branch \`${branch}\` (base: \`${baseBranch}\`).
-Commit your changes. The branch will be pushed automatically.`;
-}
-function buildReportingInstructions(_runId) {
-  return `## Reporting & Memory
-
-### Progress reporting (real-time, visible in TUI)
-Chain \`neo log\` with the command that triggered it \u2014 never standalone:
-\`\`\`bash
-pnpm test && neo log milestone "all tests passing" || neo log blocker "tests failing"
-git push origin HEAD && neo log action "pushed to branch"
-neo log decision "chose JWT over sessions \u2014 simpler for MVP"
-\`\`\`
-
-### Memory (persistent, injected into future agent prompts)
-Write discoveries so the next agent on this repo starts smarter.
-
-**Be selective** \u2014 only write a memory if it would change HOW you or future agents approach work:
-\`\`\`bash
-# GOOD: affects workflow decisions
-neo memory write --type fact --scope $NEO_REPOSITORY "CI requires pnpm build before push \u2014 no auto-rebuild in pipeline"
-neo memory write --type fact --scope $NEO_REPOSITORY "Biome enforces complexity max 20 \u2014 extract helpers for large functions"
-neo memory write --type procedure --scope $NEO_REPOSITORY "Integration tests require DATABASE_URL env var \u2014 set before running"
-
-# BAD: trivial or derivable \u2014 do NOT write these
-# "packages/core has 71 files" \u2014 derivable from ls
-# "Uses React 19" \u2014 visible in package.json
-# "apps/web has no test framework" \u2014 derivable from ls/cat
-\`\`\`
-
-**The test**: if \`cat package.json\`, \`ls\`, or reading the README can answer it, do NOT memorize it. Only memorize truths that affect decisions or non-obvious workflows learned from failure.
-
-Write at key moments: after resolving a non-obvious issue, after discovering a build/CI quirk, before finishing.`;
-}
-function buildFullPrompt(agentPrompt, repoInstructions, gitInstructions, taskPrompt, memoryContext, cwdInstructions, reportingInstructions) {
-  const sections = [];
-  if (agentPrompt) sections.push(agentPrompt);
-  if (cwdInstructions) sections.push(cwdInstructions);
-  if (memoryContext) sections.push(memoryContext);
-  if (repoInstructions) sections.push(`## Repository instructions
-
-${repoInstructions}`);
-  if (gitInstructions) sections.push(gitInstructions);
-  if (reportingInstructions) sections.push(reportingInstructions);
-  sections.push(`## Task
-
-${taskPrompt}`);
-  return sections.join("\n\n---\n\n");
-}
-function buildMiddlewareContext(runId, workflow, step, agent, repo, getContextValue) {
-  const store = /* @__PURE__ */ new Map();
-  return {
-    runId,
-    workflow,
-    step,
-    agent,
-    repo,
-    get: ((key) => {
-      const value = getContextValue(key);
-      if (value !== void 0) return value;
-      return store.get(key);
-    }),
-    set: ((key, value) => {
-      store.set(key, value);
-    })
-  };
-}
-var SessionExecutor = class {
-  constructor(config, getContextValue) {
-    this.config = config;
-    this.getContextValue = getContextValue;
+var SessionExecutor = class {
+  constructor(config, getContextValue) {
+    this.config = config;
+    this.getContextValue = getContextValue;
   }
   /**
    * Execute an agent session with the given input and dependencies.
@@ -1660,7 +1998,6 @@ var SessionExecutor = class {
     const {
       runId,
       agent,
-      stepDef,
       repoConfig,
       repoPath,
       prompt: taskPrompt,
@@ -1681,7 +2018,6 @@ var SessionExecutor = class {
     const chain = buildMiddlewareChain(middleware);
     const middlewareContext = buildMiddlewareContext(
       runId,
-      stepDef.prompt ? "workflow" : "direct",
       "execute",
       agent.name,
       repoPath,
@@ -1706,12 +2042,11 @@ ALWAYS run commands from this directory. NEVER cd to or operate on any other rep
       agent.definition.prompt,
       repoInstructions,
       gitInstructions,
-      stepDef.prompt ?? taskPrompt,
+      taskPrompt,
       memoryContext,
       cwdInstructions,
       reportingInstructions
     );
-    const recoveryOpts = stepDef.recovery;
     const agentEnv = {
       NEO_RUN_ID: runId,
       NEO_AGENT_NAME: agent.name,
@@ -1726,11 +2061,10 @@ ALWAYS run commands from this directory. NEVER cd to or operate on any other rep
       env: agentEnv,
       initTimeoutMs: this.config.initTimeoutMs,
       maxDurationMs: this.config.maxDurationMs,
-      maxRetries: recoveryOpts?.maxRetries ?? this.config.maxRetries,
+      maxRetries: this.config.maxRetries,
       backoffBaseMs: this.config.backoffBaseMs,
       ...sessionPath ? { sessionPath } : {},
       ...mcpServers ? { mcpServers } : {},
-      ...recoveryOpts?.nonRetryable ? { nonRetryable: recoveryOpts.nonRetryable } : {},
       ...onAttempt ? { onAttempt } : {}
     });
     const parsed = parseOutput(sessionResult.output);
@@ -1869,7 +2203,7 @@ ${sections.join("\n\n")}`;
 
 // src/supervisor/memory/store.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync4, mkdirSync } from "fs";
+import { existsSync as existsSync5, mkdirSync } from "fs";
 import { createRequire } from "module";
 import path9 from "path";
 var esmRequire = createRequire(import.meta.url);
@@ -1879,7 +2213,7 @@ var MemoryStore = class {
   hasVec;
   constructor(dbPath, embedder) {
     const dir = path9.dirname(dbPath);
-    if (!existsSync4(dir)) {
+    if (!existsSync5(dir)) {
       mkdirSync(dir, { recursive: true });
     }
     const Database = esmRequire("better-sqlite3");
@@ -2082,7 +2416,6 @@ var MemoryStore = class {
       case "createdAt":
         orderBy = "ORDER BY created_at DESC";
         break;
-      case "relevance":
       default:
         orderBy = "ORDER BY (access_count * MAX(0, 1.0 - (julianday('now') - julianday(last_accessed_at)) / 60.0)) DESC";
         break;
@@ -2222,128 +2555,6 @@ function rowToEntry(row) {
   };
 }
 
-// src/workflows/registry.ts
-import { existsSync as existsSync5 } from "fs";
-import { readdir as readdir4 } from "fs/promises";
-import path10 from "path";
-
-// src/workflows/loader.ts
-import { readFile as readFile6 } from "fs/promises";
-import { parse } from "yaml";
-import { z as z4 } from "zod";
-var workflowStepDefSchema = z4.object({
-  type: z4.literal("step").optional().default("step"),
-  agent: z4.string(),
-  dependsOn: z4.array(z4.string()).optional(),
-  prompt: z4.string().optional(),
-  sandbox: z4.enum(["writable", "readonly"]).optional(),
-  maxTurns: z4.number().int().positive().optional(),
-  mcpServers: z4.array(z4.string()).optional(),
-  recovery: z4.object({
-    maxRetries: z4.number().int().nonnegative().optional(),
-    nonRetryable: z4.array(z4.string()).optional()
-  }).optional(),
-  condition: z4.string().optional()
-});
-var workflowGateDefSchema = z4.object({
-  type: z4.literal("gate"),
-  dependsOn: z4.array(z4.string()).optional(),
-  description: z4.string(),
-  timeout: z4.string().optional(),
-  autoApprove: z4.boolean().optional()
-});
-var workflowHeaderSchema = z4.object({
-  name: z4.string().min(1),
-  description: z4.string().optional(),
-  steps: z4.record(z4.string(), z4.unknown())
-});
-function parseStepEntry(stepName, stepValue) {
-  const obj = stepValue;
-  const schema = obj.type === "gate" ? workflowGateDefSchema : workflowStepDefSchema;
-  const result = schema.safeParse(stepValue);
-  if (result.success) {
-    return { step: result.data, errors: [] };
-  }
-  return {
-    step: stepValue,
-    errors: result.error.issues.map(
-      (i) => `  - steps.${stepName}.${i.path.join(".")}: ${i.message}`
-    )
-  };
-}
-function parseSteps(rawSteps, filePath) {
-  if (Object.keys(rawSteps).length === 0) {
-    throw new Error(
-      `Invalid workflow definition in ${filePath}:
-  - steps: Workflow must have at least one step`
-    );
-  }
-  const steps = {};
-  const errors = [];
-  for (const [name, value] of Object.entries(rawSteps)) {
-    const { step, errors: stepErrors } = parseStepEntry(name, value);
-    if (stepErrors.length > 0) {
-      errors.push(...stepErrors);
-    } else {
-      steps[name] = step;
-    }
-  }
-  if (errors.length > 0) {
-    throw new Error(`Invalid workflow definition in ${filePath}:
-${errors.join("\n")}`);
-  }
-  return steps;
-}
-async function loadWorkflow(filePath) {
-  const content = await readFile6(filePath, "utf-8");
-  const raw = parse(content);
-  const headerResult = workflowHeaderSchema.safeParse(raw);
-  if (!headerResult.success) {
-    const issues = headerResult.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
-    throw new Error(`Invalid workflow definition in ${filePath}:
-${issues}`);
-  }
-  const { name, description, steps: rawSteps } = headerResult.data;
-  const steps = parseSteps(rawSteps, filePath);
-  return { name, description, steps };
-}
-
-// src/workflows/registry.ts
-var WorkflowRegistry = class {
-  builtInDir;
-  customDir;
-  workflows = /* @__PURE__ */ new Map();
-  constructor(builtInDir, customDir) {
-    this.builtInDir = builtInDir;
-    this.customDir = customDir;
-  }
-  async load() {
-    await this.loadFromDir(this.builtInDir);
-    if (this.customDir) {
-      await this.loadFromDir(this.customDir);
-    }
-  }
-  get(name) {
-    return this.workflows.get(name);
-  }
-  list() {
-    return [...this.workflows.values()];
-  }
-  has(name) {
-    return this.workflows.has(name);
-  }
-  async loadFromDir(dir) {
-    if (!existsSync5(dir)) return;
-    const files = await readdir4(dir);
-    for (const file of files) {
-      if (!file.endsWith(".yml") && !file.endsWith(".yaml")) continue;
-      const filePath = path10.join(dir, file);
-      const workflow = await loadWorkflow(filePath);
-      this.workflows.set(workflow.name, workflow);
-    }
-  }
-};
-
 // src/orchestrator.ts
 var MAX_PROMPT_SIZE = 100 * 1024;
 var MAX_METADATA_DEPTH = 5;
@@ -2353,7 +2564,6 @@ var Orchestrator = class extends NeoEventEmitter {
   config;
   semaphore;
   userMiddleware;
-  workflows = /* @__PURE__ */ new Map();
   registeredAgents = /* @__PURE__ */ new Map();
   _activeSessions = /* @__PURE__ */ new Map();
   idempotencyCache = /* @__PURE__ */ new Map();
@@ -2361,8 +2571,6 @@ var Orchestrator = class extends NeoEventEmitter {
   repoIndex = /* @__PURE__ */ new Map();
   runStore = new RunStore();
   journalDir;
-  builtInWorkflowDir;
-  customWorkflowDir;
   costJournal = null;
   eventJournal = null;
   webhookDispatcher = null;
@@ -2377,11 +2585,9 @@ var Orchestrator = class extends NeoEventEmitter {
     this.config = config;
     this.userMiddleware = options.middleware ?? [];
     this.journalDir = options.journalDir ?? getJournalsDir();
-    this.builtInWorkflowDir = options.builtInWorkflowDir;
-    this.customWorkflowDir = options.customWorkflowDir;
     this.skipOrphanRecovery = options.skipOrphanRecovery ?? false;
     for (const repo of config.repos) {
-      const resolvedPath = path11.resolve(repo.path);
+      const resolvedPath = path10.resolve(repo.path);
       const normalizedRepo = { ...repo, path: resolvedPath };
       this.repoIndex.set(resolvedPath, normalizedRepo);
     }
@@ -2414,9 +2620,6 @@ var Orchestrator = class extends NeoEventEmitter {
     );
   }
   // ─── Registration ──────────────────────────────────────
-  registerWorkflow(definition) {
-    this.workflows.set(definition.name, definition);
-  }
   registerAgent(agent) {
     this.registeredAgents.set(agent.name, agent);
   }
@@ -2490,13 +2693,6 @@ var Orchestrator = class extends NeoEventEmitter {
       );
     }
     this._costToday = await this.costJournal.getDayTotal();
-    if (this.builtInWorkflowDir) {
-      const registry = new WorkflowRegistry(this.builtInWorkflowDir, this.customWorkflowDir);
-      await registry.load();
-      for (const workflow of registry.list()) {
-        this.registerWorkflow(workflow);
-      }
-    }
     if (!this.skipOrphanRecovery) {
       await this.recoverOrphanedRuns();
     }
@@ -2568,21 +2764,18 @@ var Orchestrator = class extends NeoEventEmitter {
   buildDispatchContext(input) {
     const runId = input.runId ?? randomUUID3();
     const sessionId = randomUUID3();
-    const workflow = this.workflows.get(input.workflow);
-    if (!workflow) {
-      const available = [...this.workflows.keys()].join(", ") || "none";
+    const agent = this.registeredAgents.get(input.agent);
+    if (!agent) {
+      const available = [...this.registeredAgents.keys()].join(", ") || "none";
       throw new Error(
-        `Workflow "${input.workflow}" not found. Available workflows: ${available}. Check the workflow name or register it first.`
+        `Agent "${input.agent}" not found. Available agents: ${available}. Register the agent first.`
       );
     }
-    const [stepName, stepDef] = this.getFirstStep(workflow, input);
-    const agent = this.resolveStepAgent(stepDef, workflow.name);
     const repoConfig = this.resolveRepo(input.repo);
     const activeSession = {
       sessionId,
       runId,
-      workflow: input.workflow,
-      step: stepName,
+      step: "execute",
       agent: agent.name,
       repo: input.repo,
       status: "queued",
@@ -2594,8 +2787,6 @@ var Orchestrator = class extends NeoEventEmitter {
       runId,
       sessionId,
       startedAt: Date.now(),
-      stepName,
-      stepDef,
       agent,
       repoConfig,
       activeSession
@@ -2607,7 +2798,7 @@ var Orchestrator = class extends NeoEventEmitter {
     await this.persistRun({
       version: 1,
       runId,
-      workflow: input.workflow,
+      agent: agent.name,
       repo: input.repo,
       prompt: input.prompt,
       pid: process.pid,
@@ -2619,7 +2810,7 @@ var Orchestrator = class extends NeoEventEmitter {
     });
     try {
       const branchName = input.branch || repoConfig.defaultBranch;
-      const sessionDir = path11.join(this.config.sessions.dir, runId);
+      const sessionDir = path10.join(this.config.sessions.dir, runId);
       const info = await createSessionClone({
         repoPath: input.repo,
         branch: branchName,
@@ -2692,13 +2883,12 @@ var Orchestrator = class extends NeoEventEmitter {
     }
   }
   async runAgentSession(ctx, sessionPath) {
-    const { input, runId, sessionId, stepName, stepDef, agent, repoConfig, activeSession } = ctx;
+    const { input, runId, sessionId, agent, repoConfig, activeSession } = ctx;
     this.emit({
       type: "session:start",
       sessionId,
       runId,
-      workflow: input.workflow,
-      step: stepName,
+      step: "execute",
       agent: agent.name,
       repo: input.repo,
       metadata: input.metadata,
@@ -2718,15 +2908,13 @@ var Orchestrator = class extends NeoEventEmitter {
       }
     );
     const strategy = input.gitStrategy ?? repoConfig.gitStrategy ?? "branch";
-    const mcpServers = this.resolveMcpServers(stepDef, agent);
+    const mcpServers = this.resolveMcpServers(agent);
     const memoryContext = this.loadMemoryContext(input.repo);
-    const recoveryOpts = stepDef.recovery;
     const result = await executor.execute(
       {
         runId,
         sessionId,
         agent,
-        stepDef,
         repoConfig,
         repoPath: input.repo,
         prompt: input.prompt,
@@ -2748,7 +2936,7 @@ var Orchestrator = class extends NeoEventEmitter {
               runId,
               error: `Retrying with strategy: ${strategy2}`,
               attempt: attempt - 1,
-              maxRetries: recoveryOpts?.maxRetries ?? this.config.recovery.maxRetries,
+              maxRetries: this.config.recovery.maxRetries,
               willRetry: true,
               metadata: input.metadata,
               timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -2773,13 +2961,13 @@ var Orchestrator = class extends NeoEventEmitter {
     return result;
   }
   async finalizeDispatch(ctx, stepResult, idempotencyKey) {
-    const { input, runId, stepName, activeSession } = ctx;
+    const { input, runId, agent, activeSession } = ctx;
     const taskResult = {
       runId,
-      workflow: input.workflow,
+      agent: agent.name,
       repo: input.repo,
       status: stepResult.status === "success" ? "success" : "failure",
-      steps: { [stepName]: stepResult },
+      steps: { execute: stepResult },
       branch: stepResult.status === "success" && activeSession.sessionPath ? input.branch : void 0,
       costUsd: stepResult.costUsd,
       durationMs: Date.now() - ctx.startedAt,
@@ -2795,7 +2983,7 @@ var Orchestrator = class extends NeoEventEmitter {
     await this.persistRun({
       version: 1,
       runId,
-      workflow: input.workflow,
+      agent: agent.name,
       repo: input.repo,
       prompt: input.prompt,
       pid: process.pid,
@@ -2818,8 +3006,8 @@ var Orchestrator = class extends NeoEventEmitter {
   // ─── Private: Memory injection ──────────────────────────
   getMemoryStore() {
     if (!this.memoryStore) {
-      const supervisorDir = path11.join(getSupervisorsDir(), "supervisor");
-      this.memoryStore = new MemoryStore(path11.join(supervisorDir, "memory.sqlite"));
+      const supervisorDir = path10.join(getSupervisorsDir(), "supervisor");
+      this.memoryStore = new MemoryStore(path10.join(supervisorDir, "memory.sqlite"));
     }
     return this.memoryStore;
   }
@@ -2846,8 +3034,7 @@ var Orchestrator = class extends NeoEventEmitter {
       const costEntry = {
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         runId: ctx.runId,
-        workflow: ctx.input.workflow,
-        step: ctx.stepName,
+        step: "execute",
         sessionId,
         agent: ctx.agent.name,
         costUsd: sessionCost,
@@ -2916,8 +3103,8 @@ var Orchestrator = class extends NeoEventEmitter {
     if (!existsSync6(input.repo)) {
       throw new Error(`Validation error: repo path does not exist: ${input.repo}`);
     }
-    if (!this.workflows.has(input.workflow)) {
-      throw new Error(`Validation error: workflow "${input.workflow}" not found in registry`);
+    if (!this.registeredAgents.has(input.agent)) {
+      throw new Error(`Validation error: agent "${input.agent}" not found in registry`);
     }
     if (input.metadata !== void 0) {
       if (!isPlainObject(input.metadata)) {
@@ -2948,45 +3135,12 @@ var Orchestrator = class extends NeoEventEmitter {
     if (!idempotency?.enabled) return null;
     const key = idempotency.key ?? "metadata";
     if (key === "prompt") {
-      return `${input.workflow}:${input.repo}:${input.prompt}`;
-    }
-    return `${input.workflow}:${input.repo}:${JSON.stringify(input.metadata ?? {})}`;
-  }
-  getFirstStep(workflow, input) {
-    if (input.step) {
-      const step = workflow.steps[input.step];
-      if (!step || step.type === "gate") {
-        throw new Error(
-          `Step "${input.step}" not found in workflow "${workflow.name}" or is a gate step. Check the step name in the workflow definition.`
-        );
-      }
-      return [input.step, step];
-    }
-    for (const [name, step] of Object.entries(workflow.steps)) {
-      if (step.type === "gate") continue;
-      const stepDef = step;
-      if (!stepDef.dependsOn || stepDef.dependsOn.length === 0) {
-        return [name, stepDef];
-      }
-    }
-    const entries = Object.entries(workflow.steps);
-    const first = entries[0];
-    if (!first) {
-      throw new Error(`Workflow "${workflow.name}" has no steps`);
-    }
-    return [first[0], first[1]];
-  }
-  resolveStepAgent(step, workflowName) {
-    const agent = this.registeredAgents.get(step.agent);
-    if (!agent) {
-      throw new Error(
-        `Agent "${step.agent}" required by workflow "${workflowName}" not found in registry. Register the agent or check the workflow definition.`
-      );
+      return `${input.agent}:${input.repo}:${input.prompt}`;
     }
-    return agent;
+    return `${input.agent}:${input.repo}:${JSON.stringify(input.metadata ?? {})}`;
   }
   resolveRepo(repoPath) {
-    const repo = this.repoIndex.get(path11.resolve(repoPath));
+    const repo = this.repoIndex.get(path10.resolve(repoPath));
     if (repo) return repo;
     return {
       path: repoPath,
@@ -3002,17 +3156,11 @@ var Orchestrator = class extends NeoEventEmitter {
     return Math.max(0, (cap - this._costToday) / cap * 100);
   }
   // ─── Private: MCP server resolution ────────────────────
-  resolveMcpServers(stepDef, agent) {
+  resolveMcpServers(agent) {
     const configServers = this.config.mcpServers;
     if (!configServers) return void 0;
-    const names = /* @__PURE__ */ new Set();
-    if (stepDef.mcpServers) {
-      for (const name of stepDef.mcpServers) names.add(name);
-    }
-    if (agent.definition.mcpServers) {
-      for (const name of agent.definition.mcpServers) names.add(name);
-    }
-    if (names.size === 0) return void 0;
+    const names = agent.definition.mcpServers;
+    if (!names || names.length === 0) return void 0;
     const resolved = {};
     for (const name of names) {
       const serverConfig = configServers[name];
@@ -3034,8 +3182,8 @@ var Orchestrator = class extends NeoEventEmitter {
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         try {
-          const statePath = path11.join(supervisorsDir, entry.name, "state.json");
-          const raw = await readFile7(statePath, "utf-8");
+          const statePath = path10.join(supervisorsDir, entry.name, "state.json");
+          const raw = await readFile6(statePath, "utf-8");
           const state = JSON.parse(raw);
           if (state.status !== "running" || !state.port) continue;
           if (state.pid && !isProcessAlive(state.pid)) continue;
@@ -3088,13 +3236,176 @@ function objectDepth(obj, current = 0) {
 
 // src/supervisor/schemas.ts
 import { z as z5 } from "zod";
+
+// src/supervisor/decisions.ts
+import { randomUUID as randomUUID4 } from "crypto";
+import { appendFile as appendFile4, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
+import path11 from "path";
+import { z as z4 } from "zod";
+var decisionOptionSchema = z4.object({
+  key: z4.string(),
+  label: z4.string(),
+  description: z4.string().optional()
+});
+var decisionSchema = z4.object({
+  id: z4.string(),
+  question: z4.string(),
+  context: z4.string().optional(),
+  options: z4.array(decisionOptionSchema).optional(),
+  type: z4.string().default("generic"),
+  source: z4.string(),
+  metadata: z4.record(z4.string(), z4.unknown()).optional(),
+  createdAt: z4.string(),
+  expiresAt: z4.string().optional(),
+  defaultAnswer: z4.string().optional(),
+  answeredAt: z4.string().optional(),
+  answer: z4.string().optional(),
+  expiredAt: z4.string().optional()
+});
+var DecisionStore = class {
+  filePath;
+  dir;
+  dirCache = /* @__PURE__ */ new Set();
+  constructor(filePath) {
+    this.filePath = filePath;
+    this.dir = path11.dirname(filePath);
+  }
+  /**
+   * Create a new decision and persist it.
+   * @returns The generated decision ID
+   */
+  async create(input) {
+    await ensureDir(this.dir, this.dirCache);
+    const id = `dec_${randomUUID4().replace(/-/g, "").slice(0, 20)}`;
+    const decision = {
+      ...input,
+      id,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await appendFile4(this.filePath, `${JSON.stringify(decision)}
+`, "utf-8");
+    return id;
+  }
+  /**
+   * Answer a decision by ID.
+   * Reads all entries, updates the matching one, and rewrites the file.
+   */
+  async answer(id, answer) {
+    const decisions = await this.readAll();
+    const decision = decisions.find((d) => d.id === id);
+    if (!decision) {
+      throw new Error(`Decision not found: ${id}`);
+    }
+    if (decision.answer !== void 0) {
+      throw new Error(`Decision already answered: ${id}`);
+    }
+    decision.answer = answer;
+    decision.answeredAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.writeAll(decisions);
+  }
+  /**
+   * Get all pending decisions (unanswered, not expired, not timed out).
+   */
+  async pending() {
+    const decisions = await this.readAll();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return decisions.filter((d) => {
+      if (d.answer !== void 0) return false;
+      if (d.expiredAt !== void 0) return false;
+      if (d.expiresAt && d.expiresAt < now) return false;
+      return true;
+    });
+  }
+  /**
+   * Get answered decisions, optionally filtered by timestamp.
+   * @param since - ISO timestamp to filter decisions answered after this time
+   */
+  async answered(since) {
+    const decisions = await this.readAll();
+    return decisions.filter((d) => {
+      if (d.answer === void 0) return false;
+      if (since && d.answeredAt && d.answeredAt < since) return false;
+      return true;
+    });
+  }
+  /**
+   * Get a specific decision by ID.
+   */
+  async get(id) {
+    const decisions = await this.readAll();
+    return decisions.find((d) => d.id === id) ?? null;
+  }
+  /**
+   * Auto-answer expired decisions with their defaultAnswer.
+   * Decisions without defaultAnswer are marked as expired (expiredAt).
+   * @returns The decisions that were auto-answered or marked expired
+   */
+  async expire() {
+    const decisions = await this.readAll();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const expired = [];
+    for (const decision of decisions) {
+      if (decision.answer === void 0 && decision.expiredAt === void 0 && decision.expiresAt && decision.expiresAt < now) {
+        if (decision.defaultAnswer !== void 0) {
+          decision.answer = decision.defaultAnswer;
+          decision.answeredAt = now;
+        } else {
+          decision.expiredAt = now;
+        }
+        expired.push(decision);
+      }
+    }
+    if (expired.length > 0) {
+      await this.writeAll(decisions);
+    }
+    return expired;
+  }
+  // ─── Private helpers ─────────────────────────────────────
+  async readAll() {
+    let content;
+    try {
+      content = await readFile7(this.filePath, "utf-8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return [];
+      }
+      throw error;
+    }
+    const decisions = [];
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const parsed = decisionSchema.parse(JSON.parse(line));
+        decisions.push(parsed);
+      } catch (error) {
+        console.warn(
+          `[DecisionStore] Skipping malformed JSONL line: ${error instanceof Error ? error.message : "unknown error"}`
+        );
+      }
+    }
+    return decisions;
+  }
+  async writeAll(decisions) {
+    await ensureDir(this.dir, this.dirCache);
+    const content = `${decisions.map((d) => JSON.stringify(d)).join("\n")}
+`;
+    await writeFile3(this.filePath, content, "utf-8");
+  }
+};
+
+// src/supervisor/schemas.ts
 var wakeReasonSchema = z5.enum(["events", "timer", "active_runs", "forced"]);
-var supervisorDaemonStateSchema = z5.object({
+var supervisorBaseFieldsSchema = z5.object({
   pid: z5.number(),
   sessionId: z5.string(),
+  startedAt: z5.string(),
+  heartbeatCount: z5.number(),
+  totalCostUsd: z5.number(),
+  todayCostUsd: z5.number()
+});
+var supervisorDaemonStateSchema = supervisorBaseFieldsSchema.extend({
   port: z5.number(),
   cwd: z5.string(),
-  startedAt: z5.string(),
   lastHeartbeat: z5.string().optional(),
   heartbeatCount: z5.number().default(0),
   totalCostUsd: z5.number().default(0),
@@ -3130,6 +3441,7 @@ var activityEntrySchema = z5.object({
     "decision",
     "action",
     "error",
+    "warning",
     "event",
     "message",
     "thinking",
@@ -3153,10 +3465,32 @@ var logBufferEntrySchema = z5.object({
   consolidatedAt: z5.string().optional()
 });
 var internalEventKindSchema = z5.enum(["consolidation_timer", "active_run_check"]);
+var supervisorStatusSchema = supervisorBaseFieldsSchema.extend({
+  status: z5.enum(["running", "idle", "stopping"]),
+  lastHeartbeat: z5.string(),
+  activeRunCount: z5.number(),
+  recentActivitySummary: z5.array(z5.string())
+});
+var activityTypeFilterSchema = z5.enum([
+  "decision",
+  "action",
+  "error",
+  "event",
+  "message",
+  "plan",
+  "dispatch"
+]);
+var activityQueryOptionsSchema = z5.object({
+  limit: z5.number().int().min(1).max(500).default(50).optional(),
+  offset: z5.number().int().min(0).default(0).optional(),
+  type: activityTypeFilterSchema.optional(),
+  since: z5.string().datetime().optional(),
+  until: z5.string().datetime().optional()
+});
 
 // src/supervisor/activity-log.ts
-import { randomUUID as randomUUID4 } from "crypto";
-import { appendFile as appendFile4, readFile as readFile8, rename, stat } from "fs/promises";
+import { randomUUID as randomUUID5 } from "crypto";
+import { appendFile as appendFile5, readFile as readFile8, rename, stat } from "fs/promises";
 import path12 from "path";
 var ACTIVITY_FILE = "activity.jsonl";
 var MAX_SIZE_BYTES = 10 * 1024 * 1024;
@@ -3175,14 +3509,14 @@ var ActivityLog = class {
     await this.checkRotation();
     const line = `${JSON.stringify(entry)}
 `;
-    await appendFile4(this.filePath, line, "utf-8");
+    await appendFile5(this.filePath, line, "utf-8");
   }
   /**
    * Create and append a new entry with auto-generated id and timestamp.
    */
   async log(type, summary, detail) {
     await this.append({
-      id: randomUUID4(),
+      id: randomUUID5(),
       type,
       summary,
       detail,
@@ -3224,15 +3558,15 @@ var ActivityLog = class {
 };
 
 // src/supervisor/daemon.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID7 } from "crypto";
 import { existsSync as existsSync8 } from "fs";
-import { mkdir as mkdir7, readFile as readFile12, rm as rm2, writeFile as writeFile6 } from "fs/promises";
-import { homedir as homedir3 } from "os";
+import { mkdir as mkdir7, readFile as readFile12, rm as rm2, writeFile as writeFile7 } from "fs/promises";
+import { homedir as homedir5 } from "os";
 import path15 from "path";
 
 // src/supervisor/event-queue.ts
-import { watch } from "fs";
-import { readFile as readFile9, writeFile as writeFile3 } from "fs/promises";
+import { watch as watch2 } from "fs";
+import { readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
 var EventQueue = class {
   queue = [];
   seenIds = /* @__PURE__ */ new Set();
@@ -3282,13 +3616,14 @@ var EventQueue = class {
   /**
    * Drain and group events: deduplicates messages by content,
    * keeps webhooks and run completions separate.
+   * Returns both grouped events AND original raw events for later marking as processed.
    */
   drainAndGroup() {
-    const events = this.drain();
+    const rawEvents = this.drain();
     const messageMap = /* @__PURE__ */ new Map();
     const webhooks = [];
     const runCompletions = [];
-    for (const event of events) {
+    for (const event of rawEvents) {
       if (event.kind === "message") {
         const key = event.data.text.trim().toLowerCase();
         const existing = messageMap.get(key);
@@ -3304,9 +3639,12 @@ var EventQueue = class {
       }
     }
     return {
-      messages: [...messageMap.values()],
-      webhooks,
-      runCompletions
+      grouped: {
+        messages: [...messageMap.values()],
+        webhooks,
+        runCompletions
+      },
+      rawEvents
     };
   }
   size() {
@@ -3319,9 +3657,8 @@ var EventQueue = class {
   async startWatching(inboxPath, eventsPath) {
     for (const p of [inboxPath, eventsPath]) {
       try {
-        await writeFile3(p, "", { flag: "a" });
-      } catch (err) {
-        console.error(`[EventQueue] Failed to ensure file exists: ${p}`, err);
+        await writeFile4(p, "", { flag: "a" });
+      } catch {
       }
     }
     this.watchJsonlFile(inboxPath, "message");
@@ -3370,14 +3707,12 @@ var EventQueue = class {
   }
   watchJsonlFile(filePath, kind) {
     try {
-      const watcher = watch(filePath, () => {
-        this.readNewLines(filePath, kind).catch((err) => {
-          console.error(`[EventQueue] Failed to read new lines from ${filePath}:`, err);
+      const watcher = watch2(filePath, () => {
+        this.readNewLines(filePath, kind).catch(() => {
         });
       });
       this.watchers.push(watcher);
-    } catch (err) {
-      console.error(`[EventQueue] Cannot watch file (may not exist yet): ${filePath}`, err);
+    } catch {
     }
   }
   async readNewLines(filePath, kind) {
@@ -3461,24 +3796,23 @@ var EventQueue = class {
         return line;
       });
       if (changed) {
-        await writeFile3(filePath, updated.join("\n"), "utf-8");
+        await writeFile4(filePath, updated.join("\n"), "utf-8");
         this.fileOffsets.set(filePath, updated.join("\n").length);
       }
-    } catch (err) {
-      console.error(`[EventQueue] Failed to mark events as processed in ${filePath}:`, err);
+    } catch {
     }
   }
 };
 
 // src/supervisor/heartbeat.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 import { existsSync as existsSync7 } from "fs";
-import { readdir as readdir5, readFile as readFile11, writeFile as writeFile5 } from "fs/promises";
-import { homedir as homedir2 } from "os";
+import { readdir as readdir4, readFile as readFile11, writeFile as writeFile6 } from "fs/promises";
+import { homedir as homedir4 } from "os";
 import path14 from "path";
 
 // src/supervisor/log-buffer.ts
-import { appendFile as appendFile5, readFile as readFile10, stat as stat2, writeFile as writeFile4 } from "fs/promises";
+import { appendFile as appendFile6, readFile as readFile10, stat as stat2, writeFile as writeFile5 } from "fs/promises";
 import path13 from "path";
 var LOG_BUFFER_FILE = "log-buffer.jsonl";
 var MAX_FILE_BYTES = 1024 * 1024;
@@ -3532,7 +3866,7 @@ async function markConsolidated(dir, ids) {
       updated.push(line);
     }
   }
-  await writeFile4(filePath, `${updated.join("\n")}
+  await writeFile5(filePath, `${updated.join("\n")}
 `, "utf-8");
 }
 async function compactLogBuffer(dir) {
@@ -3566,37 +3900,31 @@ async function compactLogBuffer(dir) {
     result = `${kept.join("\n")}
 `;
   }
-  await writeFile4(filePath, result, "utf-8");
+  await writeFile5(filePath, result, "utf-8");
 }
 async function appendLogBuffer(dir, entry) {
   try {
-    await appendFile5(bufferPath(dir), `${JSON.stringify(entry)}
+    await appendFile6(bufferPath(dir), `${JSON.stringify(entry)}
 `, "utf-8");
   } catch {
   }
 }
 
 // src/supervisor/prompt-builder.ts
-var ROLE = `You are the neo autonomous supervisor \u2014 the engineering manager your agents deserve.
-
-You don't write code. You make sure the right work happens, at the right time, by the right agent \u2014 and you follow through until it's done.
-
-<mindset>
-- You are accountable for delivery. A task in the queue that nobody is working on is YOUR problem.
-- Be the manager you'd want: give agents clear context, check their output, unblock them when they're stuck.
-- Think before dispatching. Read the task context, understand what's needed, craft a prompt that sets the agent up to succeed on the first try.
-- When a run completes, ALWAYS read its output. Verify the result meets the acceptance criteria. If it doesn't, figure out why and act \u2014 re-dispatch with better instructions, file a follow-up, or escalate.
-- When a run fails, diagnose before retrying. Read the output, check if the prompt was unclear, if the branch had conflicts, if the agent hit a known issue. Fix the root cause.
-- Never let work stall silently. If a run has been active too long, check on it. If a task is blocked, find what unblocks it. If nothing is happening, ask why.
-</mindset>
-
-<behavioral-contract>
-- Your ONLY visible output is \`neo log\` commands. The TUI shows these and nothing else.
-- Your text output is NEVER shown to anyone \u2014 every token of text is wasted cost.
-- Produce tool calls, not explanations. Do not narrate your reasoning.
-- You NEVER modify code \u2014 that is the agents' job.
-- You can read code in the available repos (path in \`neo repos\` command)
-</behavioral-contract>`;
+var ROLE = `You are the neo autonomous supervisor \u2014 accountable for delivery across parallel initiatives.
+
+You do not write code directly; you ensure the right work is assigned, executed, reviewed, and completed by the right agent.`;
+var OPERATING_PRINCIPLES = `### Operating principles
+
+- Own delivery end-to-end: any queued task without an active owner is your responsibility.
+- Operate like a strong engineering lead: provide clear context, dispatch deliberately, validate outcomes, and remove blockers quickly.
+- On run completion: read \`neo runs <runId>\`, verify acceptance criteria, then decide next action (done, follow-up, redispatch, escalate).
+- On run failure: diagnose root cause before retrying (prompt quality, branch conflict, known issue, environment/tooling), then fix the cause.
+- Prevent silent stalls: monitor long-running jobs, detect blocked work early, and actively unblock.
+- Keep initiative boundaries strict: decisions for initiative A must not be influenced by unrelated state from B.
+- Your user-visible channel is \`neo log\` only; produce concise tool calls (not reasoning/explanations) and avoid wasted tokens.
+- You may inspect repositories available via \`neo repos\`, read-only to launch agents.
+- Task hygiene is non-negotiable: update task outcomes EVERY heartbeat. A task without a current outcome is a blind spot.`;
 var COMMANDS = `### Dispatching agents
 \`\`\`bash
 neo run <agent> --prompt "..." --repo <path> --branch <name> [--priority critical|high|medium|low] [--meta '<json>']
@@ -3607,7 +3935,7 @@ neo run <agent> --prompt "..." --repo <path> --branch <name> [--priority critica
 | \`--prompt\` | always | Task description for the agent |
 | \`--repo\` | always | Target repository path |
 | \`--branch\` | always | Branch name for the isolated clone |
-| \`--priority\` | no | \`critical\`, \`high\`, \`medium\`, \`low\` |
+| \`--priority\` | optional | \`critical\`, \`high\`, \`medium\`, \`low\` |
 | \`--meta\` | **always** | JSON with \`"label"\` for identification + \`"ticketId"\`, \`"stage"\`, etc. |
 
 All agents require \`--branch\`. Each agent session runs in an isolated clone on that branch.
@@ -3635,6 +3963,27 @@ neo memory search "keyword"
 neo memory list --type fact
 \`\`\`
 
+### Configuration
+\`\`\`bash
+neo config get <key>                    # read a value (dot notation)
+neo config set <key> <value> --global   # update global config (~/.neo/config.yml)
+neo config list                         # show full merged config
+\`\`\`
+
+Keys use dot notation (e.g., \`budget.dailyCapUsd\`, \`supervisor.dailyCapUsd\`, \`concurrency.maxSessions\`).
+Changes are hot-reloaded \u2014 the new values take effect at the next heartbeat.
+
+Use cases: raise budget cap mid-run, adjust concurrency, change heartbeat timeout.
+
+### Decisions
+When you need human input on something that cannot be decided autonomously:
+\`\`\`bash
+neo decision create "<question>" --options "key1:label1,key2:label2:description" [--default <key>] [--expires-in 24h] [--context "..."]
+neo decision list                    # show pending decisions
+neo decision answer <id> <answer>    # answer a decision (usually done by human via TUI)
+\`\`\`
+The decision ID is returned by \`create\`. If no answer arrives before expiration, the \`--default\` answer is applied automatically (or the decision expires without resolution).
+
 ### Reporting
 \`\`\`bash
 neo log <type> "<message>"   # visible in TUI only
@@ -3643,7 +3992,8 @@ var COMMANDS_COMPACT = `### Commands (reference)
 \`neo run <agent> --prompt "..." --repo <path> --branch <name> --meta '{"label":"T1-auth",...}'\`
 \`neo runs [--short | <runId>]\` \xB7 \`neo runs --short --status running\` \xB7 \`neo cost --short\`
 \`neo memory write|update|forget|search|list\` \xB7 \`neo log <type> "<msg>"\`
-ALWAYS read run output on completion: \`neo runs <runId>\` \u2014 it contains the agent's structured result.`;
+\`neo config get <key>\` \xB7 \`neo config set <key> <value> --global\` \xB7 \`neo config list\`
+\`neo decision create "<question>" --options "..." [--default <key>]\` \xB7 \`neo decision list\``;
 var HEARTBEAT_RULES = `### Heartbeat lifecycle
 
 <decision-tree>
@@ -3653,7 +4003,8 @@ var HEARTBEAT_RULES = `### Heartbeat lifecycle
 4. EVENTS? \u2014 process run completions, messages, webhooks. Parse agent JSON output.
 5. FOLLOW-UPS? \u2014 check CI (\`gh pr checks\`), deferred dispatches.
 6. DISPATCH \u2014 route work to agents. Mark tasks \`in_progress\`, add ACTIVE to focus.
-7. YIELD \u2014 log your decisions and yield. Do not poll. Completions arrive at future heartbeats.
+7. UPDATE TASKS \u2014 review ALL in_progress/blocked tasks. For each: confirm status matches reality (run still active? PR merged? blocked resolved?). Update outcomes immediately \u2014 do not defer to next heartbeat.
+8. SERIALIZE & YIELD \u2014 rewrite focus (see <focus>), log your decisions, and yield. Do not poll.
 </decision-tree>
 
 <run-monitoring>
@@ -3664,43 +4015,21 @@ Runs are your agents in the field. You MUST actively track them:
 - **Active runs**: check \`neo runs --short --status running\` to verify your runs are still alive. If a run disappeared, investigate.
 </run-monitoring>
 
-<orchestration>
-When managing a multi-task initiative (architect decomposition, feature with milestones):
-
-**Branch strategy:**
-- Use ONE branch per initiative: \`feat/YC-2670-kanban-improvements\` \u2014 all tasks in the initiative push commits to this same branch
-- Each agent inherits the previous task's work without needing merges
-- The first task creates the branch. Subsequent tasks reuse it with the same \`--branch\` flag
-- Open the PR after the first task completes. Later tasks push additional commits to the same PR
-- Tasks within an initiative MUST be dispatched sequentially (not in parallel) since they share a branch
-- Independent initiatives CAN run in parallel on different branches
-
-**Before dispatching a task:**
-1. Run the task's \`--category\` command to retrieve context (architect plan, previous run output)
-2. Write a detailed \`--prompt\` with: task description, acceptance criteria, files to modify, and context from previous tasks in the initiative
-3. Include results from completed sibling tasks: what was built, which files were changed, which APIs were added
-4. Always pass the same \`--branch\` as previous tasks in the initiative
-
-**After a run completes:**
-1. \`neo runs <runId>\` \u2014 read the FULL output, not just status
-2. Extract: PR URL/number, files changed, test results, any issues
-3. Verify the output matches the task's acceptance criteria
-4. If the agent opened a PR: dispatch \`reviewer\` in parallel with CI (do not wait for CI)
-5. Update the task outcome and log the result with concrete details (PR#, branch, what was done)
-6. Update the initiative note with the completed milestone
-
-**Cross-task context:**
-- Each task builds on previous ones. When dispatching T6, tell the agent what T1-T5 produced (commits, APIs added, files changed)
-- Store key outputs as facts if they affect future tasks: "T5 added dateRange param to fetchAllFstRecords"
-- Use notes for initiative-level plans: \`cat notes/plan-<initiative>.md\` \u2014 update as tasks complete
-</orchestration>
-
-<rules>
-- Work queue IS your plan. Never re-plan existing tasks.
-- Maximize parallelism: dispatch independent tasks in the same heartbeat.
-- After dispatch: update focus, yield immediately. Do NOT wait for results.
-- Deferred work (CI pending): MUST check at next heartbeat.
-</rules>`;
+<multi-task-initiatives>
+**Branch strategy:** one branch per initiative \u2014 all tasks push to the same branch sequentially (never in parallel). First task creates the branch; open PR after it completes. Later tasks add commits to the same PR. Independent initiatives CAN run in parallel on different branches.
+
+**Dispatch quality:** write a detailed \`--prompt\` with acceptance criteria, files to modify, and context from completed sibling tasks (commits, APIs added, files changed). When dispatching task N, summarize what tasks 1..N-1 produced.
+
+**Post-completion:** if agent opened a PR, dispatch \`reviewer\` in parallel with CI (do not wait). Update task outcome with concrete details (PR#, what was done) and update the initiative note.
+
+**Task tracking discipline:**
+- On dispatch: \`neo memory update <id> --outcome in_progress\` immediately \u2014 never dispatch without updating the task.
+- On run completion: update to \`done\` with details OR \`blocked\` with reason. Do this in the SAME heartbeat you read the run output.
+- On run failure: update to \`blocked\` with root cause. Never leave a failed run's task as \`in_progress\`.
+- Every heartbeat: cross-check active tasks against \`neo runs --short\`. If a run finished but the task is still \`in_progress\`, something was missed \u2014 fix it now.
+
+**Memory:** store key outputs as facts if they affect future tasks (e.g. "T5 added dateRange param to fetchAllFstRecords").
+</multi-task-initiatives>`;
 var REPORTING_RULES = `### Reporting
 
 \`neo log\` is your ONLY visible output. Use telegraphic format.
@@ -3711,19 +4040,14 @@ neo log action "<agent> <repo>:<branch> run:<runId> | <context>"
 neo log discovery "<what> in <where>"
 </log-format>
 
-<examples>
-<example type="good">
+<examples type="good">
 neo log decision "YC-42 \u2192 developer | clear spec, complexity 3"
 neo log action "developer standards:feat/YC-42-auth run:5900a64a | task T1"
 neo log discovery "CI requires node 20 in api-service"
-</example>
-<example type="bad">
-neo log plan "Good! Now let me check the status and update things accordingly."
-neo log decision "Heartbeat #309: Idle cycle - no action required. All 4 repositories stable."
-neo log action "I've dispatched a developer agent to work on the authentication feature."
-</example>
 </examples>`;
-var MEMORY_RULES_CORE = `### Memory
+function buildMemoryRulesCore(supervisorDir) {
+  const notesDir = `${supervisorDir}/notes`;
+  return `### Memory
 
 <memory-types>
 | Type | Store when | TTL |
@@ -3736,7 +4060,7 @@ var MEMORY_RULES_CORE = `### Memory
 </memory-types>
 
 <memory-rules>
-- Focus MUST use structured format: ACTIVE/PENDING/WAITING/PROCESSED lines only.
+- Focus is free-form working memory \u2014 rewrite at end of EVERY heartbeat (see <focus>).
 - NEVER store: file counts, line numbers, completed work details, data available via \`neo runs <id>\`.
 - After PR merge: forget related facts unless they are reusable architectural truths.
 - Pattern escalation: same failure 3+ times \u2192 write a \`procedure\`.
@@ -3744,53 +4068,43 @@ var MEMORY_RULES_CORE = `### Memory
 </memory-rules>
 
 <task-workflow>
-Tasks are your work queue. The work queue section above shows them with markers (\`\u25CB\` pending, \`[ACTIVE]\` in_progress, \`[BLOCKED]\` blocked).
+Queue markers: \u25CB pending \xB7 [ACTIVE] in_progress \xB7 [BLOCKED] blocked.
+Create tasks for: incoming tickets, architect decompositions, sub-tickets, follow-ups, CI fixes.
+- \`--tags "initiative:<name>"\` \u2014 groups related tasks
+- \`--tags "depends:mem_<id>"\` \u2014 blocks until dependency is done
+- \`--category\` \u2014 retrieval command (MANDATORY). Examples: \`"neo runs <runId>"\` \xB7 \`"cat ${notesDir}/plan-feature.md"\` \xB7 \`"API-retrieve-a-page <notionPageId>"\`
+Lifecycle: create \u2192 in_progress (on dispatch) \u2192 done | blocked | abandoned
 
-Create a task for any planned work: incoming tickets, architect decompositions, refiner sub-tickets, follow-up actions, CI fixes.
-- \`--severity critical|high|medium|low\` \u2014 dispatch highest severity first
-- \`--tags "initiative:<name>"\` \u2014 groups related tasks (shown as [initiative] headers in queue)
-- \`--tags "depends:mem_<id>"\` \u2014 task cannot start until dependency is done
-- \`--category\` \u2014 **MANDATORY** \u2014 the command to retrieve context for this task (shown as \`\u2192 <command>\` in queue)
+**Update frequency:** task outcomes MUST be updated in the same heartbeat as the triggering event. Never defer a task update to "next heartbeat" \u2014 by then you will have forgotten. Stale task states cause duplicate dispatches and wasted budget.
 
-**Context retrieval rule**: every task and relevant memory MUST include a way for you to access its source context at a future heartbeat. You are stateless \u2014 without this, you lose the context.
-- Agent output: \`--category "neo runs <runId>"\`
-- Note/plan: \`--category "cat notes/plan-feature.md"\`
-- Notion ticket: \`--category "API-retrieve-a-page <notionPageId>"\`
-- Architect decomposition: \`--category "neo runs <architectRunId>"\` (contains milestones + tasks)
-
-Lifecycle: create \u2192 \`neo memory update <id> --outcome in_progress\` (on dispatch) \u2192 \`done\` (on success) / \`blocked\` (on failure, will retry) / \`abandoned\` (terminal, won't retry)
-
-Dispatch rule: pick the highest-severity task with no unmet dependencies. Dispatch independent tasks in parallel. Before dispatching, run the \`--category\` command to retrieve task context.
+**Mandatory cross-check:** before yielding, verify that:
+1. Every dispatched run has a corresponding \`in_progress\` task
+2. Every completed run has a corresponding \`done\` or \`blocked\` task
+3. No task is \`in_progress\` without an active run (unless manually worked)
 </task-workflow>
 
-<focus-format>
-ACTIVE: <runId> <agent> "<task>" branch:<name>
-PENDING: <taskId> "<description>" depends:<taskId>
-WAITING: <what> since:HB<N>
-PROCESSED: <runId> \u2192 <outcome> PR#<N>
-</focus-format>
-
-<notes>
-
-You have a notes/ directory for rich markdown documents that persist across heartbeats.
+<focus>
+You are stateless between heartbeats. Focus is your scratchpad \u2014 the only thing future-you will read before acting.
 
-When to use notes:
-- Architect decompositions: save the full plan with milestones, tasks, acceptance criteria, dependency graph
-- Initiative tracking: progress log with completed/pending tasks, PRs merged, blockers
-- Complex debugging: accumulate findings across multiple heartbeats
-- Review checklists: aggregate reviewer feedback across fix/review cycles
+Write it like a handoff note to yourself: what's happening, what you decided, what to do next, what to watch for. Free-form. No format imposed. The only rule: if you don't write it down, you lose it.
 
-How to use:
-- Write: \`cat > notes/plan-YC-2670-kanban.md << 'EOF' ... EOF\` \u2014 include milestones checklist, acceptance criteria, file paths
-- Read: \`cat notes/plan-YC-2670-kanban.md\` \u2014 retrieve full context at any heartbeat
-- Link to tasks: \`neo memory write --type task --category "cat notes/plan-YC-2670-kanban.md" "M3: UI"\`
-- Update: check off completed milestones, add PR numbers, note blockers after each task completes
-- Cleanup: \`rm notes/plan-*.md\` when the initiative is done
+Rewrite focus at the END of every heartbeat. Never leave it empty after a heartbeat with activity.
+</focus>
 
-Use notes for every initiative with 3+ tasks. They are your project management tool.
+<notes>
+Notes directory: \`${notesDir}/\`
+Use notes for any initiative with 3+ tasks (persists across heartbeats).
+- Write: \`cat > ${notesDir}/plan-<initiative>.md << 'EOF' ... EOF\`
+- Link to tasks: \`--category "cat ${notesDir}/plan-<initiative>.md"\`
+- Update after each task: check off milestones, add PR numbers, note blockers
+- Delete when initiative is done
+Use cases: architect decompositions, initiative tracking, debugging across heartbeats, review checklists.
 </notes>`;
-var MEMORY_RULES_EXAMPLES = `<memory-examples>
-neo memory write --type focus --expires 2h "ACTIVE: 5900a64a developer 'T1' branch:feat/x (cat notes/plan-YC-2670-kanban.md)"
+}
+function buildMemoryRulesExamples(supervisorDir) {
+  const notesDir = `${supervisorDir}/notes`;
+  return `<memory-examples>
+neo memory write --type focus --expires 2h "ACTIVE: 5900a64a developer 'T1' branch:feat/x (cat ${notesDir}/plan-YC-2670-kanban.md)"
 neo memory write --type fact --scope /repo "main branch uses protected merges \u2014 agents must create PRs, never push directly"
 neo memory write --type fact --scope /repo "pnpm build must pass before push \u2014 CI does not rebuild, run 2g589f34a5a failed without it"
 neo memory write --type procedure --scope /repo "After architect run: parse milestones from JSON output, create one task per milestone with --tags initiative:<name>"
@@ -3800,42 +4114,156 @@ neo memory write --type task --scope /repo --severity high --category "neo runs
 neo memory update <id> --outcome in_progress|done|blocked|abandoned
 neo memory forget <id>
 </memory-examples>`;
+}
+function buildRoleSection(heartbeatCount, label) {
+  const suffix = label ? ` (${label})` : "";
+  return `<role>
+${ROLE}
+Heartbeat #${heartbeatCount}${suffix}
+</role>`;
+}
 function getCommandsSection(heartbeatCount) {
   return heartbeatCount <= 3 ? COMMANDS : COMMANDS_COMPACT;
 }
-function buildContextSections(opts) {
-  const parts = [];
-  if (opts.repos.length > 0) {
-    const repoList = opts.repos.map((r) => `- ${r.path} (branch: ${r.defaultBranch})`).join("\n");
-    parts.push(`Repositories:
-${repoList}`);
-  }
-  if (opts.mcpServerNames.length > 0) {
-    const mcpList = opts.mcpServerNames.map((n) => `- ${n}`).join("\n");
-    parts.push(`Integrations (MCP):
-${mcpList}`);
-  }
-  parts.push(
-    `Budget: $${opts.budgetStatus.todayUsd.toFixed(2)} / $${opts.budgetStatus.capUsd.toFixed(2)} (${opts.budgetStatus.remainingPct.toFixed(0)}% remaining)`
-  );
-  return parts;
+function buildReferenceSection(heartbeatCount) {
+  return `<reference>
+${getCommandsSection(heartbeatCount)}
+</reference>`;
 }
-function buildMemorySection(memories, supervisorDir) {
+function buildFocusSection(memories) {
   const focusEntries = memories.filter((m) => m.type === "focus");
-  const factEntries = memories.filter((m) => m.type === "fact");
-  const procedureEntries = memories.filter((m) => m.type === "procedure");
-  const feedbackEntries = memories.filter((m) => m.type === "feedback");
-  const parts = [];
   if (focusEntries.length > 0) {
     const lines = focusEntries.map((m) => `- ${m.content}`).join("\n");
-    parts.push(`<focus>
+    return `<focus>
 ${lines}
-</focus>`);
-  } else {
-    parts.push(
-      "<focus>\n(empty \u2014 use neo memory write --type focus to set working context)\n</focus>"
-    );
+</focus>`;
   }
+  return "<focus>\n(empty \u2014 use neo memory write --type focus to set working context)\n</focus>";
+}
+function buildPendingDecisionsSection(decisions) {
+  if (!decisions || decisions.length === 0) {
+    return "";
+  }
+  const lines = [];
+  for (const d of decisions) {
+    const expiry = d.expiresAt ? ` (expires: ${d.expiresAt})` : "";
+    const defaultHint = d.defaultAnswer ? ` [default: ${d.defaultAnswer}]` : "";
+    lines.push(`- **${d.id}**: ${d.question}${expiry}${defaultHint}`);
+    if (d.options && d.options.length > 0) {
+      for (const opt of d.options) {
+        const desc = opt.description ? ` \u2014 ${opt.description}` : "";
+        lines.push(`    \u2022 \`${opt.key}\`: ${opt.label}${desc}`);
+      }
+    }
+    if (d.context) {
+      lines.push(`    Context: ${d.context}`);
+    }
+  }
+  return `Pending decisions (${decisions.length}):
+${lines.join("\n")}
+
+To answer a decision, emit a \`decision:answer\` event:
+\`\`\`bash
+neo event emit decision:answer --data '{"id":"<decision_id>","answer":"<option_key>"}'
+\`\`\``;
+}
+function buildAnsweredDecisionsSection(decisions) {
+  if (!decisions || decisions.length === 0) {
+    return "";
+  }
+  const lines = decisions.map((d) => {
+    const answeredBy = d.source ? ` (by ${d.source})` : "";
+    return `- ${d.id}: "${d.question}" \u2192 **${d.answer}**${answeredBy}`;
+  });
+  return `Recent decisions (${decisions.length}):
+${lines.join("\n")}`;
+}
+function buildFullContext(opts) {
+  const parts = [];
+  parts.push(buildFocusSection(opts.memories));
+  const workQueue = buildWorkQueueSection(opts.memories);
+  if (workQueue) {
+    parts.push(workQueue);
+  }
+  if (opts.activeRuns.length > 0) {
+    parts.push(`Active runs:
+${opts.activeRuns.map((r) => `- ${r}`).join("\n")}`);
+  }
+  const recentActions = buildRecentActionsSection(opts.recentActions);
+  if (recentActions) {
+    parts.push(recentActions);
+  }
+  const pendingDecisions = buildPendingDecisionsSection(opts.pendingDecisions);
+  if (pendingDecisions) {
+    parts.push(pendingDecisions);
+  }
+  const answeredDecisions = buildAnsweredDecisionsSection(opts.answeredDecisions);
+  if (answeredDecisions) {
+    parts.push(answeredDecisions);
+  }
+  parts.push(buildKnowledgeSection(opts.memories));
+  parts.push(...buildEnvironmentSections(opts));
+  parts.push(`Events:
+${buildEventsSection(opts.grouped)}`);
+  return `<context>
+${parts.join("\n\n")}
+</context>`;
+}
+function buildCompactionContext(opts) {
+  const parts = [];
+  parts.push(buildFocusSection(opts.memories));
+  parts.push(buildKnowledgeSection(opts.memories));
+  const workQueue = buildWorkQueueSection(opts.memories);
+  if (workQueue) {
+    parts.push(workQueue);
+  }
+  parts.push(...buildEnvironmentSections(opts));
+  return `<context>
+${parts.join("\n\n")}
+</context>`;
+}
+function buildBaseInstructions(opts, options) {
+  const parts = [];
+  parts.push(OPERATING_PRINCIPLES);
+  parts.push(HEARTBEAT_RULES);
+  parts.push(REPORTING_RULES);
+  parts.push(buildMemoryRulesCore(opts.supervisorDir));
+  if (options.includeExamples) {
+    parts.push(buildMemoryRulesExamples(opts.supervisorDir));
+  }
+  if (opts.customInstructions) {
+    parts.push(`### Custom instructions
+${opts.customInstructions}`);
+  }
+  return parts;
+}
+function wrapInstructions(parts) {
+  return `<instructions>
+${parts.join("\n\n")}
+</instructions>`;
+}
+function buildEnvironmentSections(opts) {
+  const parts = [];
+  if (opts.repos.length > 0) {
+    const repoList = opts.repos.map((r) => `- ${r.path} (branch: ${r.defaultBranch})`).join("\n");
+    parts.push(`Repositories:
+${repoList}`);
+  }
+  if (opts.mcpServerNames.length > 0) {
+    const mcpList = opts.mcpServerNames.map((n) => `- ${n}`).join("\n");
+    parts.push(`Integrations (MCP):
+${mcpList}`);
+  }
+  parts.push(
+    `Budget: $${opts.budgetStatus.todayUsd.toFixed(2)} / $${opts.budgetStatus.capUsd.toFixed(2)} (${opts.budgetStatus.remainingPct.toFixed(0)}% remaining)`
+  );
+  return parts;
+}
+function buildKnowledgeSection(memories) {
+  const factEntries = memories.filter((m) => m.type === "fact");
+  const procedureEntries = memories.filter((m) => m.type === "procedure");
+  const feedbackEntries = memories.filter((m) => m.type === "feedback");
+  const parts = [];
   if (factEntries.length > 0) {
     const byScope = /* @__PURE__ */ new Map();
     for (const m of factEntries) {
@@ -3871,12 +4299,6 @@ ${lines}`);
     parts.push(`Recurring review issues:
 ${lines}`);
   }
-  parts.push(`For detailed plans and checklists, use notes:
-\`\`\`bash
-cat > ${supervisorDir}/notes/plan-feature.md << 'EOF'
-<your detailed plan here>
-EOF
-\`\`\``);
   return parts.join("\n\n");
 }
 var DONE_OUTCOMES = /* @__PURE__ */ new Set(["done", "abandoned"]);
@@ -3925,18 +4347,72 @@ function groupTasksByInitiative(tasks) {
   }
   return groups;
 }
+var SEVERITY_ORDER = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3
+};
+function bySeverity(a, b) {
+  const aOrder = SEVERITY_ORDER[a.severity ?? "medium"] ?? 2;
+  const bOrder = SEVERITY_ORDER[b.severity ?? "medium"] ?? 2;
+  return aOrder - bOrder;
+}
+function partitionTasks(tasks) {
+  const active = [];
+  const blocked = [];
+  const pending = [];
+  for (const t of tasks) {
+    if (t.outcome === "in_progress") active.push(t);
+    else if (t.outcome === "blocked") blocked.push(t);
+    else pending.push(t);
+  }
+  return { active, blocked, pending };
+}
+function renderInitiativeSummary(group) {
+  const { active, pending } = partitionTasks(group.tasks);
+  const nextEligible = [...pending].sort(bySeverity)[0];
+  const cat = nextEligible?.category ? ` -> ${nextEligible.category}` : "";
+  const nextLabel = nextEligible ? ` (next: ${nextEligible.content.slice(0, 30)}${nextEligible.content.length > 30 ? "..." : ""} [${nextEligible.severity ?? "medium"}])` : "";
+  return `[${group.initiative}] ${active.length} active, ${pending.length} pending${nextLabel}${cat}`;
+}
+function renderCompactInitiative(group, lines, rendered) {
+  lines.push(`  ${renderInitiativeSummary(group)}`);
+  const { active, blocked, pending } = partitionTasks(group.tasks);
+  const nextEligible = [...pending].sort(bySeverity)[0];
+  for (const task of [...active, ...blocked]) {
+    if (rendered >= MAX_TASKS) break;
+    lines.push(`    ${formatTaskLine(task)}`);
+    rendered++;
+  }
+  if (nextEligible && active.length === 0 && blocked.length === 0 && rendered < MAX_TASKS) {
+    lines.push(`    ${formatTaskLine(nextEligible)}`);
+    rendered++;
+  }
+  return rendered;
+}
+function renderFlatGroup(group, showHeader, lines, rendered) {
+  if (showHeader && group.initiative) {
+    lines.push(`  [${group.initiative}]`);
+  }
+  for (const task of group.tasks) {
+    if (rendered >= MAX_TASKS) break;
+    lines.push(`  ${formatTaskLine(task)}`);
+    rendered++;
+  }
+  return rendered;
+}
 function renderTaskGroups(groups) {
   const lines = [];
   let rendered = 0;
   for (const group of groups) {
     if (rendered >= MAX_TASKS) break;
-    if (group.initiative && groups.length > 1) {
-      lines.push(`  [${group.initiative}]`);
-    }
-    for (const task of group.tasks) {
-      if (rendered >= MAX_TASKS) break;
-      lines.push(`  ${formatTaskLine(task)}`);
-      rendered++;
+    const useCompactMode = group.initiative && group.tasks.length >= 3;
+    if (useCompactMode) {
+      rendered = renderCompactInitiative(group, lines, rendered);
+    } else {
+      const showHeader = group.initiative !== null && groups.length > 1;
+      rendered = renderFlatGroup(group, showHeader, lines, rendered);
     }
   }
   return lines;
@@ -4017,112 +4493,100 @@ ${JSON.stringify(event.data.payload ?? {}, null, 2)}
       return `Internal event: ${event.eventKind}`;
   }
 }
+function countEvents(grouped) {
+  return grouped.messages.length + grouped.webhooks.length + grouped.runCompletions.length;
+}
 function isIdleHeartbeat(opts) {
-  const { messages, webhooks, runCompletions } = opts.grouped;
-  const totalEvents = messages.length + webhooks.length + runCompletions.length;
   const hasWork = buildWorkQueueSection(opts.memories) !== "";
-  return totalEvents === 0 && opts.activeRuns.length === 0 && !hasWork;
+  return countEvents(opts.grouped) === 0 && opts.activeRuns.length === 0 && !hasWork;
 }
 function buildIdlePrompt(opts) {
-  return `<role>
-${ROLE}
-Heartbeat #${opts.heartbeatCount}
-</role>
+  const budgetLine = `Budget: $${opts.budgetStatus.todayUsd.toFixed(2)} / $${opts.budgetStatus.capUsd.toFixed(2)} (${opts.budgetStatus.remainingPct.toFixed(0)}% remaining)`;
+  const hasRepos = opts.repos.length > 0;
+  const hasBudget = opts.budgetStatus.remainingPct > 10;
+  const hasPendingDecisions = (opts.pendingDecisions?.length ?? 0) > 0;
+  if (!hasRepos || !hasBudget) {
+    return `${buildRoleSection(opts.heartbeatCount)}
 
 <context>
 No events. No active runs. No pending tasks.
-Budget: $${opts.budgetStatus.todayUsd.toFixed(2)} / $${opts.budgetStatus.capUsd.toFixed(2)} (${opts.budgetStatus.remainingPct.toFixed(0)}% remaining)
+${budgetLine}
 </context>
 
 <directive>
 Nothing to do. Run \`neo log discovery "idle"\` and yield. Do not produce any other output.
 </directive>`;
-}
-function buildStandardPrompt(opts) {
-  const sections = [];
-  sections.push(`<role>
-${ROLE}
-Heartbeat #${opts.heartbeatCount}
-</role>`);
-  const contextParts = [];
-  const workQueue = buildWorkQueueSection(opts.memories);
-  if (workQueue) {
-    contextParts.push(workQueue);
   }
-  if (opts.activeRuns.length > 0) {
-    contextParts.push(`Active runs:
-${opts.activeRuns.map((r) => `- ${r}`).join("\n")}`);
-  }
-  contextParts.push(...buildContextSections(opts));
-  contextParts.push(buildMemorySection(opts.memories, opts.supervisorDir));
-  const recentActions = buildRecentActionsSection(opts.recentActions);
-  if (recentActions) {
-    contextParts.push(recentActions);
+  const repoList = opts.repos.map((r) => `- ${r.path} (branch: ${r.defaultBranch})`).join("\n");
+  if (hasPendingDecisions) {
+    const pendingSection = buildPendingDecisionsSection(opts.pendingDecisions);
+    return `${buildRoleSection(opts.heartbeatCount)}
+
+<context>
+No events. No active runs. No pending tasks.
+${budgetLine}
+
+${pendingSection}
+
+Repositories:
+${repoList}
+</context>
+
+<directive>
+Idle \u2014 but there are pending decisions awaiting user response.
+Run \`neo log discovery "idle \u2014 waiting on ${String(opts.pendingDecisions?.length ?? 0)} pending decision(s)"\` and yield.
+</directive>`;
   }
-  contextParts.push(`Events:
-${buildEventsSection(opts.grouped)}`);
-  sections.push(`<context>
-${contextParts.join("\n\n")}
-</context>`);
-  sections.push(`<reference>
+  return `${buildRoleSection(opts.heartbeatCount)}
+
+<context>
+No events. No active runs. No pending tasks.
+${budgetLine}
+
+Repositories:
+${repoList}
+</context>
+
+<reference>
 ${getCommandsSection(opts.heartbeatCount)}
-</reference>`);
-  const instructionParts = [];
-  instructionParts.push(HEARTBEAT_RULES);
-  instructionParts.push(REPORTING_RULES);
-  instructionParts.push(MEMORY_RULES_CORE);
-  if (opts.customInstructions) {
-    instructionParts.push(`### Custom instructions
-${opts.customInstructions}`);
-  }
-  const { messages, webhooks, runCompletions } = opts.grouped;
-  const hasEvents = messages.length + webhooks.length + runCompletions.length > 0;
+</reference>
+
+<directive>
+Idle \u2014 no work in progress. Use this downtime to dispatch a \`scout\` agent on one of your repositories.
+
+The scout explores the codebase and surfaces bugs, improvements, security issues, and tech debt. It creates decisions (via \`neo decision create\`) for each critical or high-impact finding, so the user can choose what to act on.
+
+**Rules:**
+- Pick the repo that was least recently scouted (check your memory for previous scout runs).
+- Only ONE scout at a time \u2014 never dispatch multiple scouts in parallel.
+- Use \`--branch main\` (or the repo's default branch) \u2014 scouts are read-only.
+- Log your decision before dispatching.
+
+**Example:**
+\`\`\`bash
+neo log decision "Idle \u2014 dispatching scout on <repo>"
+neo run scout --prompt "Explore this repository. Surface bugs, improvements, security issues, and tech debt. Create decisions for critical and high-impact findings." \\
+  --repo <path> \\
+  --branch <default-branch> \\
+  --meta '{"stage":"scout","label":"scout-<repo-name>"}'
+\`\`\`
+</directive>`;
+}
+function buildStandardPrompt(opts) {
+  const instructionParts = buildBaseInstructions(opts, { includeExamples: false });
+  const hasEvents = countEvents(opts.grouped) > 0;
   instructionParts.push(
     hasEvents ? "Process events, dispatch eligible work, yield. Each heartbeat costs ~$0.10 \u2014 be efficient." : "No events. If pending work exists, dispatch it. Otherwise yield immediately."
   );
-  sections.push(`<instructions>
-${instructionParts.join("\n\n")}
-</instructions>`);
-  return sections.join("\n\n");
+  return [
+    buildRoleSection(opts.heartbeatCount),
+    buildFullContext(opts),
+    buildReferenceSection(opts.heartbeatCount),
+    wrapInstructions(instructionParts)
+  ].join("\n\n");
 }
 function buildConsolidationPrompt(opts) {
-  const sections = [];
-  sections.push(`<role>
-${ROLE}
-Heartbeat #${opts.heartbeatCount} (CONSOLIDATION)
-</role>`);
-  const contextParts = [];
-  const workQueueConsolidation = buildWorkQueueSection(opts.memories);
-  if (workQueueConsolidation) {
-    contextParts.push(workQueueConsolidation);
-  }
-  if (opts.activeRuns.length > 0) {
-    contextParts.push(`Active runs:
-${opts.activeRuns.map((r) => `- ${r}`).join("\n")}`);
-  }
-  contextParts.push(...buildContextSections(opts));
-  contextParts.push(buildMemorySection(opts.memories, opts.supervisorDir));
-  const recentActions = buildRecentActionsSection(opts.recentActions);
-  if (recentActions) {
-    contextParts.push(recentActions);
-  }
-  contextParts.push(`Events:
-${buildEventsSection(opts.grouped)}`);
-  sections.push(`<context>
-${contextParts.join("\n\n")}
-</context>`);
-  sections.push(`<reference>
-${getCommandsSection(opts.heartbeatCount)}
-</reference>`);
-  const instructionParts = [];
-  instructionParts.push(HEARTBEAT_RULES);
-  instructionParts.push(REPORTING_RULES);
-  instructionParts.push(MEMORY_RULES_CORE);
-  instructionParts.push(MEMORY_RULES_EXAMPLES);
-  if (opts.customInstructions) {
-    instructionParts.push(`### Custom instructions
-${opts.customInstructions}`);
-  }
+  const instructionParts = buildBaseInstructions(opts, { includeExamples: true });
   instructionParts.push(
     `### Consolidation
 This is a CONSOLIDATION heartbeat.
@@ -4137,39 +4601,16 @@ If there IS active work, your job:
 4. **Prune completed work** \u2014 if a PR is merged or an initiative is done, forget related facts that are no longer actionable. Keep only reusable architectural truths.
 5. **Prune done tasks** \u2014 forget tasks with outcome \`done\` or \`abandoned\` older than 7 days.`
   );
-  sections.push(`<instructions>
-${instructionParts.join("\n\n")}
-</instructions>`);
-  return sections.join("\n\n");
+  return [
+    buildRoleSection(opts.heartbeatCount, "CONSOLIDATION"),
+    buildFullContext(opts),
+    buildReferenceSection(opts.heartbeatCount),
+    wrapInstructions(instructionParts)
+  ].join("\n\n");
 }
 function buildCompactionPrompt(opts) {
-  const sections = [];
-  sections.push(`<role>
-${ROLE}
-Heartbeat #${opts.heartbeatCount} (COMPACTION)
-</role>`);
-  const contextParts = [];
-  contextParts.push(...buildContextSections(opts));
-  contextParts.push(buildMemorySection(opts.memories, opts.supervisorDir));
-  const workQueueCompaction = buildWorkQueueSection(opts.memories);
-  if (workQueueCompaction) {
-    contextParts.push(workQueueCompaction);
-  }
-  sections.push(`<context>
-${contextParts.join("\n\n")}
-</context>`);
-  sections.push(`<reference>
-${getCommandsSection(opts.heartbeatCount)}
-</reference>`);
-  const instructionParts = [];
-  instructionParts.push(HEARTBEAT_RULES);
-  instructionParts.push(REPORTING_RULES);
-  instructionParts.push(MEMORY_RULES_CORE);
-  instructionParts.push(MEMORY_RULES_EXAMPLES);
-  if (opts.customInstructions) {
-    instructionParts.push(`### Custom instructions
-${opts.customInstructions}`);
-  }
+  const notesDir = `${opts.supervisorDir}/notes`;
+  const instructionParts = buildBaseInstructions(opts, { includeExamples: true });
   instructionParts.push(`### Compaction
 This is a COMPACTION heartbeat. Deep-clean your ENTIRE memory.
 
@@ -4179,7 +4620,7 @@ This is a COMPACTION heartbeat. Deep-clean your ENTIRE memory.
 4. **Merge duplicates** \u2014 combine similar facts within the same scope into one.
 5. **Clean up focus** \u2014 forget resolved items, rewrite remaining in structured format.
 6. **Prune done tasks** \u2014 forget tasks with outcome \`done\` or \`abandoned\` older than 7 days.
-7. **Delete completed notes** from notes/ directory.
+7. **Delete completed notes** from \`${notesDir}/\` directory.
 8. **Stay under 15 facts per scope** \u2014 prioritize facts that affect dispatch decisions.
 
 Flag contradictions: if two facts contradict, keep the newer one.
@@ -4188,12 +4629,66 @@ Flag contradictions: if two facts contradict, keep the newer one.
 neo memory list --type fact
 neo memory forget <stale-id>
 \`\`\``);
-  sections.push(`<instructions>
-${instructionParts.join("\n\n")}
-</instructions>`);
-  return sections.join("\n\n");
+  return [
+    buildRoleSection(opts.heartbeatCount, "COMPACTION"),
+    buildCompactionContext(opts),
+    buildReferenceSection(opts.heartbeatCount),
+    wrapInstructions(instructionParts)
+  ].join("\n\n");
 }
 
+// src/supervisor/webhookEvents.ts
+import { z as z6 } from "zod";
+var supervisorStartedEventSchema = z6.object({
+  type: z6.literal("supervisor_started"),
+  supervisorId: z6.string(),
+  startedAt: z6.string().datetime()
+});
+var heartbeatEventSchema = z6.object({
+  type: z6.literal("heartbeat"),
+  supervisorId: z6.string(),
+  heartbeatNumber: z6.number().int().min(0),
+  timestamp: z6.string().datetime(),
+  runsActive: z6.number().int().min(0),
+  budget: z6.object({
+    todayUsd: z6.number().min(0),
+    limitUsd: z6.number().min(0)
+  })
+});
+var runDispatchedEventSchema = z6.object({
+  type: z6.literal("run_dispatched"),
+  supervisorId: z6.string(),
+  runId: z6.string(),
+  agent: z6.string(),
+  repo: z6.string(),
+  branch: z6.string(),
+  prompt: z6.string().max(500)
+  // truncated
+});
+var runCompletedEventSchema = z6.object({
+  type: z6.literal("run_completed"),
+  supervisorId: z6.string(),
+  runId: z6.string(),
+  status: z6.enum(["completed", "failed", "cancelled"]),
+  output: z6.string().max(1e3).optional(),
+  // truncated
+  costUsd: z6.number().min(0),
+  durationMs: z6.number().int().min(0)
+});
+var supervisorStoppedEventSchema = z6.object({
+  type: z6.literal("supervisor_stopped"),
+  supervisorId: z6.string(),
+  stoppedAt: z6.string().datetime(),
+  reason: z6.enum(["shutdown", "budget_exceeded", "error", "manual"])
+});
+var supervisorWebhookEventSchema = z6.discriminatedUnion("type", [
+  supervisorStartedEventSchema,
+  heartbeatEventSchema,
+  runDispatchedEventSchema,
+  runCompletedEventSchema,
+  supervisorStoppedEventSchema
+]);
+
 // src/supervisor/heartbeat.ts
 var DEFAULT_IDLE_SKIP_MAX = 20;
 var DEFAULT_ACTIVE_WORK_SKIP_MAX = 3;
@@ -4208,6 +4703,23 @@ function shouldCompact(heartbeatCount, lastCompactionHeartbeat, compactionInterv
   const since = heartbeatCount - lastCompactionHeartbeat;
   return since >= compactionInterval;
 }
+var STALE_GRACE_PERIOD_MS = 3e4;
+function isRunActive(run, isAlive = isProcessAlive, now = Date.now()) {
+  if (run.status !== "running" && run.status !== "paused") {
+    return false;
+  }
+  if (run.status === "paused") {
+    return true;
+  }
+  if (run.pid && isAlive(run.pid)) {
+    return true;
+  }
+  if (run.pid) {
+    return false;
+  }
+  const ageMs = now - new Date(run.createdAt).getTime();
+  return ageMs < STALE_GRACE_PERIOD_MS;
+}
 var HeartbeatLoop = class {
   stopping = false;
   consecutiveFailures = 0;
@@ -4218,10 +4730,18 @@ var HeartbeatLoop = class {
   sessionId;
   eventQueue;
   activityLog;
+  _eventsPath;
   customInstructions;
   defaultInstructionsPath;
   memoryStore = null;
   memoryDbPath;
+  onWebhookEvent;
+  decisionStore = null;
+  /** ConfigWatcher for hot-reload support */
+  configWatcher = null;
+  configStore = null;
+  repoPath;
+  configWatcherDebounceMs;
   constructor(options) {
     this.config = options.config;
     this.supervisorDir = options.supervisorDir;
@@ -4229,8 +4749,16 @@ var HeartbeatLoop = class {
     this.sessionId = options.sessionId;
     this.eventQueue = options.eventQueue;
     this.activityLog = options.activityLog;
+    this._eventsPath = options.eventsPath;
     this.defaultInstructionsPath = options.defaultInstructionsPath;
     this.memoryDbPath = options.memoryDbPath;
+    this.onWebhookEvent = options.onWebhookEvent;
+    this.repoPath = options.repoPath;
+    this.configWatcherDebounceMs = options.configWatcherDebounceMs;
+  }
+  /** Path to the inbox/events directory for markProcessed() calls */
+  get eventsPath() {
+    return this._eventsPath;
   }
   getMemoryStore() {
     if (!this.memoryStore && this.memoryDbPath) {
@@ -4241,9 +4769,17 @@ var HeartbeatLoop = class {
     }
     return this.memoryStore;
   }
+  getDecisionStore() {
+    if (!this.decisionStore) {
+      this.decisionStore = new DecisionStore(path14.join(this.supervisorDir, "decisions.jsonl"));
+    }
+    return this.decisionStore;
+  }
   async start() {
     this.customInstructions = await this.loadInstructions();
+    await this.initConfigWatcher();
     await this.activityLog.log("heartbeat", "Supervisor heartbeat loop started");
+    await this.emitSupervisorStarted();
     while (!this.stopping) {
       try {
         await this.runHeartbeat();
@@ -4269,23 +4805,60 @@ var HeartbeatLoop = class {
       if (this.stopping) break;
       await this.eventQueue.waitForEvent(this.config.supervisor.eventTimeoutMs);
     }
+    await this.emitSupervisorStopped("shutdown");
     await this.activityLog.log("heartbeat", "Supervisor heartbeat loop stopped");
   }
   stop() {
     this.stopping = true;
     this.activeAbort?.abort(new Error("Supervisor shutting down"));
     this.eventQueue.interrupt();
+    if (this.configWatcher) {
+      this.configWatcher.stop();
+      this.configWatcher = null;
+    }
+  }
+  /**
+   * Initialize and start the ConfigWatcher for hot-reload support.
+   * Subscribes to config file changes and logs reload events.
+   */
+  async initConfigWatcher() {
+    this.configStore = new ConfigStore(this.repoPath);
+    await this.configStore.load();
+    const watcherOptions = this.configWatcherDebounceMs !== void 0 ? { debounceMs: this.configWatcherDebounceMs } : void 0;
+    this.configWatcher = new ConfigWatcher(this.configStore, watcherOptions);
+    this.configWatcher.on("change", () => {
+      this.handleConfigChange();
+    });
+    this.configWatcher.start();
+    await this.activityLog.log("event", "ConfigWatcher started for hot-reload");
+  }
+  /**
+   * Handle config file changes. Propagates reloaded config to the running
+   * loop and triggers an immediate heartbeat.
+   */
+  handleConfigChange() {
+    if (this.configStore) {
+      this.config = this.configStore.getAll();
+    }
+    this.activityLog.log("event", "Configuration reloaded (hot-reload)").catch(() => {
+    });
+    this.eventQueue.interrupt();
   }
   async runHeartbeat() {
     const startTime = Date.now();
-    const heartbeatId = randomUUID5();
+    const heartbeatId = randomUUID6();
     const state = await this.readState();
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
     const budgetCheck = await this.checkBudgetExceeded(state, today);
     if (budgetCheck.exceeded) return;
-    const grouped = this.eventQueue.drainAndGroup();
+    const { grouped, rawEvents } = this.eventQueue.drainAndGroup();
     const totalEventCount = grouped.messages.length + grouped.webhooks.length + grouped.runCompletions.length;
     const activeRuns = await this.getActiveRuns();
+    const decisionStore = this.getDecisionStore();
+    await this.processDecisionAnswers(rawEvents, decisionStore);
+    await decisionStore.expire();
+    const _pendingDecisions = await decisionStore.pending();
+    void _pendingDecisions;
     const skipResult = await this.handleSkipLogic({
       state,
       totalEventCount,
@@ -4320,6 +4893,17 @@ var HeartbeatLoop = class {
       }
     );
     const { costUsd, turnCount } = await this.callSdk(prompt, heartbeatId);
+    if (turnCount === 0) {
+      await this.activityLog.log(
+        "warning",
+        `Heartbeat #${modeResult.heartbeatCount} completed with turnCount=0. SDK stream may have timed out before any turns completed.`,
+        { heartbeatId }
+      );
+    }
+    if (rawEvents.length > 0) {
+      const inboxPath = path14.join(this.supervisorDir, "inbox.jsonl");
+      await this.eventQueue.markProcessed(inboxPath, this.eventsPath, rawEvents);
+    }
     if (modeResult.isConsolidation) {
       const allIds = modeResult.unconsolidated.map((e) => e.id);
       if (allIds.length > 0) {
@@ -4349,6 +4933,27 @@ var HeartbeatLoop = class {
         isConsolidation: modeResult.isConsolidation
       }
     );
+    await this.emitHeartbeatCompleted({
+      heartbeatNumber: modeResult.heartbeatCount + 1,
+      runsActive: activeRuns.length,
+      todayUsd: budgetCheck.todayCost + costUsd,
+      limitUsd: this.config.supervisor.dailyCapUsd
+    });
+    for (const event of rawEvents) {
+      if (event.kind === "run_complete") {
+        const runData = await this.readPersistedRun(event.runId);
+        const emitOpts = {
+          runId: event.runId,
+          status: runData?.status === "failed" ? "failed" : "completed",
+          costUsd: runData?.totalCostUsd ?? 0,
+          durationMs: runData?.durationMs ?? 0
+        };
+        if (runData?.output) {
+          emitOpts.output = runData.output;
+        }
+        await this.emitRunCompleted(emitOpts);
+      }
+    }
   }
   /**
    * Check if supervisor daily budget is exceeded.
@@ -4424,7 +5029,6 @@ var HeartbeatLoop = class {
       isCompaction,
       unconsolidated,
       heartbeatCount,
-      lastConsolidation,
       lastConsolidationTs
     };
   }
@@ -4504,6 +5108,12 @@ var HeartbeatLoop = class {
   }
   /**
    * Call the Claude SDK and stream results.
+   *
+   * Uses Promise.race to enable non-blocking abort detection. The standard
+   * `for await (const message of stream)` pattern only checks the abort signal
+   * AFTER each yield — if the SDK hangs (no messages), the abort never executes.
+   * This implementation races each iterator.next() against an abort promise,
+   * allowing immediate response to shutdown/timeout signals.
    */
   async callSdk(prompt, heartbeatId) {
     const abortController = new AbortController();
@@ -4523,25 +5133,48 @@ var HeartbeatLoop = class {
         }
       }
       const queryOptions = {
-        cwd: homedir2(),
+        cwd: homedir4(),
         allowedTools,
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
-        mcpServers: this.config.mcpServers ?? {}
+        mcpServers: this.config.mcpServers ?? {},
+        // Don't persist session history — each heartbeat is a fresh conversation.
+        // Without this, supervisor restarts could replay old messages.
+        persistSession: false
       };
       const stream = sdk.query({ prompt, options: queryOptions });
-      for await (const message of stream) {
-        if (abortController.signal.aborted) break;
-        const msg = message;
-        if (isInitMessage(msg)) {
-          this.sessionId = msg.session_id;
+      const abortPromise = new Promise((resolve4) => {
+        if (abortController.signal.aborted) {
+          resolve4({ aborted: true });
+          return;
         }
-        if (isResultMessage(msg)) {
-          output = msg.result ?? "";
-          costUsd = msg.total_cost_usd ?? 0;
-          turnCount = msg.num_turns ?? 0;
+        abortController.signal.addEventListener("abort", () => resolve4({ aborted: true }), {
+          once: true
+        });
+      });
+      const iterator = stream[Symbol.asyncIterator]();
+      try {
+        while (true) {
+          const raceResult = await Promise.race([iterator.next(), abortPromise]);
+          if ("aborted" in raceResult) {
+            await this.activityLog.log("heartbeat", "Heartbeat aborted", { heartbeatId });
+            break;
+          }
+          const iterResult = raceResult;
+          if (iterResult.done) break;
+          const msg = iterResult.value;
+          if (isInitMessage(msg)) {
+            this.sessionId = msg.session_id;
+          }
+          if (isResultMessage(msg)) {
+            output = msg.result ?? "";
+            costUsd = msg.total_cost_usd ?? 0;
+            turnCount = msg.num_turns ?? 0;
+          }
+          await this.logStreamMessage(msg, heartbeatId);
         }
-        await this.logStreamMessage(msg, heartbeatId);
+      } finally {
+        await iterator.return?.();
       }
     } finally {
       clearTimeout(timeout);
@@ -4562,29 +5195,33 @@ var HeartbeatLoop = class {
       const raw = await readFile11(this.statePath, "utf-8");
       const state = JSON.parse(raw);
       Object.assign(state, updates);
-      await writeFile5(this.statePath, JSON.stringify(state, null, 2), "utf-8");
+      await writeFile6(this.statePath, JSON.stringify(state, null, 2), "utf-8");
     } catch {
     }
   }
-  /** Read persisted run files and return summaries of active (running/paused) runs. */
+  /**
+   * Read persisted run files and return summaries of active (running/paused) runs.
+   * Validates that "running" runs are actually alive by checking their PID.
+   * Stale runs (dead PID past grace period) are filtered out to prevent ghost runs.
+   */
   async getActiveRuns() {
     const runsDir = getRunsDir();
     if (!existsSync7(runsDir)) return [];
     try {
-      const entries = await readdir5(runsDir, { withFileTypes: true });
+      const entries = await readdir4(runsDir, { withFileTypes: true });
       const active = [];
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         const subDir = path14.join(runsDir, entry.name);
-        const files = await readdir5(subDir);
+        const files = await readdir4(subDir);
         for (const f of files) {
           if (!f.endsWith(".json")) continue;
           try {
             const raw = await readFile11(path14.join(subDir, f), "utf-8");
             const run = JSON.parse(raw);
-            if (run.status === "running" || run.status === "paused") {
+            if (isRunActive(run)) {
               active.push(
-                `${run.runId} [${run.status}] ${run.workflow} on ${path14.basename(run.repo)}`
+                `${run.runId} [${run.status}] ${run.agent} on ${path14.basename(run.repo)}`
               );
             }
           } catch {
@@ -4663,21 +5300,191 @@ var HeartbeatLoop = class {
     if (!isToolResultMessage(msg)) return;
     const result = msg.result ?? "";
     const runMatch = /Run\s+(\S+)\s+dispatched/i.exec(result);
-    if (runMatch) {
-      await this.activityLog.log("dispatch", `Agent dispatched: ${runMatch[1]}`, {
+    const runId = runMatch?.[1];
+    if (runId) {
+      await this.activityLog.log("dispatch", `Agent dispatched: ${runId}`, {
         heartbeatId,
-        runId: runMatch[1]
+        runId
+      });
+      const agentMatch = /agent[:\s]+(\S+)/i.exec(result);
+      const repoMatch = /repo[:\s]+(\S+)/i.exec(result);
+      const branchMatch = /branch[:\s]+(\S+)/i.exec(result);
+      const agent = agentMatch?.[1] ?? "unknown";
+      const repo = repoMatch?.[1] ?? "unknown";
+      const branch = branchMatch?.[1] ?? "unknown";
+      await this.emitRunDispatched({
+        runId,
+        agent,
+        repo,
+        branch,
+        prompt: result.slice(0, 500)
       });
     }
   }
   sleep(ms) {
     return new Promise((resolve4) => setTimeout(resolve4, ms));
   }
+  /**
+   * Process decision:answer events from inbox messages.
+   * Expected format: "decision:answer <decisionId> <answer>"
+   */
+  async processDecisionAnswers(rawEvents, store) {
+    for (const event of rawEvents) {
+      if (event.kind !== "message") continue;
+      const text = event.data.text.trim();
+      const match = /^decision:answer\s+(\S+)\s+(.+)$/i.exec(text);
+      if (!match) continue;
+      const decisionId = match[1];
+      const answer = match[2];
+      if (!decisionId || !answer) continue;
+      try {
+        await store.answer(decisionId, answer);
+        await this.activityLog.log("event", `Decision answered: ${decisionId}`, {
+          decisionId,
+          answer
+        });
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        await this.activityLog.log("error", `Failed to answer decision ${decisionId}: ${msg}`, {
+          decisionId,
+          answer
+        });
+      }
+    }
+  }
+  /**
+   * Read persisted run data to extract actual status, cost, and duration.
+   * Returns null if the run file cannot be found or parsed.
+   */
+  async readPersistedRun(runId) {
+    const runsDir = getRunsDir();
+    if (!existsSync7(runsDir)) return null;
+    try {
+      const entries = await readdir4(runsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const subDir = path14.join(runsDir, entry.name);
+        const runPath = path14.join(subDir, `${runId}.json`);
+        if (existsSync7(runPath)) {
+          const raw = await readFile11(runPath, "utf-8");
+          const run = JSON.parse(raw);
+          const totalCostUsd = Object.values(run.steps).reduce(
+            (sum, step) => sum + (step.costUsd ?? 0),
+            0
+          );
+          const durationMs = new Date(run.updatedAt).getTime() - new Date(run.createdAt).getTime();
+          const completedSteps = Object.values(run.steps).filter(
+            (s) => s.status === "success" || s.status === "failure"
+          );
+          const lastStep = completedSteps[completedSteps.length - 1];
+          const output = typeof lastStep?.rawOutput === "string" ? lastStep.rawOutput.slice(0, 1e3) : void 0;
+          return { status: run.status, totalCostUsd, durationMs, output };
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+  // ─── Webhook event emission ───────────────────────────────
+  /**
+   * Emit a webhook event if a callback is configured.
+   * Validates the event against its schema before emission.
+   */
+  async emitWebhookEvent(event) {
+    if (!this.onWebhookEvent) return;
+    try {
+      switch (event.type) {
+        case "supervisor_started":
+          supervisorStartedEventSchema.parse(event);
+          break;
+        case "heartbeat":
+          heartbeatEventSchema.parse(event);
+          break;
+        case "run_dispatched":
+          runDispatchedEventSchema.parse(event);
+          break;
+        case "run_completed":
+          runCompletedEventSchema.parse(event);
+          break;
+        case "supervisor_stopped":
+          supervisorStoppedEventSchema.parse(event);
+          break;
+      }
+      await this.onWebhookEvent(event);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      await this.activityLog.log("error", `Webhook event emission failed: ${msg}`, {
+        eventType: event.type
+      });
+    }
+  }
+  /** Emit SupervisorStartedEvent */
+  async emitSupervisorStarted() {
+    const event = {
+      type: "supervisor_started",
+      supervisorId: this.sessionId,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.emitWebhookEvent(event);
+  }
+  /** Emit SupervisorStoppedEvent */
+  async emitSupervisorStopped(reason) {
+    const event = {
+      type: "supervisor_stopped",
+      supervisorId: this.sessionId,
+      stoppedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      reason
+    };
+    await this.emitWebhookEvent(event);
+  }
+  /** Emit HeartbeatEvent */
+  async emitHeartbeatCompleted(opts) {
+    const event = {
+      type: "heartbeat",
+      supervisorId: this.sessionId,
+      heartbeatNumber: opts.heartbeatNumber,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      runsActive: opts.runsActive,
+      budget: {
+        todayUsd: opts.todayUsd,
+        limitUsd: opts.limitUsd
+      }
+    };
+    await this.emitWebhookEvent(event);
+  }
+  /** Emit RunDispatchedEvent from tool result detection */
+  async emitRunDispatched(opts) {
+    const event = {
+      type: "run_dispatched",
+      supervisorId: this.sessionId,
+      runId: opts.runId,
+      agent: opts.agent,
+      repo: opts.repo,
+      branch: opts.branch,
+      prompt: opts.prompt.slice(0, 500)
+      // Truncate to schema max
+    };
+    await this.emitWebhookEvent(event);
+  }
+  /** Emit RunCompletedEvent when processing run_complete events */
+  async emitRunCompleted(opts) {
+    const event = {
+      type: "run_completed",
+      supervisorId: this.sessionId,
+      runId: opts.runId,
+      status: opts.status,
+      output: opts.output?.slice(0, 1e3),
+      // Truncate to schema max
+      costUsd: opts.costUsd,
+      durationMs: opts.durationMs
+    };
+    await this.emitWebhookEvent(event);
+  }
 };
 
 // src/supervisor/webhook-server.ts
 import { createHmac as createHmac2, timingSafeEqual } from "crypto";
-import { appendFile as appendFile6 } from "fs/promises";
+import { appendFile as appendFile7 } from "fs/promises";
 import { createServer } from "http";
 var MAX_BODY_SIZE = 1024 * 1024;
 var WebhookServer = class {
@@ -4762,7 +5569,7 @@ var WebhookServer = class {
       payload: parsed.payload ?? parsed,
       receivedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    await appendFile6(this.eventsPath, `${JSON.stringify(event)}
+    await appendFile7(this.eventsPath, `${JSON.stringify(event)}
 `, "utf-8");
     this.onEvent(event);
     this.sendJson(res, 200, { ok: true, id: event.id });
@@ -4802,6 +5609,7 @@ var SupervisorDaemon = class {
   eventQueue = null;
   heartbeatLoop = null;
   activityLog = null;
+  decisionStore = null;
   sessionId = "";
   constructor(options) {
     this.name = options.name;
@@ -4822,16 +5630,17 @@ var SupervisorDaemon = class {
       await rm2(lockPath, { force: true });
     }
     const tempLock = `${lockPath}.${process.pid}`;
-    await writeFile6(tempLock, String(process.pid), "utf-8");
+    await writeFile7(tempLock, String(process.pid), "utf-8");
     const { rename: rename2 } = await import("fs/promises");
     await rename2(tempLock, lockPath);
     const existingState = await this.readState();
     if (existingState?.sessionId && existingState.status !== "stopped") {
       this.sessionId = existingState.sessionId;
     } else {
-      this.sessionId = randomUUID6();
+      this.sessionId = randomUUID7();
     }
     this.activityLog = new ActivityLog(this.dir);
+    this.decisionStore = new DecisionStore(getSupervisorDecisionsPath(this.name));
     this.eventQueue = new EventQueue({
       maxEventsPerSec: this.config.supervisor.maxEventsPerSec
     });
@@ -4845,6 +5654,12 @@ var SupervisorDaemon = class {
       eventsPath,
       onEvent: (event) => {
         this.eventQueue?.push({ kind: "webhook", data: event });
+        this.handleDecisionAnswer(event).catch((err) => {
+          this.activityLog?.log(
+            "error",
+            `Failed to handle decision:answer: ${err instanceof Error ? err.message : String(err)}`
+          );
+        });
         if ((event.event === "session:complete" || event.event === "session:fail") && event.payload) {
           const runId = typeof event.payload.runId === "string" ? event.payload.runId : void 0;
           if (runId) {
@@ -4863,7 +5678,7 @@ var SupervisorDaemon = class {
       pid: process.pid,
       sessionId: this.sessionId,
       port: this.config.supervisor.port,
-      cwd: homedir3(),
+      cwd: homedir5(),
       startedAt: (/* @__PURE__ */ new Date()).toISOString(),
       lastHeartbeat: existingState?.lastHeartbeat,
       heartbeatCount: existingState?.heartbeatCount ?? 0,
@@ -4894,6 +5709,7 @@ var SupervisorDaemon = class {
       sessionId: this.sessionId,
       eventQueue: this.eventQueue,
       activityLog: this.activityLog,
+      eventsPath,
       defaultInstructionsPath: this.defaultInstructionsPath
     });
     await this.heartbeatLoop.start();
@@ -4936,7 +5752,7 @@ var SupervisorDaemon = class {
   }
   async writeState(state) {
     const statePath = path15.join(this.dir, "state.json");
-    await writeFile6(statePath, JSON.stringify(state, null, 2), "utf-8");
+    await writeFile7(statePath, JSON.stringify(state, null, 2), "utf-8");
   }
   async readLockPid(lockPath) {
     try {
@@ -4947,14 +5763,248 @@ var SupervisorDaemon = class {
       return null;
     }
   }
+  /**
+   * Handle decision:answer webhook events.
+   * Extracts decisionId and answer from the payload and records the answer.
+   */
+  async handleDecisionAnswer(event) {
+    if (event.event !== "decision:answer") return;
+    if (!this.decisionStore || !event.payload) return;
+    const decisionId = typeof event.payload.decisionId === "string" ? event.payload.decisionId : void 0;
+    const answer = typeof event.payload.answer === "string" ? event.payload.answer : void 0;
+    if (!decisionId || !answer) {
+      await this.activityLog?.log(
+        "error",
+        `decision:answer webhook missing required fields (decisionId: ${decisionId}, answer: ${answer})`
+      );
+      return;
+    }
+    try {
+      await this.decisionStore.answer(decisionId, answer);
+      await this.activityLog?.log(
+        "decision",
+        `Decision ${decisionId} answered via webhook: "${answer}"`
+      );
+    } catch (err) {
+      await this.activityLog?.log(
+        "error",
+        `Failed to answer decision ${decisionId}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+};
+
+// src/supervisor/StatusReader.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { readFile as readFile13 } from "fs/promises";
+import path16 from "path";
+var STATE_FILE = "state.json";
+var ACTIVITY_FILE2 = "activity.jsonl";
+var StatusReader = class {
+  dataDir;
+  statePath;
+  activityPath;
+  constructor(dataDir) {
+    this.dataDir = dataDir;
+    this.statePath = path16.join(dataDir, STATE_FILE);
+    this.activityPath = path16.join(dataDir, ACTIVITY_FILE2);
+  }
+  /**
+   * Read and parse supervisor status from disk.
+   * Returns null if the state file doesn't exist (supervisor not running).
+   */
+  async getStatus() {
+    let raw;
+    try {
+      raw = await readFile13(this.statePath, "utf-8");
+    } catch {
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+    const result = supervisorDaemonStateSchema.safeParse(parsed);
+    if (!result.success) {
+      return null;
+    }
+    const daemon = result.data;
+    const statusMap = {
+      running: "running",
+      draining: "stopping",
+      stopped: "idle"
+    };
+    const recentActivity = this.queryActivity({ limit: 5 });
+    return {
+      pid: daemon.pid,
+      sessionId: daemon.sessionId,
+      startedAt: daemon.startedAt,
+      heartbeatCount: daemon.heartbeatCount,
+      totalCostUsd: daemon.totalCostUsd,
+      todayCostUsd: daemon.todayCostUsd,
+      status: statusMap[daemon.status],
+      lastHeartbeat: daemon.lastHeartbeat ?? daemon.startedAt,
+      activeRunCount: 0,
+      // TODO: count active runs from .neo/runs/
+      recentActivitySummary: recentActivity.map((e) => `[${e.type}] ${e.summary}`)
+    };
+  }
+  /**
+   * Query activity entries with optional filtering.
+   * Returns empty array if the activity file doesn't exist or is empty.
+   */
+  queryActivity(options = {}) {
+    const { limit = 50, offset = 0, type, since, until } = options;
+    let content;
+    try {
+      content = readFileSync2(this.activityPath, "utf-8");
+    } catch {
+      return [];
+    }
+    const lines = content.trim().split("\n").filter(Boolean);
+    let entries = [];
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line);
+        const result = activityEntrySchema.safeParse(parsed);
+        if (result.success) {
+          entries.push(result.data);
+        }
+      } catch {
+      }
+    }
+    if (type) {
+      entries = entries.filter((e) => e.type === type);
+    }
+    if (since) {
+      const sinceDate = new Date(since);
+      entries = entries.filter((e) => new Date(e.timestamp) >= sinceDate);
+    }
+    if (until) {
+      const untilDate = new Date(until);
+      entries = entries.filter((e) => new Date(e.timestamp) <= untilDate);
+    }
+    return entries.slice(offset, offset + limit);
+  }
 };
 
+// src/supervisor/shutdown.ts
+import { existsSync as existsSync9 } from "fs";
+import { readdir as readdir5, readFile as readFile14, writeFile as writeFile8 } from "fs/promises";
+import path17 from "path";
+
+// src/webhook-config.ts
+import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir8, readFile as readFile15, writeFile as writeFile9 } from "fs/promises";
+import path18 from "path";
+import { z as z7 } from "zod";
+var webhookEntrySchema = z7.object({
+  url: z7.string().url(),
+  events: z7.array(z7.string()).optional(),
+  secret: z7.string().optional(),
+  timeoutMs: z7.number().default(5e3),
+  createdAt: z7.string().default(() => (/* @__PURE__ */ new Date()).toISOString())
+});
+var webhooksConfigSchema = z7.object({
+  webhooks: z7.array(webhookEntrySchema).default([])
+});
+function getWebhooksConfigPath() {
+  return path18.join(getDataDir(), "webhooks.json");
+}
+async function loadWebhooksConfig() {
+  const configPath = getWebhooksConfigPath();
+  if (!existsSync10(configPath)) {
+    return { webhooks: [] };
+  }
+  const raw = await readFile15(configPath, "utf-8");
+  const parsed = JSON.parse(raw);
+  return webhooksConfigSchema.parse(parsed);
+}
+async function saveWebhooksConfig(config) {
+  const configPath = getWebhooksConfigPath();
+  await mkdir8(getDataDir(), { recursive: true });
+  await writeFile9(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+async function addWebhook(input) {
+  const config = await loadWebhooksConfig();
+  const entry = webhookEntrySchema.parse(input);
+  const existing = config.webhooks.findIndex((w) => w.url === entry.url);
+  if (existing >= 0) {
+    config.webhooks[existing] = entry;
+  } else {
+    config.webhooks.push(entry);
+  }
+  await saveWebhooksConfig(config);
+  return entry;
+}
+async function removeWebhook(url) {
+  const config = await loadWebhooksConfig();
+  const initialLength = config.webhooks.length;
+  config.webhooks = config.webhooks.filter((w) => w.url !== url);
+  if (config.webhooks.length === initialLength) {
+    return false;
+  }
+  await saveWebhooksConfig(config);
+  return true;
+}
+async function listWebhooks() {
+  const config = await loadWebhooksConfig();
+  return config.webhooks;
+}
+async function testWebhooks() {
+  const webhooks = await listWebhooks();
+  if (webhooks.length === 0) {
+    return [];
+  }
+  const payload = {
+    type: "test",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    runId: `test-${Date.now()}`,
+    status: "test",
+    summary: "Test webhook from neo CLI"
+  };
+  const results = await Promise.all(
+    webhooks.map(async (webhook) => {
+      const start = Date.now();
+      const body = JSON.stringify(payload);
+      try {
+        const response = await fetch(webhook.url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body,
+          signal: AbortSignal.timeout(webhook.timeoutMs)
+        });
+        return {
+          url: webhook.url,
+          success: response.ok,
+          statusCode: response.status,
+          durationMs: Date.now() - start
+        };
+      } catch (err) {
+        return {
+          url: webhook.url,
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+          durationMs: Date.now() - start
+        };
+      }
+    })
+  );
+  return results;
+}
+
 // src/index.ts
 var VERSION = "0.1.0";
 export {
   ActivityLog,
   AgentRegistry,
+  ConfigStore,
   CostJournal,
+  DecisionStore,
   EventJournal,
   EventQueue,
   HeartbeatLoop,
@@ -4965,13 +6015,14 @@ export {
   Semaphore,
   SessionError,
   SessionExecutor,
+  StatusReader,
   SupervisorDaemon,
   VERSION,
   WebhookDispatcher,
   WebhookServer,
-  WorkflowRegistry,
   activityEntrySchema,
   addRepoToGlobalConfig,
+  addWebhook,
   agentConfigSchema,
   agentModelSchema,
   agentSandboxSchema,
@@ -4988,6 +6039,8 @@ export {
   buildSandboxConfig,
   createBranch,
   createSessionClone,
+  decisionOptionSchema,
+  decisionSchema,
   deleteBranch,
   fetchRemote,
   getBranchName,
@@ -4999,6 +6052,7 @@ export {
   getRunLogPath,
   getRunsDir,
   getSupervisorActivityPath,
+  getSupervisorDecisionsPath,
   getSupervisorDir,
   getSupervisorEventsPath,
   getSupervisorInboxPath,
@@ -5010,11 +6064,11 @@ export {
   isProcessAlive,
   listReposFromGlobalConfig,
   listSessionClones,
+  listWebhooks,
   loadAgentFile,
   loadConfig,
   loadGlobalConfig,
   loadRepoInstructions,
-  loadWorkflow,
   loopDetection,
   matchesFilter,
   mcpServerConfigSchema,
@@ -5024,15 +6078,18 @@ export {
   pushSessionBranch,
   removeRepoFromGlobalConfig,
   removeSessionClone,
+  removeWebhook,
   repoConfigSchema,
+  repoOverrideConfigSchema,
   resolveAgent,
   runSession,
   runWithRecovery,
   supervisorDaemonStateSchema,
   supervisorDaemonStateSchema as supervisorStateSchema,
+  supervisorStatusSchema,
+  testWebhooks,
   toRepoSlug,
-  webhookIncomingEventSchema,
-  workflowGateDefSchema,
-  workflowStepDefSchema
+  webhookEntrySchema,
+  webhookIncomingEventSchema
 };
 //# sourceMappingURL=index.js.map