@neotx/core 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/index.d.ts

@@ -38,6 +38,7 @@ declare const agentConfigSchema: z.ZodObject<{
     name: z.ZodString;
     extends: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodEnum<{
         opus: "opus";
         sonnet: "sonnet";
@@ -62,7 +63,29 @@ declare const agentConfigSchema: z.ZodObject<{
         writable: "writable";
     }>>;
     maxTurns: z.ZodOptional<z.ZodNumber>;
+    maxCost: z.ZodOptional<z.ZodNumber>;
     mcpServers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        prompt: z.ZodString;
+        tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            Read: "Read";
+            Write: "Write";
+            Edit: "Edit";
+            Bash: "Bash";
+            Glob: "Glob";
+            Grep: "Grep";
+            Agent: "Agent";
+            WebSearch: "WebSearch";
+            WebFetch: "WebFetch";
+            NotebookEdit: "NotebookEdit";
+        }>>>;
+        model: z.ZodOptional<z.ZodEnum<{
+            opus: "opus";
+            sonnet: "sonnet";
+            haiku: "haiku";
+        }>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type AgentConfig = z.infer<typeof agentConfigSchema>;
 type AgentModel = z.infer<typeof agentModelSchema>;
@@ -368,18 +391,31 @@ declare function removeRepoFromGlobalConfig(pathOrName: string): Promise<boolean
  */
 declare function listReposFromGlobalConfig(): Promise<RepoConfig[]>;
 
+interface SubagentDefinition {
+    description: string;
+    prompt: string;
+    tools?: string[] | undefined;
+    model?: string | undefined;
+}
 interface AgentDefinition {
     description: string;
     prompt: string;
     tools: string[];
     model: string;
     mcpServers?: string[] | undefined;
+    agents?: Record<string, SubagentDefinition> | undefined;
 }
 interface ResolvedAgent {
     name: string;
     definition: AgentDefinition;
     sandbox: "writable" | "readonly";
     maxTurns?: number | undefined;
+    /**
+     * Maximum cost in USD for this agent session.
+     * Checked post-session; if session cost >= maxCost, budget_exceeded error is thrown.
+     */
+    maxCost?: number | undefined;
+    version?: string | undefined;
     source: "built-in" | "custom" | "extended";
 }
 interface PersistedRun {
@@ -1058,7 +1094,9 @@ interface SessionOptions {
     env?: Record<string, string>;
     initTimeoutMs: number;
     maxDurationMs: number;
+    maxTurns?: number | undefined;
     resumeSessionId?: string | undefined;
+    agents?: Record<string, unknown> | undefined;
     onEvent?: ((event: SessionEvent) => void) | undefined;
 }
 interface SessionResult {
@@ -1208,6 +1246,16 @@ type DecisionInput = Omit<Decision, "id" | "createdAt" | "answeredAt" | "answer"
  * JSONL-backed store for decisions.
  * Append-only with in-place updates for answers and expiration.
  * Uses an in-memory mutex to serialize write operations.
+ *
+ * Compaction Strategy:
+ * - Threshold-based compaction triggers on either:
+ *   1. Tombstone ratio exceeds 30% of total valid entries (tombstones / (valid decisions + tombstones), excluding malformed lines)
+ *   2. File size exceeds 10MB (prevents unbounded growth)
+ * - Compaction rebuilds the file, filtering out tombstoned entries and preserving active decisions
+ * - In-memory index maintains O(1) lookup without full file scans
+ * - Compaction runs synchronously within the write lock to maintain consistency
+ * - During compaction: all write operations are blocked until compaction completes, preventing race conditions
+ * - Concurrent reads during compaction may return stale data from before compaction started
  */
 declare class DecisionStore {
     private readonly filePath;
@@ -1215,6 +1263,8 @@ declare class DecisionStore {
     private readonly dirCache;
     /** Promise-based mutex to serialize write operations */
     private writeLock;
+    /** Maximum file size in bytes before validation fails (default: 10MB) */
+    private readonly maxFileSizeBytes;
     constructor(filePath: string);
     /**
      * Acquire the write lock and execute a callback.
@@ -1314,9 +1364,9 @@ declare const activityEntrySchema: z.ZodObject<{
         message: "message";
         decision: "decision";
         tool_use: "tool_use";
+        action: "action";
         event: "event";
         heartbeat: "heartbeat";
-        action: "action";
         warning: "warning";
         thinking: "thinking";
         plan: "plan";
@@ -1379,8 +1429,8 @@ declare const activityQueryOptionsSchema: z.ZodObject<{
         error: "error";
         message: "message";
         decision: "decision";
-        event: "event";
         action: "action";
+        event: "event";
         plan: "plan";
         dispatch: "dispatch";
     }>>;
@@ -1988,4 +2038,4 @@ declare function testWebhooks(): Promise<WebhookTestResult[]>;
 
 declare const VERSION = "0.1.0";
 
-export { type ActiveSession, type ActivityEntry, ActivityLog, type ActivityQueryOptions, type AgentConfig, type AgentDefinition, type AgentMessageEvent, type AgentModel, AgentRegistry, type AgentTool, type AgentToolEntry, type AgentToolUseEvent, type AuditLogMiddleware, type BudgetAlertEvent, ConfigStore, type CostEntry, CostJournal, type CostUpdateEvent, type Decision, type DecisionInput, type DecisionOption, DecisionStore, type DispatchInput, type Embedder, EventJournal, EventQueue, type GateWaitingEvent, type GitStrategy, type GlobalConfig, HeartbeatLoop, type HeartbeatLoopOptions, type HookEvent, type InboxMessage, LocalEmbedder, type LoopDetectionMiddleware, type McpServerConfig, type MemoryEntry, type MemoryQuery, type MemoryStats, MemoryStore, type MemoryType, type MemoryWriteInput, type Middleware, type MiddlewareChain, type MiddlewareContext, type MiddlewareContextMap, type MiddlewareEvent, type MiddlewareHandler, type MiddlewareResult, type NeoConfig, type NeoEvent, NeoEventEmitter, Orchestrator, type OrchestratorOptions, type OrchestratorShutdownEvent, type OrchestratorStatus, type ParsedOutput, type PersistedRun, type Priority, type QueueDequeueEvent, type QueueEnqueueEvent, type QueuedEvent, type RecoveryOptions, type RepoConfig, type RepoConfigInput, type ResolvedAgent, type RunContext, type SDKHooks, type SandboxConfig, Semaphore, type SemaphoreCallbacks, type SemaphoreConfig, type SessionCloneInfo, type SessionCompleteEvent, SessionError, type SessionEvent, type SessionExecutionConfig, type SessionExecutionDeps, type SessionExecutionInput, type SessionExecutionResult, SessionExecutor, type SessionFailEvent, type SessionOptions, type SessionResult, type SessionStartEvent, StatusReader, type StepCompleteEvent, type StepResult, type StepStartEvent, SupervisorDaemon, type SupervisorDaemonOptions, type SupervisorDaemonState, type SupervisorDaemonState as SupervisorState, type SupervisorStatus, type TaskResult, VERSION, WebhookDispatcher, type WebhookEntry, type WebhookEntryInput, type WebhookIncomingEvent, WebhookServer, type WebhookTestPayload, type WebhookTestResult, activityEntrySchema, addRepoToGlobalConfig, addWebhook, agentConfigSchema, agentModelSchema, agentSandboxSchema, agentToolEntrySchema, agentToolSchema, appendLogBuffer, auditLog, budgetGuard, buildFullPrompt, buildGitStrategyInstructions, buildMiddlewareChain, buildReportingInstructions, buildSDKHooks, buildSandboxConfig, createBranch, createSessionClone, decisionOptionSchema, decisionSchema, deleteBranch, fetchRemote, getBranchName, getCurrentBranch, getDataDir, getJournalsDir, getRepoRunsDir, getRunDispatchPath, getRunLogPath, getRunsDir, getSupervisorActivityPath, getSupervisorDecisionsPath, getSupervisorDir, getSupervisorEventsPath, getSupervisorInboxPath, getSupervisorLockPath, getSupervisorStatePath, getSupervisorsDir, globalConfigSchema, inboxMessageSchema, isProcessAlive, listReposFromGlobalConfig, listSessionClones, listWebhooks, loadAgentFile, loadConfig, loadGlobalConfig, loadRepoInstructions, loopDetection, matchesFilter, mcpServerConfigSchema, neoConfigSchema, parseOutput, pushBranch, pushSessionBranch, removeRepoFromGlobalConfig, removeSessionClone, removeWebhook, repoConfigSchema, repoOverrideConfigSchema, resolveAgent, runSession, runWithRecovery, supervisorDaemonStateSchema, supervisorDaemonStateSchema as supervisorStateSchema, supervisorStatusSchema, testWebhooks, toRepoSlug, webhookEntrySchema, webhookIncomingEventSchema };
+export { type ActiveSession, type ActivityEntry, ActivityLog, type ActivityQueryOptions, type AgentConfig, type AgentDefinition, type AgentMessageEvent, type AgentModel, AgentRegistry, type AgentTool, type AgentToolEntry, type AgentToolUseEvent, type AuditLogMiddleware, type BudgetAlertEvent, ConfigStore, type CostEntry, CostJournal, type CostUpdateEvent, type Decision, type DecisionInput, type DecisionOption, DecisionStore, type DispatchInput, type Embedder, EventJournal, EventQueue, type GateWaitingEvent, type GitStrategy, type GlobalConfig, HeartbeatLoop, type HeartbeatLoopOptions, type HookEvent, type InboxMessage, LocalEmbedder, type LoopDetectionMiddleware, type McpServerConfig, type MemoryEntry, type MemoryQuery, type MemoryStats, MemoryStore, type MemoryType, type MemoryWriteInput, type Middleware, type MiddlewareChain, type MiddlewareContext, type MiddlewareContextMap, type MiddlewareEvent, type MiddlewareHandler, type MiddlewareResult, type NeoConfig, type NeoEvent, NeoEventEmitter, Orchestrator, type OrchestratorOptions, type OrchestratorShutdownEvent, type OrchestratorStatus, type ParsedOutput, type PersistedRun, type Priority, type QueueDequeueEvent, type QueueEnqueueEvent, type QueuedEvent, type RecoveryOptions, type RepoConfig, type RepoConfigInput, type ResolvedAgent, type RunContext, type SDKHooks, type SandboxConfig, Semaphore, type SemaphoreCallbacks, type SemaphoreConfig, type SessionCloneInfo, type SessionCompleteEvent, SessionError, type SessionEvent, type SessionExecutionConfig, type SessionExecutionDeps, type SessionExecutionInput, type SessionExecutionResult, SessionExecutor, type SessionFailEvent, type SessionOptions, type SessionResult, type SessionStartEvent, StatusReader, type StepCompleteEvent, type StepResult, type StepStartEvent, type SubagentDefinition, SupervisorDaemon, type SupervisorDaemonOptions, type SupervisorDaemonState, type SupervisorDaemonState as SupervisorState, type SupervisorStatus, type TaskResult, VERSION, WebhookDispatcher, type WebhookEntry, type WebhookEntryInput, type WebhookIncomingEvent, WebhookServer, type WebhookTestPayload, type WebhookTestResult, activityEntrySchema, addRepoToGlobalConfig, addWebhook, agentConfigSchema, agentModelSchema, agentSandboxSchema, agentToolEntrySchema, agentToolSchema, appendLogBuffer, auditLog, budgetGuard, buildFullPrompt, buildGitStrategyInstructions, buildMiddlewareChain, buildReportingInstructions, buildSDKHooks, buildSandboxConfig, createBranch, createSessionClone, decisionOptionSchema, decisionSchema, deleteBranch, fetchRemote, getBranchName, getCurrentBranch, getDataDir, getJournalsDir, getRepoRunsDir, getRunDispatchPath, getRunLogPath, getRunsDir, getSupervisorActivityPath, getSupervisorDecisionsPath, getSupervisorDir, getSupervisorEventsPath, getSupervisorInboxPath, getSupervisorLockPath, getSupervisorStatePath, getSupervisorsDir, globalConfigSchema, inboxMessageSchema, isProcessAlive, listReposFromGlobalConfig, listSessionClones, listWebhooks, loadAgentFile, loadConfig, loadGlobalConfig, loadRepoInstructions, loopDetection, matchesFilter, mcpServerConfigSchema, neoConfigSchema, parseOutput, pushBranch, pushSessionBranch, removeRepoFromGlobalConfig, removeSessionClone, removeWebhook, repoConfigSchema, repoOverrideConfigSchema, resolveAgent, runSession, runWithRecovery, supervisorDaemonStateSchema, supervisorDaemonStateSchema as supervisorStateSchema, supervisorStatusSchema, testWebhooks, toRepoSlug, webhookEntrySchema, webhookIncomingEventSchema };

package/dist/index.js

@@ -20,17 +20,32 @@ var agentToolSchema = z.enum([
 ]);
 var agentToolEntrySchema = z.union([agentToolSchema, z.literal("$inherited")]);
 var agentSandboxSchema = z.enum(["writable", "readonly"]);
+var subagentDefinitionSchema = z.object({
+  description: z.string(),
+  prompt: z.string(),
+  tools: z.array(agentToolSchema).optional(),
+  model: agentModelSchema.optional()
+});
 var agentConfigSchema = z.object({
   name: z.string(),
   extends: z.string().optional(),
   description: z.string().optional(),
+  version: z.string().optional(),
   model: agentModelSchema.optional(),
   tools: z.array(agentToolEntrySchema).optional(),
   prompt: z.string().optional(),
   promptAppend: z.string().optional(),
   sandbox: agentSandboxSchema.optional(),
   maxTurns: z.number().optional(),
-  mcpServers: z.array(z.string()).optional()
+  /**
+   * Maximum cost in USD for this agent session.
+   * Checked post-session (SDK provides cost only after session ends).
+   * If session cost >= maxCost, a budget_exceeded error is thrown.
+   * Child agents can override the parent's maxCost.
+   */
+  maxCost: z.number().min(0).optional(),
+  mcpServers: z.array(z.string()).optional(),
+  agents: z.record(z.string(), subagentDefinitionSchema).optional()
 });
 
 // src/agents/loader.ts
@@ -66,6 +81,20 @@ ${issues}`);
       );
     }
   }
+  if (config.agents) {
+    for (const [name, subagent] of Object.entries(config.agents)) {
+      if (subagent.prompt.endsWith(".md")) {
+        const subagentPromptPath = path.resolve(path.dirname(filePath), subagent.prompt);
+        try {
+          subagent.prompt = await readFile(subagentPromptPath, "utf-8");
+        } catch (err) {
+          throw new Error(
+            `Subagent "${name}" prompt file not found: ${subagentPromptPath} (referenced in ${filePath}). Error: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    }
+  }
   return config;
 }
 
