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

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { z, ZodType } from 'zod';
 import { HookEvent as HookEvent$1, HookCallbackMatcher } from '@anthropic-ai/claude-agent-sdk';
+import { ChildProcess } from 'node:child_process';
 
 declare const agentModelSchema: z.ZodEnum<{
     opus: "opus";
@@ -88,9 +89,6 @@ declare const agentConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 type AgentConfig = z.infer<typeof agentConfigSchema>;
-type AgentModel = z.infer<typeof agentModelSchema>;
-type AgentTool = z.infer<typeof agentToolSchema>;
-type AgentToolEntry = z.infer<typeof agentToolEntrySchema>;
 
 /**
  * Load a single agent definition from a YAML file.
@@ -427,14 +425,18 @@ interface PersistedRun {
     branch?: string | undefined;
     sessionPath?: string | undefined;
     pid?: number | undefined;
-    status: "running" | "paused" | "completed" | "failed";
+    status: "running" | "paused" | "completed" | "failed" | "blocked";
+    /** Reason why this run is blocked (if status is "blocked") */
+    blockedReason?: string | undefined;
+    /** Timestamp when the run was blocked */
+    blockedAt?: string | undefined;
     steps: Record<string, StepResult>;
     createdAt: string;
     updatedAt: string;
     metadata?: Record<string, unknown> | undefined;
 }
 interface StepResult {
-    status: "pending" | "running" | "success" | "failure" | "skipped";
+    status: "pending" | "running" | "success" | "failure" | "skipped" | "blocked";
     sessionId?: string | undefined;
     output?: unknown;
     rawOutput?: string | undefined;
@@ -446,6 +448,8 @@ interface StepResult {
     startedAt?: string | undefined;
     completedAt?: string | undefined;
     error?: string | undefined;
+    /** Reason why this step is blocked (if status is "blocked") */
+    blockedReason?: string | undefined;
     attempt: number;
 }
 type Priority = "critical" | "high" | "medium" | "low";
@@ -1048,6 +1052,13 @@ declare function getRunDispatchPath(repoSlug: string, runId: string): string;
  * Path to the log file for a detached run.
  */
 declare function getRunLogPath(repoSlug: string, runId: string): string;
+/**
+ * Path to the worker startup confirmation file for a detached run.
+ * This file is written immediately after worker process starts to confirm
+ * it survived the spawn phase. The parent process checks for this file
+ * to detect early worker crashes.
+ */
+declare function getWorkerStartedPath(repoSlug: string, runId: string): string;
 /**
  * Directory for all supervisor instances: ~/.neo/supervisors/
  */
@@ -1065,6 +1076,15 @@ declare function getSupervisorInboxPath(name: string): string;
 declare function getSupervisorEventsPath(name: string): string;
 declare function getSupervisorLockPath(name: string): string;
 declare function getSupervisorDecisionsPath(name: string): string;
+/**
+ * Path to the children registry file: ~/.neo/supervisors/<name>/children.json
+ * Written by ChildRegistry, read by the TUI to display focused child supervisors.
+ */
+declare function getSupervisorChildrenPath(name: string): string;
+/**
+ * Directory for a specific focused supervisor: ~/.neo/supervisors/focused/<id>/
+ */
+declare function getFocusedSupervisorDir(supervisorId: string): string;
 
 interface ParsedOutput {
     rawOutput: string;
@@ -1140,6 +1160,9 @@ interface RecoveryOptions extends SessionOptions {
  *
  * Non-retryable errors skip to immediate failure.
  * Backoff: backoffBaseMs * attempt between levels.
+ *
+ * On retry, the prompt is enriched with failure context from the previous
+ * attempt, giving the agent information to try a different approach.
  */
 declare function runWithRecovery(options: RecoveryOptions): Promise<SessionResult>;
 
@@ -1273,6 +1296,7 @@ declare class DecisionStore {
     private withWriteLock;
     /**
      * Create a new decision and persist it.
+     * Uses a mutex to serialize concurrent calls and prevent race conditions.
      * @returns The generated decision ID
      */
     create(input: DecisionInput): Promise<string>;
@@ -1295,6 +1319,11 @@ declare class DecisionStore {
      * Get a specific decision by ID.
      */
     get(id: string): Promise<Decision | null>;
+    /**
+     * Check if a decision has already been answered without throwing.
+     * Returns true if answered, false otherwise (including non-existent decisions).
+     */
+    isAnswered(id: string): Promise<boolean>;
     /**
      * Auto-answer expired decisions with their defaultAnswer.
      * Decisions without defaultAnswer are marked as expired (expiredAt).
@@ -1364,10 +1393,10 @@ declare const activityEntrySchema: z.ZodObject<{
         message: "message";
         decision: "decision";
         tool_use: "tool_use";
+        warning: "warning";
         action: "action";
         event: "event";
         heartbeat: "heartbeat";
-        warning: "warning";
         thinking: "thinking";
         plan: "plan";
         dispatch: "dispatch";
@@ -1452,15 +1481,84 @@ type QueuedEvent = {
     kind: "internal";
     eventKind: InternalEventKind;
     timestamp: string;
+} | {
+    kind: "child_supervisor";
+    message: ChildToParentMessage;
+    timestamp: string;
 };
+declare const childHandleSchema: z.ZodObject<{
+    supervisorId: z.ZodString;
+    objective: z.ZodString;
+    depth: z.ZodNumber;
+    startedAt: z.ZodString;
+    lastProgressAt: z.ZodString;
+    costUsd: z.ZodDefault<z.ZodNumber>;
+    maxCostUsd: z.ZodOptional<z.ZodNumber>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        blocked: "blocked";
+        complete: "complete";
+        stalled: "stalled";
+    }>;
+}, z.core.$strip>;
+type ChildHandle = z.infer<typeof childHandleSchema>;
+declare const childToParentMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    supervisorId: z.ZodString;
+    summary: z.ZodString;
+    costDelta: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"complete">;
+    supervisorId: z.ZodString;
+    summary: z.ZodString;
+    evidence: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"blocked">;
+    supervisorId: z.ZodString;
+    reason: z.ZodString;
+    question: z.ZodString;
+    urgency: z.ZodEnum<{
+        high: "high";
+        low: "low";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"failed">;
+    supervisorId: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"session">;
+    supervisorId: z.ZodString;
+    sessionId: z.ZodString;
+}, z.core.$strip>], "type">;
+type ChildToParentMessage = z.infer<typeof childToParentMessageSchema>;
+declare const parentToChildMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"unblock">;
+    answer: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"stop">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"inject">;
+    context: z.ZodString;
+}, z.core.$strip>], "type">;
+type ParentToChildMessage = z.infer<typeof parentToChildMessageSchema>;
 
 declare class ActivityLog {
     readonly filePath: string;
     private readonly dir;
+    /** Promise-based mutex to serialize write operations */
+    private writeLock;
     constructor(dir: string);
+    /**
+     * Acquire the write lock and execute a callback.
+     * Serializes write operations to prevent race conditions during rotation.
+     */
+    private withWriteLock;
     /**
      * Append a structured entry to the activity log.
      * Rotates the file if it exceeds MAX_SIZE_BYTES.
+     * Uses a mutex to serialize concurrent calls and prevent race conditions.
      */
     append(entry: ActivityEntry): Promise<void>;
     /**
@@ -1474,11 +1572,171 @@ declare class ActivityLog {
     private checkRotation;
 }
 
+declare const supervisorCompleteSchema: z.ZodObject<{
+    summary: z.ZodString;
+    evidence: z.ZodArray<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    criteriaResults: z.ZodArray<z.ZodObject<{
+        criterion: z.ZodString;
+        met: z.ZodBoolean;
+        evidence: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const supervisorBlockedSchema: z.ZodObject<{
+    reason: z.ZodString;
+    question: z.ZodString;
+    context: z.ZodString;
+    urgency: z.ZodEnum<{
+        high: "high";
+        low: "low";
+    }>;
+}, z.core.$strip>;
+type SupervisorCompleteInput = z.infer<typeof supervisorCompleteSchema>;
+type SupervisorBlockedInput = z.infer<typeof supervisorBlockedSchema>;
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+
+/**
+ * Opaque session handle — each adapter stores what it needs.
+ * Persisted via SupervisorStore so it survives process restart.
+ * Only "claude" is implemented now — others are reserved for future providers.
+ */
+type SessionHandle = {
+    provider: "claude";
+    sessionId: string;
+};
+type SupervisorMessageKind = "text" | "tool_use" | "end";
+interface SupervisorMessage {
+    kind: SupervisorMessageKind;
+    toolName?: string;
+    toolInput?: unknown;
+    text?: string;
+}
+interface AIQueryOptions {
+    prompt: string;
+    tools: ToolDefinition[];
+    sessionHandle?: SessionHandle;
+    systemPrompt?: string;
+    model?: string;
+}
+/**
+ * Adapter interface for AI providers.
+ * ClaudeAdapter is the default implementation.
+ * Future: OpenAIAdapter, GeminiAdapter, OllamaAdapter.
+ */
+interface AIAdapter {
+    /**
+     * Execute one turn of the supervisor conversation.
+     * Returns an async iterable of structured messages.
+     */
+    query(options: AIQueryOptions): AsyncIterable<SupervisorMessage>;
+    /** Returns the current session handle (undefined before first turn). */
+    getSessionHandle(): SessionHandle | undefined;
+    /** Restore a previously persisted session handle. */
+    restoreSession(handle: SessionHandle): void;
+}
+
+declare class ClaudeAdapter implements AIAdapter {
+    private sessionHandle;
+    getSessionHandle(): SessionHandle | undefined;
+    restoreSession(handle: SessionHandle): void;
+    query(options: AIQueryOptions): AsyncIterable<SupervisorMessage>;
+}
+
+interface ChildSpawnCommand {
+    objective: string;
+    acceptanceCriteria: string[];
+    maxCostUsd?: number;
+}
+/**
+ * Parse a child:spawn command from inbox message.
+ * Format: "child:spawn <JSON payload>"
+ */
+declare function parseChildSpawnCommand(text: string): ChildSpawnCommand | null;
+
+interface ChildRegistryOptions {
+    onMessage: (message: ChildToParentMessage) => void;
+    stallTimeoutMs?: number;
+    /** If provided, children.json is written here after every mutation. */
+    childrenFilePath?: string;
+}
+/**
+ * Tracks all active focused supervisor child processes.
+ * Handles IPC message routing, budget enforcement, and stall detection.
+ */
+declare class ChildRegistry {
+    private readonly handles;
+    private readonly processes;
+    private readonly stopCallbacks;
+    private readonly stallTimers;
+    private readonly onMessage;
+    private readonly stallTimeoutMs;
+    private readonly childrenFilePath;
+    constructor(options: ChildRegistryOptions);
+    /**
+     * Register a child handle.
+     */
+    register(handle: ChildHandle, stopCallback?: () => void, childProcess?: ChildProcess): void;
+    get(supervisorId: string): ChildHandle | undefined;
+    list(): ChildHandle[];
+    /**
+     * Send a message to a child via IPC.
+     */
+    send(supervisorId: string, message: ParentToChildMessage): void;
+    /**
+     * Handle an incoming IPC message from a child.
+     * Updates state, enforces budget, forwards to caller.
+     */
+    handleMessage(message: ChildToParentMessage): void;
+    /**
+     * Remove a child from the registry and clean up.
+     */
+    remove(supervisorId: string): void;
+    /**
+     * Send stop to all children (called on daemon shutdown).
+     */
+    stopAll(): void;
+    private stopChild;
+    private persistChildren;
+    private resetStallTimer;
+    private clearStallTimer;
+}
+
+interface SpawnChildOptions {
+    objective: string;
+    acceptanceCriteria: string[];
+    registry: ChildRegistry;
+    workerPath: string;
+    parentName: string;
+    maxCostUsd?: number;
+    depth?: number;
+}
+interface SpawnChildResult {
+    supervisorId: string;
+    childProcess: ChildProcess;
+}
+/**
+ * Spawn a focused child supervisor as a forked process.
+ * The child communicates via IPC and is tracked by the ChildRegistry.
+ */
+declare function spawnChildSupervisor(options: SpawnChildOptions): Promise<SpawnChildResult>;
+
+/**
+ * Read child handles from children.json.
+ * Returns empty array if file does not exist or is malformed.
+ */
+declare function readChildrenFile(filePath: string): Promise<ChildHandle[]>;
+
 interface SupervisorDaemonOptions {
     name: string;
     config: GlobalConfig;
     /** Path to bundled default SUPERVISOR.md (e.g. from @neotx/agents) */
     defaultInstructionsPath?: string | undefined;
+    /** Path to child-supervisor-worker.js for spawning child processes */
+    workerPath?: string | undefined;
 }
 /**
  * Orchestrates all supervisor components: webhook server, event queue,
@@ -1489,11 +1747,13 @@ declare class SupervisorDaemon {
     private readonly config;
     private readonly dir;
     private readonly defaultInstructionsPath;
+    private readonly workerPath;
     private webhookServer;
     private eventQueue;
     private heartbeatLoop;
     private activityLog;
     private decisionStore;
+    private childRegistry;
     private sessionId;
     constructor(options: SupervisorDaemonOptions);
     start(): Promise<void>;
@@ -1501,6 +1761,16 @@ declare class SupervisorDaemon {
     private getHealthInfo;
     private readState;
     private writeState;
+    /**
+     * Atomically acquire a lockfile using O_EXCL flag.
+     * Handles stale locks by checking if the owning process is still alive.
+     *
+     * Note: A small race window exists between stale lock removal and retry.
+     * Another process could grab the lock during this window, which is acceptable
+     * because we detect and report it on the retry attempt. This is a best-effort
+     * pattern — a true CAS (compare-and-swap) would require platform-specific APIs.
+     */
+    private acquireLock;
     private readLockPid;
     /**
      * Handle decision:answer webhook events.
@@ -1509,6 +1779,89 @@ declare class SupervisorDaemon {
     private handleDecisionAnswer;
 }
 
+declare const directiveTriggerSchema: z.ZodEnum<{
+    idle: "idle";
+    startup: "startup";
+    shutdown: "shutdown";
+}>;
+type DirectiveTrigger = z.infer<typeof directiveTriggerSchema>;
+declare const directiveSchema: z.ZodObject<{
+    id: z.ZodString;
+    trigger: z.ZodEnum<{
+        idle: "idle";
+        startup: "startup";
+        shutdown: "shutdown";
+    }>;
+    action: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodCoercedString<unknown>;
+    expiresAt: z.ZodOptional<z.ZodCoercedString<unknown>>;
+    lastTriggeredAt: z.ZodOptional<z.ZodCoercedString<unknown>>;
+}, z.core.$strip>;
+type Directive = z.infer<typeof directiveSchema>;
+interface DirectiveCreateInput {
+    trigger: DirectiveTrigger;
+    action: string;
+    description?: string;
+    priority?: number;
+    expiresAt?: string;
+}
+/**
+ * Parse a human-readable duration string into an ISO timestamp.
+ *
+ * Supported formats:
+ * - "for X hours" / "for X minutes" / "for X days"
+ * - "until midnight"
+ * - "until HH:MM"
+ * - "2h" / "30m" / "7d" (shorthand)
+ * - "indefinitely" / "" → returns undefined (no expiry)
+ *
+ * @returns ISO timestamp string or undefined for indefinite
+ */
+declare function parseDirectiveDuration(input: string): string | undefined;
+/**
+ * JSONL-based store for persistent directives.
+ * Each line is a complete directive record (append-only with periodic compaction).
+ * Uses an in-memory mutex to serialize write operations.
+ */
+declare class DirectiveStore {
+    private readonly filePath;
+    /** Promise-based mutex to serialize write operations */
+    private writeLock;
+    constructor(filePath: string);
+    /**
+     * Acquire the write lock and execute a callback.
+     * Serializes all write operations to prevent race conditions.
+     */
+    private withWriteLock;
+    /**
+     * Create a new directive and persist it.
+     * Uses a mutex to serialize concurrent calls and prevent race conditions.
+     */
+    create(input: DirectiveCreateInput): Promise<string>;
+    get(id: string): Promise<Directive | undefined>;
+    list(): Promise<Directive[]>;
+    /**
+     * Get active directives (enabled, not expired).
+     * Optionally filter by trigger type.
+     * Sorted by priority descending.
+     */
+    active(trigger?: DirectiveTrigger): Promise<Directive[]>;
+    toggle(id: string, enabled: boolean): Promise<void>;
+    markTriggered(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    /**
+     * Remove directives that expired more than 24 hours ago.
+     * Returns IDs of removed directives.
+     */
+    expireOld(): Promise<string[]>;
+    private readAll;
+    private writeAll;
+    private append;
+}
+
 interface EventQueueOptions {
     maxEventsPerSec: number;
 }
@@ -1538,6 +1891,7 @@ interface DrainAndGroupResult {
  */
 declare class EventQueue {
     private readonly queue;
+    /** Set of event IDs for deduplication. Map preserves insertion order, so first entry is oldest. */
     private readonly seenIds;
     private readonly maxSeenIds;
     private readonly maxEventsPerSec;
@@ -1547,11 +1901,23 @@ declare class EventQueue {
     private fileOffsets;
     /** Resolve function to wake up the heartbeat loop when an event arrives */
     private wakeUp;
+    /** Write locks keyed by file path to serialize read-modify-write operations */
+    private readonly writeLocks;
     constructor(options: EventQueueOptions);
+    /**
+     * Acquire the write lock for a file path and execute a callback.
+     * Serializes write operations per-file to prevent race conditions during read-modify-write.
+     */
+    private withWriteLock;
     /**
      * Push an event into the queue. Applies dedup and rate limiting.
      */
     push(event: QueuedEvent): boolean;
+    /**
+     * Evicts the oldest entry from seenIds.
+     * Map preserves insertion order, so the first key is the oldest — O(1) eviction.
+     */
+    private evictOldestSeenId;
     /**
      * Drain all queued events and return them. Clears the queue.
      */
@@ -1583,6 +1949,10 @@ declare class EventQueue {
     interrupt(): void;
     private getEventId;
     private watchJsonlFile;
+    /**
+     * Properly close and remove a watcher from the active list.
+     */
+    private cleanupWatcher;
     private readNewLines;
     private replayFile;
     /**
@@ -1592,6 +1962,69 @@ declare class EventQueue {
     private markInFile;
 }
 
+interface FocusedSupervisorState {
+    supervisorId: string;
+    status: "running" | "blocked" | "complete" | "failed";
+    startedAt: string;
+    costUsd: number;
+    objective?: string;
+    lastProgressAt?: string;
+}
+/**
+ * Pluggable persistence interface for focused supervisor state.
+ * Default implementation: JsonlSupervisorStore (zero-infra, CLI use case).
+ * Future: SqliteSupervisorStore, PostgresSupervisorStore.
+ */
+interface SupervisorStore {
+    getSessionId(supervisorId: string): Promise<string | undefined>;
+    saveSessionId(supervisorId: string, sessionId: string): Promise<void>;
+    appendActivity(supervisorId: string, entry: ActivityEntry): Promise<void>;
+    getRecentActivity(supervisorId: string, limit?: number): Promise<ActivityEntry[]>;
+    getState(supervisorId: string): Promise<FocusedSupervisorState | null>;
+    saveState(supervisorId: string, state: FocusedSupervisorState): Promise<void>;
+    recordCost(supervisorId: string, costUsd: number): Promise<void>;
+    getTotalCost(supervisorId: string): Promise<number>;
+}
+
+interface FocusedLoopOptions {
+    supervisorId: string;
+    objective: string;
+    acceptanceCriteria: string[];
+    adapter: AIAdapter;
+    store: SupervisorStore;
+    onComplete: (result: SupervisorCompleteInput) => void | Promise<void>;
+    onBlocked: (blocked: SupervisorBlockedInput) => void | Promise<void>;
+    onProgress: (summary: string, costDelta: number) => void | Promise<void>;
+    tickIntervalMs?: number;
+    systemPrompt?: string;
+}
+/**
+ * Runs a persistent SDK conversation focused on a single objective.
+ * Loops via runOnce() until supervisor_complete or supervisor_blocked is called,
+ * or until stop() is called.
+ */
+declare class FocusedLoop {
+    private readonly options;
+    private stopping;
+    private injectedContext;
+    constructor(options: FocusedLoopOptions);
+    /** Inject context from parent supervisor (via IPC inject message). */
+    injectContext(context: string): void;
+    /** Signal the loop to stop after the current turn. */
+    stop(): void;
+    /**
+     * Execute one turn of the focused loop.
+     * Returns true if the loop should continue, false if it should stop.
+     */
+    runOnce(): Promise<boolean>;
+    /**
+     * Run the full loop until complete, blocked, or stopped.
+     */
+    run(): Promise<void>;
+    /** Returns true if the tool call is terminal (complete or blocked). */
+    private handleToolUse;
+}
+
 declare const supervisorWebhookEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"supervisor_started">;
     supervisorId: z.ZodString;
@@ -1606,6 +2039,13 @@ declare const supervisorWebhookEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject
         todayUsd: z.ZodNumber;
         limitUsd: z.ZodNumber;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"heartbeat_failure">;
+    supervisorId: z.ZodString;
+    heartbeatId: z.ZodString;
+    timestamp: z.ZodString;
+    error: z.ZodString;
+    consecutiveFailures: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"run_dispatched">;
     supervisorId: z.ZodString;
@@ -1626,6 +2066,14 @@ declare const supervisorWebhookEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     output: z.ZodOptional<z.ZodString>;
     costUsd: z.ZodNumber;
     durationMs: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ghost_run_recovered">;
+    supervisorId: z.ZodString;
+    runId: z.ZodString;
+    agent: z.ZodString;
+    repo: z.ZodString;
+    timestamp: z.ZodString;
+    reason: z.ZodLiteral<"supervisor crashed">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"supervisor_stopped">;
     supervisorId: z.ZodString;
@@ -1659,6 +2107,14 @@ interface HeartbeatLoopOptions {
     repoPath?: string | undefined;
     /** Debounce time in ms for config file changes (default: 500) */
     configWatcherDebounceMs?: number | undefined;
+    /** Optional child registry for focused supervisor IPC integration */
+    childRegistry?: ChildRegistry | undefined;
+    /** Path to child-supervisor-worker.js for spawning child processes */
+    workerPath?: string | undefined;
+    /** Name of this supervisor instance (for child spawn registration) */
+    supervisorName?: string | undefined;
+    /** Path to directives storage */
+    directivesPath?: string | undefined;
 }
 /**
  * The core autonomous loop. At each iteration:
@@ -1688,16 +2144,55 @@ declare class HeartbeatLoop {
     private readonly memoryDbPath;
     private readonly onWebhookEvent;
     private decisionStore;
+    /** Cache of decision IDs already answered in this session to prevent re-answer spam */
+    private readonly answeredDecisionIds;
     /** ConfigWatcher for hot-reload support */
     private configWatcher;
     private configStore;
     private readonly repoPath;
     private readonly configWatcherDebounceMs;
+    private readonly childRegistry;
+    private readonly workerPath;
+    private readonly supervisorName;
+    private directiveStore;
+    private readonly directivesPath;
+    private errorBoundary;
     constructor(options: HeartbeatLoopOptions);
     /** Path to the inbox/events directory for markProcessed() calls */
     get eventsPath(): string;
+    /** Track store initialization failures for health reporting */
+    private storeInitErrors;
     private getMemoryStore;
+    private taskStore;
+    private getTaskStore;
     private getDecisionStore;
+    private getDirectiveStore;
+    /**
+     * Returns the health status of all stores.
+     * Useful for diagnostics and monitoring degraded mode.
+     */
+    getStoreHealth(): {
+        memory: {
+            available: boolean;
+            error: string | undefined;
+        };
+        task: {
+            available: boolean;
+            error: string | undefined;
+        };
+        directive: {
+            available: boolean;
+            error: string | undefined;
+        };
+        decision: {
+            available: boolean;
+        };
+    };
+    /**
+     * Get or create the HeartbeatErrorBoundary instance.
+     * Lazily initialized to ensure sessionId is available.
+     */
+    private getErrorBoundary;
     start(): Promise<void>;
     stop(): void;
     /**
@@ -1721,11 +2216,11 @@ declare class HeartbeatLoop {
      */
     private processDecisions;
     /**
-     * Gather event context: drain queue, fetch active runs, memories, and recent actions.
+     * Gather event context: drain queue, fetch active runs, memories, tasks, recent actions, and active directives.
      */
     private gatherEventContext;
     /**
-     * Handle post-SDK processing: mark events as processed, consolidate log buffer.
+     * Handle post-SDK processing: mark events as processed, consolidate log buffer, clean up old directives.
      */
     private handlePostSdkProcessing;
     /**
@@ -1787,8 +2282,23 @@ declare class HeartbeatLoop {
     /**
      * Process decision:answer events from inbox messages.
      * Expected format: "decision:answer <decisionId> <answer>"
+     *
+     * Uses an in-memory deduplication cache to prevent re-answering decisions
+     * that have already been processed, avoiding the "already answered" error spam.
      */
     private processDecisionAnswers;
+    /**
+     * Process child:* commands from inbox messages.
+     * Routes inject/unblock/stop to the ChildRegistry via IPC.
+     * These messages are consumed here and not forwarded to the AI prompt.
+     */
+    private processChildCommands;
+    /**
+     * Process child:spawn commands from inbox messages.
+     * These come from `neo supervise --parent=X` CLI invocations.
+     */
+    private processChildSpawnCommands;
+    private applyDecisionAnswer;
     /**
      * Read persisted run data to extract actual status, cost, and duration.
      * Returns null if the run file cannot be found or parsed.
@@ -1809,10 +2319,22 @@ declare class HeartbeatLoop {
     private emitRunDispatched;
     /** Emit RunCompletedEvent when processing run_complete events */
     private emitRunCompleted;
+    /** Emit GhostRunRecoveredEvent when a ghost run is detected and marked failed */
+    private emitGhostRunRecovered;
+    /**
+     * Scan for ghost runs from crashed supervisors on startup.
+     * Marks them as failed and emits events for logging/debugging.
+     */
+    private recoverGhostRuns;
 }
 
+/**
+ * Read all entries from log-buffer.jsonl.
+ */
+declare function readLogBuffer(dir: string): Promise<LogBufferEntry[]>;
 /**
  * Append a single entry to the log buffer file.
+ * Uses a mutex to serialize concurrent calls and prevent race conditions.
  */
 declare function appendLogBuffer(dir: string, entry: LogBufferEntry): Promise<void>;
 
@@ -1820,29 +2342,24 @@ interface Embedder {
     embed(texts: string[]): Promise<number[][]>;
     readonly dimensions: number;
 }
-declare class LocalEmbedder implements Embedder {
-    readonly dimensions = 384;
-    embed(texts: string[]): Promise<number[][]>;
-}
 
 declare const memoryTypeSchema: z.ZodEnum<{
-    fact: "fact";
-    procedure: "procedure";
-    episode: "episode";
+    knowledge: "knowledge";
+    warning: "warning";
     focus: "focus";
-    feedback: "feedback";
-    task: "task";
 }>;
 type MemoryType = z.infer<typeof memoryTypeSchema>;
+declare const knowledgeSubtypeSchema: z.ZodEnum<{
+    fact: "fact";
+    procedure: "procedure";
+}>;
+type KnowledgeSubtype = z.infer<typeof knowledgeSubtypeSchema>;
 declare const memoryEntrySchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
-        fact: "fact";
-        procedure: "procedure";
-        episode: "episode";
+        knowledge: "knowledge";
+        warning: "warning";
         focus: "focus";
-        feedback: "feedback";
-        task: "task";
     }>;
     scope: z.ZodString;
     content: z.ZodString;
@@ -1856,17 +2373,14 @@ declare const memoryEntrySchema: z.ZodObject<{
     runId: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
     severity: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodString>;
+    subtype: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type MemoryEntry = z.infer<typeof memoryEntrySchema>;
 declare const memoryWriteInputSchema: z.ZodObject<{
     type: z.ZodEnum<{
-        fact: "fact";
-        procedure: "procedure";
-        episode: "episode";
+        knowledge: "knowledge";
+        warning: "warning";
         focus: "focus";
-        feedback: "feedback";
-        task: "task";
     }>;
     scope: z.ZodDefault<z.ZodString>;
     content: z.ZodString;
@@ -1877,7 +2391,7 @@ declare const memoryWriteInputSchema: z.ZodObject<{
     runId: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
     severity: z.ZodOptional<z.ZodString>;
-    supersedes: z.ZodOptional<z.ZodString>;
+    subtype: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type MemoryWriteInput = z.input<typeof memoryWriteInputSchema>;
 interface MemoryQuery {
@@ -1893,18 +2407,31 @@ interface MemoryStats {
     byType: Record<string, number>;
     byScope: Record<string, number>;
 }
+interface SearchResult extends MemoryEntry {
+    /** Relevance score from 0 to 1, where 1 is most relevant */
+    score: number;
+}
 
 declare class MemoryStore {
     private db;
-    private embedder;
-    private hasVec;
-    constructor(dbPath: string, embedder?: Embedder | null);
+    constructor(dbPath: string);
     private initSchema;
     /**
-     * Migrate existing tables whose CHECK constraint predates the 'task' type.
-     * SQLite doesn't allow ALTER CHECK, so we recreate the table if needed.
+     * Migrate from old schema to new schema BEFORE applying new constraints.
+     *
+     * This MUST run before CREATE TABLE IF NOT EXISTS with new CHECK constraints.
+     * Otherwise, existing databases with old constraints will fail UPDATE operations
+     * because the old CHECK constraint rejects new type values ('knowledge', 'warning').
+     *
+     * Migration steps:
+     * - fact, procedure → knowledge (with subtype)
+     * - feedback → warning
+     * - episode → delete
+     * - task → deleted (migrated by TaskStore)
+     * - Add subtype column if missing
+     * - Recreate table with new CHECK constraint
      */
-    private migrateCheckConstraint;
+    private migrateSchemaIfNeeded;
     write(input: MemoryWriteInput): Promise<string>;
     update(id: string, content: string): void;
     updateFields(id: string, fields: {
@@ -1914,11 +2441,87 @@ declare class MemoryStore {
     }): void;
     forget(id: string): void;
     query(opts?: MemoryQuery): MemoryEntry[];
-    search(text: string, opts?: MemoryQuery): Promise<MemoryEntry[]>;
+    search(text: string, opts?: MemoryQuery): Promise<SearchResult[]>;
     markAccessed(ids: string[]): void;
     decay(maxAgeDays?: number, minAccessCount?: number): number;
     expireEphemeral(): number;
     stats(): MemoryStats;
+    /**
+     * Get the top N most-accessed memories.
+     */
+    topAccessed(limit?: number): MemoryEntry[];
+    close(): void;
+}
+
+declare const taskStatusSchema: z.ZodEnum<{
+    blocked: "blocked";
+    pending: "pending";
+    in_progress: "in_progress";
+    done: "done";
+    abandoned: "abandoned";
+}>;
+type TaskStatus = z.infer<typeof taskStatusSchema>;
+declare const taskPrioritySchema: z.ZodEnum<{
+    critical: "critical";
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+type TaskPriority = z.infer<typeof taskPrioritySchema>;
+declare const taskEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    scope: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        pending: "pending";
+        in_progress: "in_progress";
+        done: "done";
+        abandoned: "abandoned";
+    }>;
+    priority: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>;
+    initiative: z.ZodOptional<z.ZodString>;
+    dependsOn: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+type TaskEntry = z.infer<typeof taskEntrySchema>;
+interface TaskCreateInput {
+    title: string;
+    scope: string;
+    status: TaskStatus;
+    priority?: TaskPriority;
+    initiative?: string;
+    dependsOn?: string;
+    context?: string;
+    runId?: string;
+}
+interface TaskQuery {
+    initiative?: string;
+    status?: TaskStatus[];
+    scope?: string;
+}
+declare class TaskStore {
+    private db;
+    constructor(dbPath: string);
+    private initSchema;
+    /**
+     * Migrate existing task-type memory entries to the tasks table.
+     * One-time migration on first open.
+     */
+    private migrateFromMemories;
+    createTask(input: TaskCreateInput): string;
+    getTask(id: string): TaskEntry | undefined;
+    updateStatus(id: string, status: TaskStatus, runId?: string): void;
+    getTasks(query?: TaskQuery): TaskEntry[];
+    deleteTask(id: string): void;
     close(): void;
 }
 
@@ -1961,6 +2564,47 @@ declare class StatusReader {
     private isRunning;
 }
 
+declare const spawnChildSupervisorInputSchema: z.ZodObject<{
+    objective: z.ZodString;
+    acceptanceCriteria: z.ZodArray<z.ZodString>;
+    maxCostUsd: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SpawnChildSupervisorInput = z.infer<typeof spawnChildSupervisorInputSchema>;
+declare const SPAWN_CHILD_SUPERVISOR_TOOL: ToolDefinition;
+
+/**
+ * JSONL-backed SupervisorStore implementation.
+ * Zero dependencies beyond Node.js built-ins.
+ * Default implementation for CLI usage (zero-infra).
+ *
+ * Layout per supervisor:
+ *   <baseDir>/<supervisorId>/session.json    — SDK session ID
+ *   <baseDir>/<supervisorId>/activity.jsonl  — activity log
+ *   <baseDir>/<supervisorId>/state.json      — current state
+ *   <baseDir>/<supervisorId>/cost.json       — accumulated cost
+ */
+declare class JsonlSupervisorStore implements SupervisorStore {
+    private readonly baseDir;
+    /** Promise-based mutex to serialize write operations */
+    private writeLock;
+    constructor(baseDir: string);
+    /**
+     * Acquire the write lock and execute a callback.
+     * Serializes all write operations to prevent race conditions.
+     */
+    private withWriteLock;
+    private supervisorDir;
+    private ensureDir;
+    getSessionId(supervisorId: string): Promise<string | undefined>;
+    saveSessionId(supervisorId: string, sessionId: string): Promise<void>;
+    appendActivity(supervisorId: string, entry: ActivityEntry): Promise<void>;
+    getRecentActivity(supervisorId: string, limit?: number): Promise<ActivityEntry[]>;
+    getState(supervisorId: string): Promise<FocusedSupervisorState | null>;
+    saveState(supervisorId: string, state: FocusedSupervisorState): Promise<void>;
+    recordCost(supervisorId: string, costUsd: number): Promise<void>;
+    getTotalCost(supervisorId: string): Promise<number>;
+}
+
 interface WebhookServerOptions {
     port: number;
     secret?: string | undefined;
@@ -1984,6 +2628,8 @@ declare class WebhookServer {
     private readonly eventsPath;
     private readonly onEvent;
     private readonly getHealth;
+    /** Promise-based mutex to serialize write operations */
+    private writeLock;
     constructor(options: WebhookServerOptions);
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -1991,6 +2637,11 @@ declare class WebhookServer {
     private handleWebhook;
     private readBody;
     private sendJson;
+    /**
+     * Acquire the write lock and execute a callback.
+     * Serializes all write operations to prevent race conditions.
+     */
+    private withWriteLock;
 }
 
 declare const webhookEntrySchema: z.ZodObject<{
@@ -2038,4 +2689,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, 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 };
+export { type AIAdapter, type AIQueryOptions, type ActiveSession, type ActivityEntry, ActivityLog, type ActivityQueryOptions, type AgentDefinition, type AgentMessageEvent, AgentRegistry, type AgentToolUseEvent, type AuditLogMiddleware, type BudgetAlertEvent, type ChildHandle, type ChildSpawnCommand, ClaudeAdapter, ConfigStore, type CostEntry, CostJournal, type CostUpdateEvent, type Decision, type DecisionInput, type DecisionOption, DecisionStore, type Directive, type DirectiveCreateInput, DirectiveStore, type DirectiveTrigger, type DispatchInput, type Embedder, EventJournal, EventQueue, FocusedLoop, type FocusedLoopOptions, type GateWaitingEvent, type GlobalConfig, HeartbeatLoop, type HeartbeatLoopOptions, type HookEvent, type InboxMessage, JsonlSupervisorStore, type KnowledgeSubtype, type LogBufferEntry, 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 ParentToChildMessage, type ParsedOutput, type PersistedRun, type Priority, type QueueDequeueEvent, type QueueEnqueueEvent, type QueuedEvent, type RecoveryOptions, type RepoConfig, type RepoConfigInput, type ResolvedAgent, type RunContext, type SDKHooks, SPAWN_CHILD_SUPERVISOR_TOOL, 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 SessionHandle, type SessionOptions, type SessionResult, type SessionStartEvent, type SpawnChildOptions, type SpawnChildResult, type SpawnChildSupervisorInput, StatusReader, type StepCompleteEvent, type StepResult, type StepStartEvent, type SubagentDefinition, SupervisorDaemon, type SupervisorDaemonOptions, type SupervisorDaemonState, type SupervisorMessage, type SupervisorStatus, type TaskCreateInput, type TaskEntry, type TaskPriority, type TaskQuery, type TaskResult, type TaskStatus, TaskStore, 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, getFocusedSupervisorDir, getJournalsDir, getRepoRunsDir, getRunDispatchPath, getRunLogPath, getRunsDir, getSupervisorActivityPath, getSupervisorChildrenPath, getSupervisorDecisionsPath, getSupervisorDir, getSupervisorEventsPath, getSupervisorInboxPath, getSupervisorLockPath, getSupervisorStatePath, getSupervisorsDir, getWorkerStartedPath, globalConfigSchema, inboxMessageSchema, isProcessAlive, knowledgeSubtypeSchema, listReposFromGlobalConfig, listSessionClones, listWebhooks, loadAgentFile, loadConfig, loadGlobalConfig, loadRepoInstructions, loopDetection, matchesFilter, mcpServerConfigSchema, neoConfigSchema, parseChildSpawnCommand, parseDirectiveDuration, parseOutput, pushBranch, pushSessionBranch, readChildrenFile, readLogBuffer, removeRepoFromGlobalConfig, removeSessionClone, removeWebhook, repoConfigSchema, repoOverrideConfigSchema, resolveAgent, runSession, runWithRecovery, spawnChildSupervisor, spawnChildSupervisorInputSchema, supervisorDaemonStateSchema, supervisorStatusSchema, taskEntrySchema, taskPrioritySchema, taskStatusSchema, testWebhooks, toRepoSlug, webhookEntrySchema, webhookIncomingEventSchema };