@oxgeneral/orch 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1356 @@
+import { SpawnOptions, ChildProcess } from 'node:child_process';
+
+/**
+ * Task domain model.
+ *
+ * A Task is the unit of work in the orchestrator.
+ * It moves through a state machine: todo → in_progress → review → done.
+ */
+type TaskStatus = 'todo' | 'in_progress' | 'retrying' | 'review' | 'done' | 'failed' | 'cancelled';
+type WorkspaceMode = 'shared' | 'worktree' | 'isolated';
+type ReviewCriterion = 'test_pass' | 'typecheck' | 'lint';
+interface ReviewResult {
+    criterion: ReviewCriterion;
+    passed: boolean;
+    output: string;
+}
+interface TaskProof {
+    branch?: string;
+    pr_url?: string;
+    files_changed: string[];
+    test_results?: string;
+    agent_summary?: string;
+}
+interface Task {
+    id: string;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    priority: number;
+    assignee?: string;
+    labels: string[];
+    depends_on: string[];
+    created_at: string;
+    updated_at: string;
+    attempts: number;
+    max_attempts: number;
+    workspace_mode?: WorkspaceMode;
+    workspace?: string;
+    proof?: TaskProof;
+    review_criteria?: ReviewCriterion[];
+    review_results?: ReviewResult[];
+    scope?: string[];
+    feedback?: string;
+}
+interface CreateTaskInput {
+    title: string;
+    description?: string;
+    priority?: number;
+    assignee?: string;
+    labels?: string[];
+    depends_on?: string[];
+    max_attempts?: number;
+    workspace_mode?: WorkspaceMode;
+    review_criteria?: ReviewCriterion[];
+    scope?: string[];
+}
+
+/**
+ * Agent domain model.
+ *
+ * An Agent is a configured AI tool (Claude, Codex, Shell, etc.)
+ * that can be assigned to execute Tasks.
+ */
+type AgentStatus = 'idle' | 'running' | 'error' | 'disabled';
+type ApprovalPolicy = 'suggest' | 'auto' | 'manual';
+interface AgentConfig {
+    command?: string;
+    model?: string;
+    approval_policy?: ApprovalPolicy;
+    max_turns?: number;
+    timeout_ms?: number;
+    stall_timeout_ms?: number;
+    env?: Record<string, string>;
+    system_prompt?: string;
+    workspace_mode?: WorkspaceMode;
+    skills?: string[];
+}
+interface AgentStats {
+    tasks_completed: number;
+    tasks_failed: number;
+    total_runs: number;
+    total_runtime_ms: number;
+    tokens_used?: number;
+}
+interface Agent {
+    id: string;
+    name: string;
+    adapter: string;
+    role?: string;
+    config: AgentConfig;
+    status: AgentStatus;
+    current_task?: string;
+    autonomous?: boolean;
+    stats: AgentStats;
+}
+interface CreateAgentInput {
+    name: string;
+    adapter: string;
+    role?: string;
+    command?: string;
+    model?: string;
+    approval_policy?: ApprovalPolicy;
+    max_turns?: number;
+    timeout_ms?: number;
+    stall_timeout_ms?: number;
+    env?: Record<string, string>;
+    system_prompt?: string;
+    workspace_mode?: WorkspaceMode;
+    skills?: string[];
+}
+
+/**
+ * Run domain model.
+ *
+ * A Run represents a single execution attempt of a Task by an Agent.
+ * Events are stored in separate .jsonl files (append-only), not in memory.
+ */
+type RunStatus = 'preparing' | 'running' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+interface Run {
+    id: string;
+    task_id: string;
+    agent_id: string;
+    attempt: number;
+    status: RunStatus;
+    started_at: string;
+    finished_at?: string;
+    workspace_path: string;
+    prompt: string;
+    pid?: number;
+    error?: string;
+    tokens?: TokenUsage;
+}
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+}
+/** Create TokenUsage with total always computed as input + output. */
+declare function createTokenUsage(input: number, output: number): TokenUsage;
+interface RunEvent {
+    timestamp: string;
+    type: RunEventType;
+    data: unknown;
+}
+type RunEventType = 'agent_output' | 'file_changed' | 'command_run' | 'tool_call' | 'error' | 'done';
+
+/**
+ * Configuration domain model.
+ *
+ * Represents the structure of .orchestry/config.yml
+ */
+
+interface ProjectConfig {
+    name: string;
+    description?: string;
+}
+interface AgentDefaults {
+    adapter: string;
+    approval_policy: ApprovalPolicy;
+    max_turns: number;
+    timeout_ms: number;
+    stall_timeout_ms: number;
+    workspace_mode: WorkspaceMode;
+}
+interface TaskDefaults {
+    max_attempts: number;
+    priority: number;
+}
+interface SchedulingConfig {
+    poll_interval_ms: number;
+    max_concurrent_agents: number;
+    retry_base_delay_ms: number;
+    retry_max_delay_ms: number;
+}
+interface OrchestratorConfig {
+    project: ProjectConfig;
+    defaults: {
+        agent: AgentDefaults;
+        task: TaskDefaults;
+    };
+    scheduling: SchedulingConfig;
+    prompt?: {
+        template?: string;
+    };
+}
+
+/**
+ * Orchestrator runtime state.
+ *
+ * Persisted in .orchestry/state.json.
+ * Updated on every mutation. Not intended for git.
+ */
+interface RunningEntry {
+    run_id: string;
+    agent_id: string;
+    task_id: string;
+    pid: number;
+    started_at: string;
+    last_event_at: string;
+}
+interface RetryEntry {
+    task_id: string;
+    attempt: number;
+    due_at: string;
+    error: string;
+}
+interface OrchestratorState {
+    version: 1;
+    pid?: number;
+    started_at?: string;
+    running: Record<string, RunningEntry>;
+    claimed: string[];
+    retry_queue: RetryEntry[];
+    stats: {
+        total_runs: number;
+        total_tasks_completed: number;
+        total_tasks_failed: number;
+        total_tokens: {
+            input: number;
+            output: number;
+            total: number;
+        };
+        total_runtime_ms: number;
+    };
+}
+
+/**
+ * Goal domain model.
+ *
+ * A Goal is a persistent objective that drives autonomous agent work.
+ * Goals have lower priority than tasks — agents work on goals only
+ * when no regular tasks are available.
+ *
+ * State machine: active → achieved | abandoned
+ *                active ↔ paused
+ */
+declare const GOAL_STATUSES: readonly ["active", "paused", "achieved", "abandoned"];
+type GoalStatus = (typeof GOAL_STATUSES)[number];
+interface Goal {
+    id: string;
+    title: string;
+    description: string;
+    status: GoalStatus;
+    assignee?: string;
+    created_at: string;
+    updated_at?: string;
+}
+interface CreateGoalInput {
+    title: string;
+    description?: string;
+    assignee?: string;
+}
+
+/**
+ * Message domain model.
+ *
+ * A Message is a unit of inter-agent communication.
+ * Messages are stored as JSON files and injected into agent prompts at dispatch time.
+ */
+type MessageChannel = 'direct' | 'broadcast' | 'lead';
+type MessageStatus = 'pending' | 'delivered' | 'expired';
+interface Message {
+    id: string;
+    channel: MessageChannel;
+    from_agent_id: string;
+    to_agent_id: string | null;
+    subject: string;
+    body: string;
+    created_at: string;
+    expires_at?: string;
+    status: MessageStatus;
+    delivered_at?: string;
+    team_id?: string;
+    reply_to?: string;
+}
+interface CreateMessageInput {
+    channel: MessageChannel;
+    from_agent_id: string;
+    to_agent_id?: string;
+    subject: string;
+    body: string;
+    ttl_ms?: number;
+    team_id?: string;
+    reply_to?: string;
+}
+
+/**
+ * Orchestrator event system.
+ *
+ * All communication between layers goes through typed events.
+ * The EventBus emits these synchronously; subscribers (TUI, logger,
+ * run store, state) react independently.
+ */
+
+type OrchestratorEvent = {
+    type: 'task:created';
+    task: Task;
+} | {
+    type: 'task:assigned';
+    taskId: string;
+    agentId: string;
+} | {
+    type: 'task:status_changed';
+    taskId: string;
+    from: TaskStatus;
+    to: TaskStatus;
+} | {
+    type: 'task:auto_reviewed';
+    taskId: string;
+    passed: boolean;
+    results: ReviewResult[];
+} | {
+    type: 'agent:started';
+    agentId: string;
+    taskId: string;
+    runId: string;
+} | {
+    type: 'agent:output';
+    runId: string;
+    agentId: string;
+    data: string;
+} | {
+    type: 'agent:file_changed';
+    runId: string;
+    agentId: string;
+    path: string;
+} | {
+    type: 'agent:completed';
+    runId: string;
+    agentId: string;
+    success: boolean;
+} | {
+    type: 'agent:error';
+    runId: string;
+    agentId: string;
+    error: string;
+} | {
+    type: 'run:retry';
+    runId: string;
+    attempt: number;
+    delay_ms: number;
+} | {
+    type: 'orchestrator:tick';
+    running: number;
+    queued: number;
+} | {
+    type: 'orchestrator:stall_detected';
+    runId: string;
+} | {
+    type: 'task:scope_overlap';
+    taskId: string;
+    overlappingTaskId: string;
+    patterns: string[];
+} | {
+    type: 'workspace:merge_succeeded';
+    taskId: string;
+    branch: string;
+} | {
+    type: 'workspace:merge_conflict';
+    taskId: string;
+    branch: string;
+    conflictInfo: string;
+} | {
+    type: 'task:orphaned';
+    taskId: string;
+} | {
+    type: 'orchestrator:error';
+    error: string;
+    context: string;
+    fatal: boolean;
+} | {
+    type: 'orchestrator:shutdown';
+    reason: string;
+} | {
+    type: 'message:sent';
+    messageId: string;
+    fromAgentId: string;
+    toAgentId: string | null;
+    channel: MessageChannel;
+} | {
+    type: 'message:delivered';
+    messageId: string;
+    toAgentId: string;
+    taskId: string;
+} | {
+    type: 'team:created';
+    teamId: string;
+    name: string;
+    leadAgentId: string;
+} | {
+    type: 'team:member_joined';
+    teamId: string;
+    agentId: string;
+} | {
+    type: 'team:member_left';
+    teamId: string;
+    agentId: string;
+} | {
+    type: 'team:task_claimed';
+    teamId: string;
+    taskId: string;
+    agentId: string;
+} | {
+    type: 'team:disbanded';
+    teamId: string;
+} | {
+    type: 'team:task_added';
+    teamId: string;
+    taskId: string;
+} | {
+    type: 'agent:autonomous_toggled';
+    agentId: string;
+    autonomous: boolean;
+} | {
+    type: 'goal:created';
+    goalId: string;
+    title: string;
+} | {
+    type: 'goal:status_changed';
+    goalId: string;
+    from: GoalStatus;
+    to: GoalStatus;
+} | {
+    type: 'goal:updated';
+    goalId: string;
+} | {
+    type: 'goal:deleted';
+    goalId: string;
+};
+type OrchestratorEventType = OrchestratorEvent['type'];
+/**
+ * Extract event payload by type discriminator.
+ */
+type EventPayload<T extends OrchestratorEventType> = Extract<OrchestratorEvent, {
+    type: T;
+}>;
+
+/**
+ * Typed error hierarchy for the orchestrator.
+ *
+ * Every error carries an exit code (matching CLI_UI_DESIGN.md §11)
+ * and an optional hint for the user.
+ *
+ * Exit codes:
+ *   0 - Success
+ *   1 - General error
+ *   2 - Invalid arguments
+ *   3 - Not initialized (.orchestry/ not found)
+ *   4 - Lock conflict (orchestrator already running)
+ *   5 - Agent error (adapter test failed)
+ */
+declare class OrchestryError extends Error {
+    readonly exitCode: number;
+    readonly hint?: string | undefined;
+    constructor(message: string, exitCode: number, hint?: string | undefined);
+}
+declare class NotInitializedError extends OrchestryError {
+    constructor();
+}
+declare class TaskNotFoundError extends OrchestryError {
+    constructor(taskId: string);
+}
+declare class AgentNotFoundError extends OrchestryError {
+    constructor(agentId: string);
+}
+
+/**
+ * Task state machine — pure functions, no side effects.
+ *
+ * State diagram:
+ *   todo → in_progress → review → done
+ *                      ↘ retrying → in_progress
+ *                      ↘ failed (max attempts)
+ *   review → todo (rejected)
+ *   * → cancelled
+ *   failed → todo | retrying (manual reactivation)
+ *   cancelled → todo (manual reactivation)
+ *
+ * Terminal statuses (done, failed, cancelled) are not auto-dispatched
+ * by the orchestrator but may have manual outgoing transitions.
+ */
+
+/**
+ * Check if a status transition is valid.
+ */
+declare function canTransition(from: TaskStatus, to: TaskStatus): boolean;
+/**
+ * Check if a task status is terminal — the orchestrator will not
+ * auto-dispatch or retry it. Terminal tasks may still have valid
+ * manual transitions (e.g. cancelled → todo, failed → todo).
+ */
+declare function isTerminal(status: TaskStatus): boolean;
+/**
+ * Check if a task can be dispatched (ready for execution).
+ */
+declare function isDispatchable(status: TaskStatus): boolean;
+/**
+ * Check if a task is blocked by unfinished dependencies.
+ */
+declare function isBlocked(task: Task, allTasks: Task[]): boolean;
+/**
+ * Determine the next status after a task failure (run error or shutdown).
+ * Returns 'retrying' if attempts remain, 'failed' otherwise.
+ */
+declare function resolveFailureStatus(task: Task): TaskStatus;
+
+/**
+ * Typed event bus.
+ *
+ * The single communication channel between all layers.
+ * Synchronous emit — handlers run inline.
+ * TUI, logger, run store, state all subscribe independently.
+ */
+
+type Handler<T> = (event: T) => void;
+declare class EventBus {
+    private handlers;
+    private wildcardHandlers;
+    private maxListeners;
+    private warnedTypes;
+    /**
+     * Set the maximum number of listeners per event type before a warning is emitted.
+     * Helps detect memory leaks from repeated subscriptions in watch mode.
+     */
+    setMaxListeners(n: number): void;
+    getMaxListeners(): number;
+    /**
+     * Get the number of listeners for a specific event type.
+     */
+    listenerCount(type: OrchestratorEventType): number;
+    /**
+     * Subscribe to events of a specific type.
+     * Returns an unsubscribe function.
+     */
+    on<T extends OrchestratorEventType>(type: T, handler: Handler<EventPayload<T>>): () => void;
+    /**
+     * Subscribe to an event type, auto-unsubscribe after first call.
+     */
+    once<T extends OrchestratorEventType>(type: T, handler: Handler<EventPayload<T>>): () => void;
+    /**
+     * Unsubscribe a handler from an event type.
+     */
+    off<T extends OrchestratorEventType>(type: T, handler: Handler<EventPayload<T>>): void;
+    /**
+     * Emit an event synchronously to all subscribed handlers.
+     */
+    emit(event: OrchestratorEvent): void;
+    private dispatchToSet;
+    /**
+     * Subscribe to ALL events regardless of type.
+     */
+    onAny(handler: Handler<OrchestratorEvent>): () => void;
+    /**
+     * Remove all handlers.
+     */
+    clear(): void;
+}
+
+/**
+ * Team domain model.
+ *
+ * A Team groups agents with a lead for coordinated work.
+ * Teams share a task pool and enable broadcast messaging.
+ */
+type TeamStatus = 'active' | 'paused' | 'disbanded';
+interface TeamMember {
+    agent_id: string;
+    role: 'lead' | 'member';
+    joined_at: string;
+}
+interface Team {
+    id: string;
+    name: string;
+    description?: string;
+    status: TeamStatus;
+    members: TeamMember[];
+    task_pool: string[];
+    lead_agent_id: string;
+    created_at: string;
+    updated_at: string;
+    config: TeamConfig;
+}
+interface TeamConfig {
+    max_concurrent_tasks?: number;
+    auto_claim: boolean;
+    message_ttl_ms?: number;
+}
+interface CreateTeamInput {
+    name: string;
+    description?: string;
+    lead_agent_id: string;
+    member_agent_ids?: string[];
+    config?: Partial<TeamConfig>;
+}
+
+/**
+ * Storage layer interfaces.
+ *
+ * All persistence goes through these contracts.
+ * Implementations use atomic file writes (temp → rename).
+ * Services depend on interfaces, not concrete stores.
+ */
+
+interface ITaskStore {
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    get(id: string): Promise<Task | null>;
+    save(task: Task): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+interface IAgentStore {
+    list(): Promise<Agent[]>;
+    get(id: string): Promise<Agent | null>;
+    getByName(name: string): Promise<Agent | null>;
+    save(agent: Agent): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+interface IRunStore {
+    save(run: Run): Promise<void>;
+    get(id: string): Promise<Run | null>;
+    listAll(): Promise<Run[]>;
+    listForTask(taskId: string): Promise<Run[]>;
+    listForAgent(agentId: string): Promise<Run[]>;
+    appendEvent(runId: string, event: RunEvent): Promise<void>;
+    readEvents(runId: string): Promise<RunEvent[]>;
+    readEventsTail(runId: string, count: number): Promise<RunEvent[]>;
+    streamEvents(runId: string, signal?: AbortSignal): AsyncGenerator<RunEvent>;
+}
+interface IStateStore {
+    read(): Promise<OrchestratorState>;
+    write(state: OrchestratorState): Promise<void>;
+}
+interface IConfigStore {
+    read(): Promise<OrchestratorConfig>;
+    write(config: OrchestratorConfig): Promise<void>;
+    get(keyPath: string): Promise<unknown>;
+    set(keyPath: string, value: unknown): Promise<void>;
+}
+interface ContextEntry {
+    key: string;
+    value: string;
+    created_at: string;
+    updated_at: string;
+    ttl_ms?: number;
+    expires_at?: string;
+}
+interface IContextStore {
+    get(key: string): Promise<ContextEntry | null>;
+    set(key: string, value: string, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(): Promise<ContextEntry[]>;
+    getAll(): Promise<Record<string, string>>;
+}
+interface IMessageStore {
+    save(message: Message): Promise<void>;
+    get(id: string): Promise<Message | null>;
+    list(): Promise<Message[]>;
+    listPending(agentId: string): Promise<Message[]>;
+    markDelivered(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    purgeExpired(): Promise<number>;
+}
+interface IGoalStore {
+    list(filter?: {
+        status?: GoalStatus;
+    }): Promise<Goal[]>;
+    get(id: string): Promise<Goal | null>;
+    save(goal: Goal): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+interface ITeamStore {
+    save(team: Team): Promise<void>;
+    get(id: string): Promise<Team | null>;
+    getByName(name: string): Promise<Team | null>;
+    list(): Promise<Team[]>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Task service — business logic for task lifecycle.
+ *
+ * Validates state transitions, emits events, manages CRUD.
+ * CLI commands call this service, not storage directly.
+ */
+
+declare class TaskService {
+    private readonly taskStore;
+    private readonly eventBus;
+    private readonly config;
+    constructor(taskStore: ITaskStore, eventBus: EventBus, config: OrchestratorConfig);
+    create(input: CreateTaskInput): Promise<Task>;
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    get(id: string): Promise<Task>;
+    updateStatus(id: string, newStatus: TaskStatus): Promise<Task>;
+    assign(taskId: string, agentId: string): Promise<Task>;
+    cancel(id: string): Promise<Task>;
+    retry(id: string): Promise<Task>;
+    reject(id: string, feedback?: string): Promise<Task>;
+    update(id: string, fields: {
+        title?: string;
+        description?: string;
+        priority?: number;
+        labels?: string[];
+    }): Promise<Task>;
+    delete(id: string): Promise<void>;
+    incrementAttempts(id: string): Promise<Task>;
+}
+
+/**
+ * Agent service — business logic for agent lifecycle.
+ *
+ * Manages agent CRUD, availability, and task assignment matching.
+ */
+
+declare class AgentService {
+    private readonly agentStore;
+    private readonly stateStore;
+    private readonly eventBus;
+    private readonly config;
+    constructor(agentStore: IAgentStore, stateStore: IStateStore, eventBus: EventBus, config: OrchestratorConfig);
+    create(input: CreateAgentInput): Promise<Agent>;
+    list(): Promise<Agent[]>;
+    get(id: string): Promise<Agent>;
+    remove(id: string): Promise<void>;
+    update(id: string, fields: {
+        name?: string;
+        role?: string;
+        model?: string;
+        approval_policy?: Agent['config']['approval_policy'];
+    }): Promise<Agent>;
+    disable(id: string): Promise<Agent>;
+    enable(id: string): Promise<Agent>;
+    setAutonomous(id: string, enabled: boolean): Promise<Agent>;
+    setStatus(id: string, status: AgentStatus): Promise<Agent>;
+    updateStats(id: string, update: Partial<Agent['stats']>): Promise<Agent>;
+    /**
+     * Find the best available agent for a task using scoring.
+     *
+     * Scoring:
+     * - Explicit assignee match = 100
+     * - Skill match with task labels = 50 per match
+     * - Role match with task labels = 30
+     * - Idle status bonus = 20
+     * - Success rate bonus = 0–10 (scaled by completed / total)
+     */
+    findBestAgent(task: Task): Promise<Agent | null>;
+}
+
+/**
+ * Run service — manages run lifecycle and event streaming.
+ */
+
+declare class RunService {
+    private readonly runStore;
+    private readonly eventBus;
+    constructor(runStore: IRunStore, eventBus: EventBus);
+    create(params: {
+        taskId: string;
+        agentId: string;
+        attempt: number;
+        prompt: string;
+        workspacePath: string;
+    }): Promise<Run>;
+    get(id: string): Promise<Run | null>;
+    start(id: string, pid: number): Promise<Run>;
+    finish(id: string, status: RunStatus, tokens?: TokenUsage, error?: string): Promise<Run>;
+    appendEvent(runId: string, event: RunEvent): Promise<void>;
+    listAll(): Promise<Run[]>;
+    listForTask(taskId: string): Promise<Run[]>;
+    listForAgent(agentId: string): Promise<Run[]>;
+    readEvents(runId: string): Promise<RunEvent[]>;
+    readEventsTail(runId: string, count: number): Promise<RunEvent[]>;
+    /**
+     * Get error and last N lines of output from the most recent failed run for a task.
+     * Used to provide retry context so agents can learn from previous failures.
+     */
+    getLastFailedRunContext(taskId: string, maxOutputLines?: number): Promise<{
+        error: string;
+        output: string;
+    } | null>;
+}
+
+/**
+ * MessageService — business logic for inter-agent messaging.
+ *
+ * Handles message creation, routing (direct/broadcast/lead),
+ * delivery into agent prompts, and cleanup of expired messages.
+ */
+
+declare class MessageService {
+    private readonly messageStore;
+    private readonly agentStore;
+    private readonly teamStore;
+    private readonly eventBus;
+    constructor(messageStore: IMessageStore, agentStore: IAgentStore, teamStore: ITeamStore, eventBus: EventBus);
+    /**
+     * Send a message. For broadcast, creates one message per recipient agent.
+     * For 'lead' channel, resolves team lead and sends direct.
+     */
+    send(input: CreateMessageInput): Promise<Message[]>;
+    /**
+     * Drain mailbox: fetch pending messages for an agent and mark them delivered.
+     * Called by the orchestrator during dispatchTask.
+     */
+    drainMailbox(agentId: string, taskId: string): Promise<Message[]>;
+    listAll(): Promise<Message[]>;
+    listPendingForAgent(agentId: string): Promise<Message[]>;
+    listForAgent(agentId: string): Promise<Message[]>;
+    purgeExpired(): Promise<number>;
+    private emitSent;
+}
+
+/**
+ * Agent adapter interface.
+ *
+ * Every AI tool (Claude, Codex, Shell, etc.) implements this contract.
+ * execute() returns an AsyncGenerator for pull-based streaming of events.
+ */
+
+interface AdapterTestResult {
+    ok: boolean;
+    version?: string;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+interface ExecuteParams {
+    prompt: string;
+    workspace: string;
+    env?: Record<string, string>;
+    config: AgentConfig;
+    signal?: AbortSignal;
+}
+interface AgentEvent {
+    type: 'output' | 'file_change' | 'command' | 'tool_call' | 'error' | 'done';
+    timestamp: string;
+    data: unknown;
+    tokens?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}
+interface ExecuteHandle {
+    pid: number;
+    events: AsyncGenerator<AgentEvent>;
+}
+interface IAgentAdapter {
+    readonly kind: string;
+    test(): Promise<AdapterTestResult>;
+    execute(params: ExecuteParams): ExecuteHandle;
+    stop(pid: number): Promise<void>;
+}
+
+/**
+ * Adapter registry.
+ *
+ * Maps adapter kind strings to adapter instances.
+ * Pre-populated at startup in the container.
+ */
+
+declare class AdapterRegistry {
+    private readonly adapters;
+    register(adapter: IAgentAdapter): void;
+    get(kind: string): IAgentAdapter | undefined;
+    require(kind: string): IAgentAdapter;
+    list(): IAgentAdapter[];
+    listKinds(): string[];
+    has(kind: string): boolean;
+}
+
+/**
+ * Process management utilities.
+ *
+ * Handles spawning subprocesses, PID checks, graceful kill.
+ */
+
+interface SpawnResult {
+    process: ChildProcess;
+    pid: number;
+}
+interface IProcessManager {
+    isAlive(pid: number): boolean;
+    kill(pid: number, signal?: NodeJS.Signals): void;
+    killWithGrace(pid: number, graceMs?: number): Promise<void>;
+    spawn(command: string, args: string[], options?: SpawnOptions): SpawnResult;
+}
+
+/**
+ * Git merge strategy for worktree branches.
+ *
+ * Encapsulates `git merge --no-ff` execution and conflict handling.
+ */
+
+type MergeResult = {
+    success: true;
+} | {
+    success: false;
+    conflictInfo: string;
+};
+
+/**
+ * Workspace manager interface.
+ */
+
+interface PrepareResult {
+    path: string;
+    branch?: string;
+}
+interface IWorkspaceManager {
+    prepare(task: Task, agent: Agent, config: OrchestratorConfig): Promise<PrepareResult>;
+    mergeBack(branch: string): Promise<MergeResult>;
+    cleanup(taskId: string): Promise<void>;
+    validate(workspacePath: string, projectRoot: string): void;
+}
+
+interface ITemplateEngine {
+    render(template: string, context: PromptContext): Promise<string>;
+}
+interface AgentInfo {
+    id: string;
+    name: string;
+    role?: string;
+    adapter: string;
+}
+interface RetryContext {
+    previous_error: string;
+    previous_output: string;
+}
+interface PromptContext {
+    project: {
+        name: string;
+        description?: string;
+    };
+    task: {
+        id: string;
+        title: string;
+        description: string;
+        priority: number;
+        labels: string[];
+        scope?: string[];
+        is_autonomous: boolean;
+    };
+    agent: {
+        id: string;
+        name: string;
+        role?: string;
+    };
+    agents: AgentInfo[];
+    attempt: number | null;
+    workspace_path: string;
+    retry?: RetryContext;
+    feedback?: string;
+    shared_context?: Record<string, string>;
+    messages?: Array<{
+        id: string;
+        from: string;
+        subject: string;
+        body: string;
+        sent_at: string;
+        reply_to?: string;
+    }>;
+}
+
+interface OrchestratorDeps {
+    taskStore: ITaskStore;
+    agentStore: IAgentStore;
+    runStore: IRunStore;
+    stateStore: IStateStore;
+    adapterRegistry: AdapterRegistry;
+    workspaceManager: IWorkspaceManager;
+    templateEngine: ITemplateEngine;
+    processManager: IProcessManager;
+    eventBus: EventBus;
+    taskService: TaskService;
+    agentService: AgentService;
+    runService: RunService;
+    contextStore?: IContextStore;
+    messageService?: MessageService;
+    goalStore?: IGoalStore;
+    config: OrchestratorConfig;
+    projectRoot: string;
+    lockPath: string;
+}
+declare class Orchestrator {
+    private readonly deps;
+    private intervalId;
+    private shuttingDown;
+    private state;
+    private abortControllers;
+    private readonly cachedTaskStore;
+    private readonly cachedAgentStore;
+    private readonly cachedGoalStore;
+    private saveStateTimer;
+    private saveStateDirty;
+    private lockAcquired;
+    private consecutiveTickFailures;
+    private readonly maxConsecutiveTickFailures;
+    private readonly maxRetryQueueSize;
+    private signalHandlers;
+    private immediateDispatchTimer;
+    private taskCreatedUnsub;
+    private tickInProgress;
+    /** Promise-chain mutex to serialize critical state mutations. */
+    private stateMutex;
+    constructor(deps: OrchestratorDeps);
+    /**
+     * Check if this instance owns the lock (can mutate state).
+     */
+    get isOwner(): boolean;
+    /**
+     * Serialize access to state mutations via a Promise-chain mutex.
+     * Prevents concurrent tick/stop/reconcile from reading stale state.
+     */
+    private withStateLock;
+    /**
+     * Run a single task by ID. Acquires lock for the duration of the run.
+     */
+    runTask(taskId: string): Promise<void>;
+    /**
+     * Run all dispatchable tasks. Acquires lock for the duration of the run.
+     */
+    runAll(): Promise<void>;
+    /**
+     * Acquire lock, run fn, then release lock.
+     * Used by single-shot commands (runTask, runAll) that don't go through startWatch.
+     */
+    private withTemporaryLock;
+    /**
+     * Start watch mode — continuous tick loop.
+     * Acquires a PID lock to prevent multiple orchestrators.
+     */
+    startWatch(): Promise<void>;
+    /**
+     * Register SIGINT/SIGTERM handlers for graceful shutdown.
+     */
+    private registerSignalHandlers;
+    /**
+     * Remove signal handlers to avoid listener leaks.
+     */
+    private removeSignalHandlers;
+    /**
+     * Stop the watch loop and clean up.
+     */
+    stop(): Promise<void>;
+    /**
+     * Cancel a running task: kill agent process, clean state, mark cancelled.
+     * Acquires lock if not already owned (standalone CLI invocation).
+     */
+    cancelTask(taskId: string): Promise<void>;
+    /**
+     * Force-stop a specific agent: kill process, clean state, release agent.
+     * Acquires lock if not already owned (standalone CLI invocation).
+     */
+    forceStopAgent(agentId: string): Promise<void>;
+    /**
+     * Single tick: Reconcile → Dispatch → Collect
+     * Serialized via mutex to prevent concurrent ticks from racing on state.
+     */
+    private tick;
+    /**
+     * Schedule an immediate dispatch with 500ms debounce.
+     * Called on task:created to avoid waiting for the next 30s tick.
+     */
+    private scheduleImmediateDispatch;
+    /**
+     * Mini-tick: invalidate caches → loadState → dispatchAll → saveState.
+     * Skips reconcile/collect — only dispatches new tasks immediately.
+     */
+    private immediateDispatch;
+    /**
+     * Reconcile: check PID liveness, detect stalls, process retry queue.
+     */
+    private reconcile;
+    /**
+     * Create tasks for autonomous agents that have no active work.
+     *
+     * Priority: active Goals assigned to the agent come first.
+     * If no goals, falls back to role-based autonomous work.
+     */
+    private seedAutonomousTasks;
+    /**
+     * Dispatch all dispatchable tasks up to max_concurrent_agents.
+     */
+    private dispatchAll;
+    /**
+     * Dispatch a single task: claim → assign → execute.
+     */
+    private dispatchTask;
+    /**
+     * Collect events from an adapter's async generator.
+     */
+    private collectEvents;
+    private handleRunSuccess;
+    private _handleRunSuccess;
+    private handleRunFailure;
+    private _handleRunFailure;
+    /**
+     * Run automatic review criteria on a task in 'review' status.
+     * If all criteria pass, transition review → done.
+     * If any fail, stay in review with results attached.
+     */
+    private runAutoReview;
+    /**
+     * Force a task to 'review' status with a summary prefix.
+     * Used when merge-back fails (conflict or infrastructure error).
+     */
+    private forceTaskToReview;
+    private unclaim;
+    /**
+     * Throw if this instance doesn't own the lock (read-only session).
+     */
+    private requireOwnership;
+    private loadState;
+    private saveState;
+    /**
+     * Debounced saveState — batches rapid writes within 500ms window.
+     * Used for non-critical updates like last_event_at in collectEvents.
+     */
+    private saveStateLazy;
+    /**
+     * Flush any pending debounced saveState immediately.
+     * Call before critical transitions to ensure state is persisted.
+     */
+    private flushStateLazy;
+}
+
+/**
+ * CLI context — resolved project root and global flags.
+ *
+ * Validated at entry point before any command runs.
+ */
+interface CliContext {
+    projectRoot: string;
+    json: boolean;
+    quiet: boolean;
+    noColor: boolean;
+    ascii: boolean;
+}
+
+/**
+ * Global configuration — persists across projects.
+ *
+ * Stored at ~/.orchestry/global.yml
+ */
+/** Activity feed filter preset name */
+type ActivityFilterPreset = 'all' | 'text' | 'tools' | 'errors' | 'events';
+interface TuiPreferences {
+    activity_filter: ActivityFilterPreset;
+}
+interface GlobalConfig {
+    tui: TuiPreferences;
+}
+
+/**
+ * Path resolution for .orchestry/ directory.
+ *
+ * All path construction goes through this module.
+ * Validates initialization state and sanitizes identifiers.
+ */
+declare class Paths {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    /** Root .orchestry/ directory */
+    get root(): string;
+    get configPath(): string;
+    get statePath(): string;
+    get lockPath(): string;
+    get tasksDir(): string;
+    get agentsDir(): string;
+    get runsDir(): string;
+    get templatesDir(): string;
+    get logsDir(): string;
+    get contextDir(): string;
+    contextPath(key: string): string;
+    get messagesDir(): string;
+    messagePath(id: string): string;
+    get goalsDir(): string;
+    goalPath(id: string): string;
+    get teamsDir(): string;
+    teamPath(id: string): string;
+    get gitignorePath(): string;
+    get workspaceExcludePath(): string;
+    taskPath(id: string): string;
+    agentPath(id: string): string;
+    runPath(id: string): string;
+    runEventsPath(id: string): string;
+    defaultTemplatePath(): string;
+    isInitialized(): Promise<boolean>;
+    requireInit(): Promise<void>;
+}
+
+/**
+ * Global config store — reads/writes ~/.orchestry/global.yml
+ *
+ * Persists across projects. Creates directory if needed.
+ */
+
+declare class GlobalConfigStore {
+    read(): Promise<GlobalConfig>;
+    write(config: GlobalConfig): Promise<void>;
+    set<K extends keyof GlobalConfig['tui']>(key: K, value: GlobalConfig['tui'][K]): Promise<void>;
+}
+
+/**
+ * Goal service — business logic for goal lifecycle.
+ *
+ * Goals are persistent objectives that drive autonomous agent work.
+ * State machine: active → achieved | abandoned
+ *                active ↔ paused
+ *
+ * Side effect: assigning an agent to a goal auto-enables autonomous mode;
+ * removing the last active goal from an agent auto-disables it.
+ */
+
+declare class GoalService {
+    private readonly goalStore;
+    private readonly eventBus;
+    private readonly agentService?;
+    private readonly taskService?;
+    constructor(goalStore: IGoalStore, eventBus: EventBus, agentService?: AgentService | undefined, taskService?: TaskService | undefined);
+    create(input: CreateGoalInput): Promise<Goal>;
+    list(filter?: {
+        status?: GoalStatus;
+    }): Promise<Goal[]>;
+    get(id: string): Promise<Goal>;
+    updateStatus(id: string, newStatus: GoalStatus): Promise<Goal>;
+    update(id: string, fields: {
+        title?: string;
+        description?: string;
+        assignee?: string;
+    }): Promise<Goal>;
+    delete(id: string): Promise<void>;
+    /** Enable autonomous mode on an agent. */
+    private enableAutonomous;
+    /** Check if an agent has at least one active goal. */
+    private hasActiveGoalsForAgent;
+    /** Cancel dispatchable (todo/retrying) autonomous tasks assigned to the agent. */
+    private cancelPendingAutonomousTasks;
+    /** Disable autonomous if agent has no other active goals. */
+    private maybeDisableAutonomous;
+}
+
+/**
+ * TeamService — business logic for team lifecycle.
+ *
+ * Manages team creation, membership, task pool, and self-claiming.
+ */
+
+declare class TeamService {
+    private readonly teamStore;
+    private readonly agentStore;
+    private readonly taskStore;
+    private readonly eventBus;
+    constructor(teamStore: ITeamStore, agentStore: IAgentStore, taskStore: ITaskStore, eventBus: EventBus);
+    create(input: CreateTeamInput): Promise<Team>;
+    get(id: string): Promise<Team>;
+    list(): Promise<Team[]>;
+    join(teamId: string, agentId: string): Promise<Team>;
+    leave(teamId: string, agentId: string): Promise<Team>;
+    addTask(teamId: string, taskId: string): Promise<Team>;
+    removeTask(teamId: string, taskId: string): Promise<Team>;
+    setLead(teamId: string, agentId: string): Promise<Team>;
+    disband(teamId: string): Promise<void>;
+    /**
+     * Find the team an agent belongs to (if any).
+     */
+    findTeamForAgent(agentId: string): Promise<Team | null>;
+}
+
+/**
+ * Doctor service — diagnostics and health checks.
+ *
+ * Checks adapter availability, system dependencies, project state.
+ */
+
+interface DoctorCheck {
+    name: string;
+    status: 'ok' | 'fail' | 'skip';
+    detail?: string;
+}
+interface DoctorReport {
+    checks: DoctorCheck[];
+    adaptersReady: number;
+    adaptersTotal: number;
+}
+declare class DoctorService {
+    private readonly adapterRegistry;
+    private readonly processManager;
+    constructor(adapterRegistry: AdapterRegistry, processManager: IProcessManager);
+    runAll(): Promise<DoctorReport>;
+    private checkCommand;
+}
+
+/**
+ * Dependency injection container.
+ *
+ * Plain TypeScript object — no framework, no decorators.
+ * Two modes:
+ *   - LightContainer: stores + services only (fast, for read-only commands)
+ *   - Container: full (+ orchestrator, adapters, template engine)
+ */
+
+/** Light container — stores + services. No heavy deps (adapters, orchestrator, LiquidJS). */
+interface LightContainer {
+    context: CliContext;
+    paths: Paths;
+    config: OrchestratorConfig;
+    taskStore: ITaskStore;
+    agentStore: IAgentStore;
+    runStore: IRunStore;
+    stateStore: IStateStore;
+    configStore: IConfigStore;
+    globalConfigStore: GlobalConfigStore;
+    globalConfig: GlobalConfig;
+    contextStore: IContextStore;
+    messageStore: IMessageStore;
+    goalStore: IGoalStore;
+    teamStore: ITeamStore;
+    eventBus: EventBus;
+    taskService: TaskService;
+    agentService: AgentService;
+    runService: RunService;
+    messageService: MessageService;
+    goalService: GoalService;
+    teamService: TeamService;
+}
+/** Full container — everything from light + orchestrator, adapters, workspace, template. */
+interface Container extends LightContainer {
+    processManager: IProcessManager;
+    adapterRegistry: AdapterRegistry;
+    workspaceManager: IWorkspaceManager;
+    templateEngine: ITemplateEngine;
+    doctorService: DoctorService;
+    orchestrator: Orchestrator;
+}
+/**
+ * Build a light container (stores + services).
+ * Fast — no ProcessManager, no adapters, no LiquidJS, no Orchestrator.
+ * Used by read-only commands: task, agent, context, msg, goal, team, logs, status, config.
+ */
+declare function buildLightContainer(context: CliContext): Promise<LightContainer>;
+/**
+ * Build a full container (light + orchestrator + adapters + template).
+ * Used by: run, tui, doctor.
+ */
+declare function buildFullContainer(context: CliContext): Promise<Container>;
+/**
+ * @deprecated Use buildLightContainer or buildFullContainer directly.
+ * Kept for backward compatibility with tests.
+ */
+declare function buildContainer(context: CliContext): Promise<Container>;
+
+export { AdapterRegistry, type AdapterTestResult, type Agent, type AgentConfig, type AgentEvent, AgentNotFoundError, AgentService, type AgentStats, type AgentStatus, type ApprovalPolicy, type Container, type CreateAgentInput, type CreateTaskInput, EventBus, type EventPayload, type ExecuteParams, type IAgentAdapter, type LightContainer, NotInitializedError, Orchestrator, type OrchestratorConfig, type OrchestratorEvent, type OrchestratorEventType, type OrchestratorState, OrchestryError, type ProjectConfig, type RetryEntry, type Run, type RunEvent, type RunEventType, RunService, type RunStatus, type RunningEntry, type SchedulingConfig, type Task, TaskNotFoundError, type TaskProof, TaskService, type TaskStatus, type TokenUsage, type WorkspaceMode, buildContainer, buildFullContainer, buildLightContainer, canTransition, createTokenUsage, isBlocked, isDispatchable, isTerminal, resolveFailureStatus };