@@ -91,18 +120,25 @@ function resolveExtendedAgent(config, extendsName, builtIns) {
   const tools = mergeTools(config.tools, base.tools);
   const prompt = mergePrompt(config.prompt, config.promptAppend, base.prompt);
   const mcpServers = mergeMcpServerNames(base.mcpServers, config.mcpServers);
+  const agents = mergeAgents(
+    base.agents,
+    config.agents
+  );
   const definition = {
     description: config.description ?? base.description ?? "",
     prompt,
     tools,
     model: config.model ?? base.model ?? "sonnet",
-    ...mcpServers.length > 0 ? { mcpServers } : {}
+    ...mcpServers.length > 0 ? { mcpServers } : {},
+    ...agents ? { agents } : {}
   };
   return {
     name: config.name,
     definition,
     sandbox: config.sandbox ?? base.sandbox ?? "readonly",
     ...config.maxTurns !== void 0 ? { maxTurns: config.maxTurns } : base.maxTurns !== void 0 ? { maxTurns: base.maxTurns } : {},
+    ...config.maxCost !== void 0 ? { maxCost: config.maxCost } : base.maxCost !== void 0 ? { maxCost: base.maxCost } : {},
+    ...config.version !== void 0 ? { version: config.version } : base.version !== void 0 ? { version: base.version } : {},
     source: config.name === extendsName && !config.extends ? "built-in" : "extended"
   };
 }
@@ -144,13 +180,16 @@ ${config.promptAppend}`;
     prompt,
     tools,
     model: config.model,
-    ...config.mcpServers?.length ? { mcpServers: config.mcpServers } : {}
+    ...config.mcpServers?.length ? { mcpServers: config.mcpServers } : {},
+    ...config.agents ? { agents: config.agents } : {}
   };
   return {
     name: config.name,
     definition,
     sandbox: config.sandbox,
     ...config.maxTurns !== void 0 ? { maxTurns: config.maxTurns } : {},
+    ...config.maxCost !== void 0 ? { maxCost: config.maxCost } : {},
+    ...config.version !== void 0 ? { version: config.version } : {},
     source: "custom"
   };
 }
@@ -175,6 +214,12 @@ function mergeMcpServerNames(base, override) {
   if (!base?.length && !override?.length) return [];
   return [.../* @__PURE__ */ new Set([...base ?? [], ...override ?? []])];
 }
+function mergeAgents(base, override) {
+  if (!base && !override) return void 0;
+  if (!base) return override;
+  if (!override) return base;
+  return { ...base, ...override };
+}
 
 // src/agents/registry.ts
 var AgentRegistry = class {
@@ -1996,7 +2041,7 @@ function buildQueryOptions(options) {
     // Always pass cwd: session clone for writable agents, repo root for readonly.
     // Without this, readonly agents default to process.cwd() and may write to main tree.
     cwd: sessionPath ?? options.repoPath,
-    // maxTurns: agent.maxTurns,
+    ...options.maxTurns ? { maxTurns: options.maxTurns } : {},
     allowedTools: sandboxConfig.allowedTools,
     // Workers run detached without a TTY — bypass interactive permission prompts.
     // Required pair: permissionMode alone is not enough, SDK also needs the flag.
@@ -2013,6 +2058,9 @@ function buildQueryOptions(options) {
   if (options.mcpServers && Object.keys(options.mcpServers).length > 0) {
     queryOptions.mcpServers = options.mcpServers;
   }
+  if (options.agents && Object.keys(options.agents).length > 0) {
+    queryOptions.agents = options.agents;
+  }
   if (options.env && Object.keys(options.env).length > 0) {
     queryOptions.env = { ...process.env, ...options.env };
   }
@@ -2241,14 +2289,23 @@ ALWAYS run commands from this directory. NEVER cd to or operate on any other rep
       sandboxConfig,
       hooks,
       env: agentEnv,
+      agents: agent.definition.agents,
       initTimeoutMs: this.config.initTimeoutMs,
       maxDurationMs: this.config.maxDurationMs,
       maxRetries: this.config.maxRetries,
       backoffBaseMs: this.config.backoffBaseMs,
       ...sessionPath ? { sessionPath } : {},
       ...mcpServers ? { mcpServers } : {},
-      ...onAttempt ? { onAttempt } : {}
+      ...onAttempt ? { onAttempt } : {},
+      ...agent.maxTurns ? { maxTurns: agent.maxTurns } : {}
     });
+    if (agent.maxCost !== void 0 && sessionResult.costUsd >= agent.maxCost) {
+      throw new SessionError(
+        `Agent session exceeded budget: $${sessionResult.costUsd.toFixed(4)} >= $${agent.maxCost.toFixed(4)} limit`,
+        "budget_exceeded",
+        sessionResult.sessionId
+      );
+    }
     const parsed = parseOutput(sessionResult.output);
     const result = {
       status: "success",
@@ -3456,9 +3513,20 @@ import { z as z5 } from "zod";
 
 // src/supervisor/decisions.ts
 import { randomUUID as randomUUID4 } from "crypto";
-import { appendFile as appendFile4, readFile as readFile6, writeFile as writeFile3 } from "fs/promises";
+import { appendFile as appendFile4, readFile as readFile6, stat as stat3, writeFile as writeFile3 } from "fs/promises";
 import path11 from "path";
 import { z as z4 } from "zod";
+var DecisionFileSizeError = class extends Error {
+  constructor(filePath, fileSizeBytes, maxSizeBytes) {
+    super(
+      `Decision file exceeds maximum size: ${filePath} (${(fileSizeBytes / 1024 / 1024).toFixed(2)}MB > ${(maxSizeBytes / 1024 / 1024).toFixed(2)}MB)`
+    );
+    this.filePath = filePath;
+    this.fileSizeBytes = fileSizeBytes;
+    this.maxSizeBytes = maxSizeBytes;
+    this.name = "DecisionFileSizeError";
+  }
+};
 var decisionOptionSchema = z4.object({
   key: z4.string(),
   label: z4.string(),
@@ -3479,12 +3547,20 @@ var decisionSchema = z4.object({
   answer: z4.string().optional(),
   expiredAt: z4.coerce.string().optional()
 });
+var tombstoneSchema = z4.object({
+  action: z4.literal("tombstone"),
+  id: z4.string(),
+  createdAt: z4.coerce.string(),
+  reason: z4.enum(["deleted", "expired", "purged"])
+});
 var DecisionStore = class {
   filePath;
   dir;
   dirCache = /* @__PURE__ */ new Set();
   /** Promise-based mutex to serialize write operations */
   writeLock = Promise.resolve();
+  /** Maximum file size in bytes before validation fails (default: 10MB) */
+  maxFileSizeBytes = 10 * 1024 * 1024;
   constructor(filePath) {
     this.filePath = filePath;
     this.dir = path11.dirname(filePath);
@@ -3607,6 +3683,10 @@ var DecisionStore = class {
   async readAll() {
     let content;
     try {
+      const stats = await stat3(this.filePath);
+      if (stats.size > this.maxFileSizeBytes) {
+        throw new DecisionFileSizeError(this.filePath, stats.size, this.maxFileSizeBytes);
+      }
       content = await readFile6(this.filePath, "utf-8");
     } catch (error) {
       if (error.code === "ENOENT") {
@@ -3733,7 +3813,7 @@ var activityQueryOptionsSchema = z5.object({
 
 // src/supervisor/activity-log.ts
 import { randomUUID as randomUUID5 } from "crypto";
-import { appendFile as appendFile5, readFile as readFile7, rename, stat as stat3 } from "fs/promises";
+import { appendFile as appendFile5, readFile as readFile7, rename, stat as stat4 } from "fs/promises";
 import path12 from "path";
 var ACTIVITY_FILE = "activity.jsonl";
 var MAX_SIZE_BYTES = 10 * 1024 * 1024;
@@ -3795,7 +3875,7 @@ var ActivityLog = class {
   }
   async checkRotation() {
     try {
-      const stats = await stat3(this.filePath);
+      const stats = await stat4(this.filePath);
       if (stats.size > MAX_SIZE_BYTES) {
         const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
         const rotatedPath = path12.join(this.dir, `activity-${timestamp}.jsonl`);
@@ -4113,7 +4193,7 @@ var IdleDetector = class {
 };
 
 // src/supervisor/log-buffer.ts
-import { appendFile as appendFile6, readFile as readFile9, stat as stat4, writeFile as writeFile5 } from "fs/promises";
+import { appendFile as appendFile6, readFile as readFile9, stat as stat5, writeFile as writeFile5 } from "fs/promises";
 import path13 from "path";
 var LOG_BUFFER_FILE = "log-buffer.jsonl";
 var MAX_FILE_BYTES = 1024 * 1024;
@@ -4247,7 +4327,9 @@ var OPERATING_PRINCIPLES = `### Operating principles
 - 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.
-- **No duplicate dispatches**: before dispatching a \`developer\` for any finding, ALWAYS check for open or recently merged PRs on the same topic: \`gh pr list --repo <repo> --search "<keywords>" --state open\` and \`--state merged --limit 5\`. If a similar PR exists \u2192 skip and log with \`neo log discovery\`. Dispatching duplicate agents wastes budget and pollutes the PR list.`;
+- **No duplicate dispatches**: before dispatching a \`developer\` for any finding, ALWAYS check for open or recently merged PRs on the same topic: \`gh pr list --repo <repo> --search "<keywords>" --state open\` and \`--state merged --limit 5\`. If a similar PR exists \u2192 skip and log with \`neo log discovery\`. Dispatching duplicate agents wastes budget and pollutes the PR list.
+- **Decision routing**: when a pending decision arrives from an agent, answer within 1-2 heartbeats. Route: (1) answer directly if strategic/scope/priority, (2) dispatch scout to investigate if codebase context needed, (3) wait for human if autoDecide is off or genuinely uncertain. Agents are BLOCKED waiting \u2014 stale decisions waste session budget.
+- **Verify agent output**: always read agent output with \`neo runs <runId>\` before dispatching follow-up work. Route based on agent output contracts documented in SUPERVISOR.md.`;
 var COMMANDS = `### Dispatching agents
 \`\`\`bash
 neo run <agent> --prompt "..." --repo <path> --branch <name> [--priority critical|high|medium|low] [--meta '<json>']
@@ -4272,7 +4354,7 @@ neo runs <runId>                    # full run details + agent output (MUST READ
 neo cost --short [--all]            # check budget
 \`\`\`
 
-\`neo runs <runId>\` returns the agent's full output. **ALWAYS read it when a run completes** \u2014 it contains structured JSON (PR URLs, issues, plans, milestones) that you need to decide next steps.
+\`neo runs <runId>\` returns the agent's full output. **ALWAYS read it when a run completes** \u2014 it contains the agent's results that you need to decide next steps per SUPERVISOR.md routing rules.
 
 ### Memory
 \`\`\`bash
@@ -4323,8 +4405,9 @@ var HEARTBEAT_RULES = `### Heartbeat lifecycle
 1. DEDUP FIRST \u2014 check focus for PROCESSED entries. Skip any runId already processed.
 2. MONITOR RUNS \u2014 \`neo runs --short\` to check active run status. If a run completed since last HB, read its output with \`neo runs <runId>\` BEFORE doing anything else.
 3. PENDING TASKS? \u2014 dispatch the next eligible task from work queue. Do not re-plan.
-4. EVENTS? \u2014 process run completions, messages, webhooks. Parse agent JSON output.
+4. EVENTS? \u2014 process run completions, messages, webhooks. Read agent output and route per SUPERVISOR.md contracts.
 5. FOLLOW-UPS? \u2014 check CI (\`gh pr checks\`), deferred dispatches.
+5b. DECISIONS? \u2014 check \`neo decision list\` for pending decisions from agents. Route each: answer directly, dispatch scout to investigate, or wait for human. Agents are blocked waiting \u2014 prioritize these.
 6. DISPATCH \u2014 route work to agents. Mark tasks \`in_progress\`, add ACTIVE to focus.
 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.
@@ -4333,15 +4416,15 @@ var HEARTBEAT_RULES = `### Heartbeat lifecycle
 <run-monitoring>
 Runs are your agents in the field. You MUST actively track them:
 - **On dispatch**: include a label in \`--meta\` for identification: \`--meta '{"label":"T6-csv-export","ticketId":"YC-42",...}'\`
-- **On completion**: ALWAYS run \`neo runs <runId>\` to read the full output. Parse structured JSON (PR URLs, issues, plans). This is NOT optional \u2014 you cannot decide next steps without reading the output.
+- **On completion**: ALWAYS run \`neo runs <runId>\` to read the full output. This is NOT optional \u2014 you cannot decide next steps without reading the output.
 - **On failure**: read the output to understand why. Decide: retry (blocked), abandon, or escalate.
 - **Active runs**: check \`neo runs --short --status running\` to verify your runs are still alive. If a run disappeared, investigate.
 </run-monitoring>
 
 <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.
+**Branch strategy:** one branch per initiative. Architect produces a plan; developer executes all tasks on that branch. 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.
+**Dispatch quality:** when dispatching developer with a plan, include the plan path and any context from completed prior work (PR numbers, APIs added). For direct tasks (no plan), write a detailed \`--prompt\` with acceptance criteria.
 
 **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.
 
@@ -4430,7 +4513,7 @@ function buildMemoryRulesExamples(supervisorDir) {
 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>"
+neo memory write --type procedure --scope /repo "After architect run: read plan path from output, dispatch developer with plan per SUPERVISOR.md routing"
 neo memory write --type procedure --scope /repo "When developer run fails with ENOSPC: the repo has large fixtures \u2014 use --branch with shallow clone flag"
 neo memory write --type feedback --scope /repo "User wants PR descriptions in French even though code is in English"
 neo memory write --type task --scope /repo --severity high --category "neo runs 2g589f34a5a" --tags "initiative:auth-v2,depends:mem_xyz" "T1: Auth middleware"