@hilbras/omninode 2.0.0-alpha.1 → 2.0.0-alpha.11

package/dist/index.d.ts

@@ -1,29 +1,75 @@
 import { z } from 'zod';
+import { ChildProcess } from 'node:child_process';
 
 /** Structured report format so reports can be processed programmatically (§16). */
 type Confidence = "low" | "medium" | "high";
 type FindingSeverity = "info" | "low" | "medium" | "high" | "critical";
+/** Typed evidence (roadmap §13, Evidence). Plain strings remain accepted
+ *  and normalize to `observation` evidence. */
+type EvidenceKind = "file" | "line" | "url" | "command" | "observation" | "artifact";
+interface Evidence {
+    kind: EvidenceKind;
+    /** Path, URL, command or logical reference. */
+    ref?: string;
+    /** Line number for file/line evidence. */
+    line?: number;
+    /** Verbatim excerpt backing the finding. */
+    excerpt?: string;
+    /** Agent that produced the evidence. */
+    agent?: string;
+}
+type EvidenceInput = string | Evidence;
+/** Artifact produced alongside a report (§13). */
+interface ReportArtifact {
+    kind: "file" | "patch" | "log" | "screenshot" | "document" | "data";
+    ref: string;
+    description?: string;
+    mediaType?: string;
+    bytes?: number;
+}
+/** Where a finding came from, when known. */
+interface FindingOrigin {
+    agent?: string;
+    reportId?: string;
+    pipelineRunId?: string;
+}
 interface Finding {
     id: string;
     title: string;
+    /** v1 field, kept for compatibility; `description` is the v2 field. */
     detail: string;
+    /** Full description of the finding (§13, Findings). */
+    description?: string;
     severity?: FindingSeverity;
-    evidence?: string[];
+    confidence?: Confidence;
+    evidence?: EvidenceInput[];
     /** File path or conceptual location the finding refers to. */
     location?: string;
     tags?: string[];
+    /** Provenance of the finding, when known (§13). */
+    source?: FindingOrigin;
+    /** The concrete fix this finding implies. */
+    recommendation?: string;
 }
 interface Report {
     id: string;
     taskId: string;
     /** Agent name from the agent registry. */
     agent: string;
+    /** v2 spelling of `agent` for machine consumers (§13). */
+    agentId?: string;
+    /** Pipeline run that produced this report, when applicable. */
+    pipelineRunId?: string;
     /** Model id used, if known. */
     model?: string;
     summary: string;
     findings: Finding[];
     recommendations: string[];
     confidence?: Confidence;
+    /** Report-level evidence backing the summary. */
+    evidence?: EvidenceInput[];
+    /** Artifacts produced with the report (§13, Artifacts). */
+    artifacts?: ReportArtifact[];
     createdAt: string;
     metadata?: Record<string, unknown>;
 }
@@ -41,7 +87,31 @@ interface AggregatedFinding {
     occurrences: number;
     /** Highest severity seen across merged duplicates. */
     severity?: FindingSeverity;
-    evidence: string[];
+    /** Highest confidence seen across merged duplicates (§14 — confidence preservation). */
+    confidence?: Confidence;
+    /** Per-agent severity, so a disagreement is visible rather than flattened. */
+    severityBySource?: Record<string, FindingSeverity>;
+    /** Per-agent confidence. */
+    confidenceBySource?: Record<string, Confidence>;
+    /** Distinct recommendations attached to this finding across reports. */
+    recommendations?: string[];
+    /** Typed evidence, normalized from strings when reports were ingested. */
+    evidence: Evidence[];
+}
+/** One agent's position on a disputed finding (§14, Conflicts). */
+interface ConflictPosition {
+    agent: string;
+    reportId: string;
+    severity?: FindingSeverity;
+    confidence?: Confidence;
+    recommendation?: string;
+}
+interface ReportConflict {
+    type: "severity" | "recommendation";
+    findingTitle: string;
+    /** Both positions are preserved — OmniNode never silently chooses one. */
+    positions: ConflictPosition[];
+    note: string;
 }
 interface AggregatedRecommendation {
     text: string;
@@ -57,6 +127,10 @@ interface CombinedReport {
     taskIds: string[];
     summary: string;
     findings: AggregatedFinding[];
+    /** Findings multiple agents reported with the same severity (consensus). */
+    agreements: AggregatedFinding[];
+    /** Disagreements between agents (§14) — both positions preserved. */
+    conflicts: ReportConflict[];
     recommendations: AggregatedRecommendation[];
     /** Distinct agent names that contributed. */
     sources: string[];
@@ -65,6 +139,99 @@ interface CombinedReport {
     metadata?: Record<string, unknown>;
 }
 
+/**
+ * OmniNode Agent Protocol v2 — message model (roadmap §7.2–§7.4, §7.7).
+ *
+ * Every message is a JSON line carrying a `ProtocolEnvelope`. All ids are
+ * optional for inbound tolerance but OmniNode always emits them, so every
+ * message is traceable to agent / task / pipeline / execution / request.
+ */
+
+/** Messages OmniNode sends to an agent. */
+type ProtocolNodeToAgentType = "TASK" | "HELLO_ACK" | "CONTEXT" | "INSTRUCTION" | "RESPONSE" | "CANCEL";
+/** Messages an agent sends to OmniNode. */
+type ProtocolAgentToNodeType = "HELLO" | "TASK_REQUEST" | "TASK_ACCEPTED" | "TASK_STARTED" | "STATUS" | "QUESTION" | "REPORT" | "ARTIFACT" | "COMPLETION" | "ERROR" | "CANCELLED";
+type ProtocolMessageType = ProtocolNodeToAgentType | ProtocolAgentToNodeType;
+interface ProtocolEnvelope<T extends ProtocolMessageType = ProtocolMessageType> {
+    /** `omninode-agent-protocol/2`. Inbound messages without it are treated as v1. */
+    protocol: string;
+    /** Unique id of this message. */
+    messageId: string;
+    /** Id of the request/thread this message belongs to. */
+    requestId?: string;
+    taskId?: string;
+    agentId?: string;
+    pipelineId?: string;
+    /** Execution identity (roadmap §6.5) — ties the message to one attempt. */
+    executionId?: string;
+    timestamp: string;
+    type: T;
+    payload: unknown;
+    metadata?: Record<string, unknown>;
+}
+/** Standard artifact kinds (roadmap §7.7). */
+type ArtifactKind = "file" | "patch" | "report" | "log" | "screenshot" | "document" | "data";
+interface ArtifactPayload {
+    kind: ArtifactKind;
+    /** Path, URL or logical name. */
+    ref: string;
+    description?: string;
+    mediaType?: string;
+    bytes?: number;
+    metadata?: Record<string, unknown>;
+}
+interface QuestionPayload {
+    /** Question id to answer. */
+    questionId: string;
+    question: string;
+    /** What kind of answer is expected (free text, file path, options…). */
+    expected?: "text" | "path" | "choice";
+    options?: string[];
+}
+interface TaskPayload {
+    taskId: string;
+    objective: string;
+}
+interface ReportPayload {
+    report: Report | Report[];
+}
+/** A question an agent asked during a run, with the answer OmniNode gave (if any). */
+interface AskedQuestion {
+    questionId: string;
+    question: string;
+    answer?: string;
+}
+declare function newMessageId(prefix?: string): string;
+/** Builds a v2 envelope with ids and timestamp filled in. */
+declare function envelope<T extends ProtocolMessageType>(type: T, payload: unknown, ids?: {
+    requestId?: string;
+    taskId?: string;
+    agentId?: string;
+    pipelineId?: string;
+    executionId?: string;
+    metadata?: Record<string, unknown>;
+}): ProtocolEnvelope<T>;
+
+interface AgentDescriptor {
+    /** Protocol the agent speaks. */
+    protocol: string;
+    name: string;
+    version?: string;
+    capabilities: string[];
+    /** Message types the agent can emit. */
+    supports: string[];
+}
+type HelloResult = {
+    ok: true;
+    descriptor: AgentDescriptor;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function parseHello(envelopeValue: ProtocolEnvelope): HelloResult;
+declare function buildHello(descriptor: Omit<AgentDescriptor, "protocol">): ProtocolEnvelope<"HELLO">;
+declare function buildHelloAck(descriptor: AgentDescriptor): ProtocolEnvelope<"HELLO_ACK">;
+
 /** Role system: what an AI is supposed to do, independent of any provider (§11). */
 interface RoleDefinition {
     /** Slug identifier, e.g. "architecture-reviewer". */
@@ -98,8 +265,21 @@ interface AgentConfig {
     inputMode?: AgentInputMode;
     /** Per-task timeout in milliseconds; the process is killed when exceeded. */
     timeoutMs?: number;
-    /** When false, the agent process starts with a minimal environment (PATH + env). */
+    /**
+     * When false, the agent process starts with a minimal environment (PATH +
+     * env). Deprecated in v2 — prefer `envPolicy`.
+     */
     inheritEnv?: boolean;
+    /** Explicit environment policy (roadmap §8). */
+    envPolicy?: "inherit" | "allowlist" | "denylist" | "explicit";
+    /** Variables forwarded from the parent under the `allowlist` policy. */
+    envAllowlist?: string[];
+    /** Variables removed from the parent under the `denylist` policy. */
+    envDenylist?: string[];
+    /** Per-stream byte budget for agent stdout/stderr (default 5 MiB). */
+    maxOutputBytes?: number;
+    /** Allow a working directory outside the project root. */
+    allowExternalCwd?: boolean;
     /** Models (as "provider:model-id") this agent may use, if restricted. */
     allowedModels?: string[];
     metadata?: Record<string, unknown>;
@@ -117,6 +297,10 @@ interface AgentInfo {
 interface AgentTaskInput {
     taskId: string;
     objective: string;
+    /** Pipeline run that owns this task (protocol correlation, §7.4). */
+    pipelineId?: string;
+    /** Execution identity for this attempt (protocol correlation, §7.4). */
+    executionId?: string;
     role?: RoleDefinition;
     /** Assembled task context (project, memory, files) already selected for this agent. */
     context?: string;
@@ -132,6 +316,14 @@ interface AgentTaskOutput {
     logs?: string[];
     /** Structured reports extracted from protocol-mode runs (§16, §21). */
     reports?: Report[];
+    /** Protocol diagnostics for protocol-mode runs (roadmap §7): questions asked, violations seen. */
+    protocol?: {
+        protocol: string;
+        legacy: boolean;
+        descriptor?: AgentDescriptor;
+        questions: AskedQuestion[];
+        violations: string[];
+    };
     error?: string;
 }
 /** Contract every agent adapter implements (Phase 3+). */
@@ -177,32 +369,73 @@ interface ChatResponse {
  * layer so adapters (e.g. planner) never depend on engine modules.
  */
 type ChatFn = (model: string, messages: ChatMessage[]) => Promise<string>;
+/** One streamed chunk (SSE deltas from OpenAI-compatible gateways). */
+interface ChatStreamChunk {
+    /** Text delta (empty for role-only or final chunks). */
+    delta: string;
+    /** Provider-reported finish reason, on the final chunk. */
+    finishReason?: string;
+    raw?: unknown;
+}
 
 /**
- * Memory abstraction. Remembera is the preferred Hilbras integration, but the
- * core depends only on this interface (memory-agnostic principle, §2, §19).
+ * Memory abstraction (§19). Remembera is the preferred implementation, but
+ * the core depends only on this interface (memory-agnostic principle, §2).
+ *
+ * v2 contract (roadmap §12): retrieve / store / search / metadata, across
+ * project / task / role scopes with structured categories.
  */
-type MemoryScope = "project" | "role" | "task" | "knowledge";
+type MemoryScope = "project" | "task" | "role" | "knowledge";
+/** Structured memory categories (roadmap §12, Memory Categories). */
+type MemoryCategory = "project" | "architecture" | "decisions" | "tasks" | "problems" | "solutions" | "conventions" | "agent_reports";
 interface MemoryEntry {
     key: string;
     scope: MemoryScope;
     content: string;
+    /** Structured category, when the backend supports it. */
+    category?: MemoryCategory;
     tags?: string[];
     createdAt?: string;
     updatedAt?: string;
     metadata?: Record<string, unknown>;
 }
 interface MemoryQuery {
+    /** Free-text relevance query. */
+    text?: string;
     scope?: MemoryScope;
+    category?: MemoryCategory;
     tags?: string[];
-    /** Free-text relevance query; implementations decide ranking. */
-    text?: string;
     limit?: number;
 }
+interface MemoryProviderMetadata {
+    name: string;
+    /** What the backend can do, so callers can adapt (e.g. no category support). */
+    capabilities: Array<"retrieve" | "store" | "search" | "categories" | "tags">;
+    /** True when the backend enforces relevance ranking itself. */
+    relevanceRanking: boolean;
+    /** Backend-specific info (gateway version, endpoint type…). */
+    backend?: Record<string, unknown>;
+}
+/**
+ * The memory contract. `query`/`write` are the v1 names, kept as aliases so
+ * existing integrations keep working — new code should use retrieve/store.
+ */
 interface IMemoryProvider {
     readonly name: string;
-    /** Retrieve relevant memory; only relevant context should reach a task (§20). */
+    /** Retrieve entries relevant to a query (task-oriented). */
+    retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** Store an entry (upsert by key). */
+    store(entry: MemoryEntry): Promise<void>;
+    /** Free-text search across scopes. */
+    search(text: string, options?: {
+        limit?: number;
+        scope?: MemoryScope;
+    }): Promise<MemoryEntry[]>;
+    /** Provider capabilities (contract introspection). */
+    metadata(): MemoryProviderMetadata;
+    /** @deprecated v1 alias of {@link retrieve}. */
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link store}. */
     write(entry: MemoryEntry): Promise<void>;
 }
 
@@ -215,21 +448,52 @@ interface ModelCapabilities {
     embeddings?: boolean;
 }
 type ModelStatus = "available" | "unavailable" | "deprecated";
+type Modality = "text" | "image" | "audio" | "video" | "embedding";
+/** Model metadata (roadmap §10, Model Metadata). */
 interface ModelInfo {
     /** Name of the provider this model belongs to. */
     provider: string;
     /** Provider-specific model identifier, e.g. "qwen3-coder". */
     id: string;
     displayName?: string;
+    /** Human-readable model name reported by the provider, when available. */
+    name?: string;
     capabilities?: ModelCapabilities;
     contextWindow?: number;
+    inputTypes?: Modality[];
+    outputTypes?: Modality[];
+    supportsTools?: boolean;
+    supportsVision?: boolean;
+    supportsReasoning?: boolean;
+    supportsStructuredOutput?: boolean;
+    supportsStreaming?: boolean;
     status?: ModelStatus;
     metadata?: Record<string, unknown>;
 }
 
 /** Task system: every operation becomes a Task (§13). */
 
-type TaskStatus = "created" | "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled";
+/**
+ * Execution states (v2 Phase 2, roadmap §6.1).
+ *
+ * The crucial distinction: `unknown` means "we cannot prove the outcome" —
+ * e.g. a process timeout after the agent may already have performed side
+ * effects. It is deliberately NOT `failed`: retrying blindly could duplicate
+ * work, and reporting failure would be a lie. Resolve it explicitly with
+ * `task retry` (which starts a fresh execution) or by inspecting artifacts.
+ */
+type TaskStatus = "created" | "queued" | "running" | "waiting" | "completed" | "failed" | "timed_out" | "cancelled" | "unknown" | "partially_completed";
+/** States from which no further automatic transition happens. */
+declare const TERMINAL_TASK_STATUSES: readonly TaskStatus[];
+/** One execution attempt (roadmap §6.5 identity: task + attempt + execution id). */
+interface ExecutionRecord {
+    executionId: string;
+    attempt: number;
+    startedAt: string;
+    finishedAt: string;
+    outcome: "completed" | "failed" | "timed_out" | "unknown" | "cancelled";
+    error?: string;
+}
 interface TaskContext {
     project?: string;
     /** Paths or globs relevant to the task. */
@@ -262,6 +526,12 @@ interface Task {
     status: TaskStatus;
     createdAt: string;
     updatedAt: string;
+    /** Number of engine.run attempts so far (0 = never executed). */
+    attempt: number;
+    /** Error from the most recent failed/unknown attempt. */
+    lastError?: string;
+    /** Recent execution attempts, newest last, bounded in length. */
+    executions?: ExecutionRecord[];
     result?: TaskResult;
 }
 
@@ -282,6 +552,8 @@ interface PipelineStep {
     dependsOn?: string[];
     condition?: PipelineStepCondition;
     retries?: number;
+    /** Constraints handed to the planner for plan steps (§15). */
+    constraints?: string[];
 }
 interface PipelineDefinition {
     id: string;
@@ -292,19 +564,43 @@ interface PipelineDefinition {
     role?: string;
     steps: PipelineStep[];
 }
-type PipelineRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * Run status. "partial" means the run finished but some step outcome was
+ * incomplete or unprovable (partial fan-out, unknown task state) — the
+ * authoritative detail always lives in `stepRuns`/`taskRuns`.
+ */
+type PipelineRunStatus = "pending" | "running" | "completed" | "failed" | "partial" | "cancelled";
+/**
+ * One step execution inside a run (§9.1 — Step Run is NOT the Step).
+ */
 interface PipelineStepRun {
     stepId: string;
     status: TaskStatus;
     /** Tasks created for this step (research fans out to several). */
     taskIds?: string[];
+    /** Execution ids of the tasks this step created, for correlation (§6.5). */
+    executionIds?: string[];
+    /** Which attempt of this step produced this record (1 = first try). */
+    attempt?: number;
     /** Set on plan steps that produced a stored plan (§18). */
     planId?: string;
     error?: string;
 }
+/** One execution attempt of a run (§9.1 — Attempt is not the Run). */
+interface PipelineRunAttempt {
+    attempt: number;
+    startedAt: string;
+    finishedAt?: string;
+    status: PipelineRunStatus;
+}
 interface PipelineRun {
     id: string;
     pipelineId: string;
+    /** Execution attempt counter: retries of the same run increment it. */
+    attempt: number;
+    /** Set when cancellation was requested; the run stops at the next check point. */
+    cancellationRequested?: boolean;
+    cancellationRequestedAt?: string;
     /** The objective this run is executing (persisted for retries). */
     objective?: string;
     status: PipelineRunStatus;
@@ -319,6 +615,28 @@ interface PipelineRun {
     planId?: string;
     /** Outcome summary of the final executed step (§28 — Result). */
     resultSummary?: string;
+    /** Per-attempt history (§9.1). */
+    attempts?: PipelineRunAttempt[];
+}
+/**
+ * Executor contract (roadmap §9.1 / §9.2): a Pipeline definition, a Run of
+ * it, Steps, Step Runs and Attempts are distinct concepts; this interface is
+ * what orchestration code depends on.
+ */
+interface IPipelineExecutor {
+    validate(definition: PipelineDefinition): void;
+    run(definition: PipelineDefinition, options?: PipelineRunOptions): Promise<PipelineRun>;
+    cancel(runId: string): Promise<void>;
+    get(runId: string): Promise<PipelineRun | undefined>;
+    listRuns(filter?: {
+        pipelineId?: string;
+    }): Promise<PipelineRun[]>;
+}
+interface PipelineRunOptions {
+    objective?: string;
+    onStep?: (stepRun: PipelineStepRun) => void;
+    /** Total run attempts (1 = no automatic rerun of the whole run). */
+    maxAttempts?: number;
 }
 
 /** Plan types: the final implementation plan produced by the planner layer (§18). */
@@ -338,6 +656,8 @@ interface PlanStep {
 interface Plan {
     id: string;
     objective: string;
+    /** Explicit goal statement (§15, Planner Output). */
+    goal?: string;
     summary: string;
     steps: PlanStep[];
     risks?: string[];
@@ -459,7 +779,20 @@ interface Project {
 
 type ProviderType = "openai-compatible" | "omnihilbras" | "openrouter" | "local" | "custom";
 type ProviderHealth = "unknown" | "healthy" | "degraded" | "unreachable";
+/** Declared provider capabilities (roadmap §10, Provider Interface). */
+type ProviderCapability = "chat" | "models" | "streaming" | "tools" | "embeddings" | "vision";
+/** Normalized authentication description — never contains a secret value. */
+interface ProviderAuthentication {
+    /** How the provider authenticates. */
+    method: "bearer" | "none" | "custom";
+    /** Environment variable that holds the credential, if any. */
+    envVar?: string;
+    /** True when the referenced variable is currently set. */
+    configured: boolean;
+}
 interface ProviderConfig {
+    /** Stable identifier used in records and references (defaults to `name`). */
+    providerId?: string;
     /** Unique name used in project configuration and the model registry. */
     name: string;
     type: ProviderType;
@@ -470,6 +803,10 @@ interface ProviderConfig {
      */
     apiKeyEnvVar?: string;
     headers?: Record<string, string>;
+    /** Provider-level request timeout in ms (distinct from agent/pipeline budgets). */
+    timeoutMs?: number;
+    /** Capabilities declared for this provider (discovered ones are merged in). */
+    capabilities?: ProviderCapability[];
     enabled?: boolean;
     metadata?: Record<string, unknown>;
 }
@@ -483,17 +820,33 @@ interface ProviderStatus {
     lastCheckedAt?: string;
     message?: string;
 }
-/** Contract every provider adapter implements (Phase 1+). */
+/** Contract every provider adapter implements (roadmap §10). */
 interface IProvider {
     readonly config: ProviderConfig;
+    /** Stable identifier of this provider. */
+    readonly providerId: string;
+    /** Normalized authentication description (no secret values). */
+    readonly authentication: ProviderAuthentication;
+    /**
+     * Connect: authenticate and discover models (roadmap §10, Model Discovery).
+     * Returns the discovered models.
+     */
+    connect(): Promise<ModelInfo[]>;
     /** Discover models exposed by this provider. */
     listModels(): Promise<ModelInfo[]>;
+    /** Fetch a single model's metadata (from discovery; re-discovers if unknown). */
+    getModel(modelId: string): Promise<ModelInfo | undefined>;
     /** Check connectivity and authentication. */
     healthCheck(): Promise<ProviderStatus>;
 }
 /** Contract for providers that can run chat completions (foundation for planning). */
 interface IChatProvider extends IProvider {
     chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Stream a completion where the provider supports it (§11). Chunks are
+     * delivered in order; the resolved ChatResponse carries the assembled text.
+     */
+    stream?(request: ChatRequest, onChunk: (chunk: ChatStreamChunk) => void): Promise<ChatResponse>;
 }
 
 /** Typed error hierarchy shared across the whole codebase (§4.1 — error model). */
@@ -578,6 +931,7 @@ declare const providerConfigSchema: z.ZodObject<{
     type: z.ZodEnum<["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]>;
     base_url: z.ZodString;
     api_key_env_var: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -585,18 +939,20 @@ declare const providerConfigSchema: z.ZodObject<{
     name: string;
     type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
     base_url: string;
+    metadata?: Record<string, unknown> | undefined;
     api_key_env_var?: string | undefined;
+    timeout_ms?: number | undefined;
     headers?: Record<string, string> | undefined;
     enabled?: boolean | undefined;
-    metadata?: Record<string, unknown> | undefined;
 }, {
     name: string;
     type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
     base_url: string;
+    metadata?: Record<string, unknown> | undefined;
     api_key_env_var?: string | undefined;
+    timeout_ms?: number | undefined;
     headers?: Record<string, string> | undefined;
     enabled?: boolean | undefined;
-    metadata?: Record<string, unknown> | undefined;
 }>;
 declare const agentConfigSchema: z.ZodObject<{
     name: z.ZodString;
@@ -609,29 +965,44 @@ declare const agentConfigSchema: z.ZodObject<{
     input_mode: z.ZodDefault<z.ZodEnum<["stdin", "arg", "protocol"]>>;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
     inherit_env: z.ZodOptional<z.ZodBoolean>;
+    env_policy: z.ZodOptional<z.ZodEnum<["inherit", "allowlist", "denylist", "explicit"]>>;
+    env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env_denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    max_output_bytes: z.ZodOptional<z.ZodNumber>;
+    allow_external_cwd: z.ZodOptional<z.ZodBoolean>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strict", z.ZodTypeAny, {
     name: string;
     type: "native" | "process" | "cli";
-    input_mode: "stdin" | "arg" | "protocol";
-    metadata?: Record<string, unknown> | undefined;
+    input_mode: "protocol" | "stdin" | "arg";
     command?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    timeout_ms?: number | undefined;
     args?: string[] | undefined;
     cwd?: string | undefined;
     env?: Record<string, string> | undefined;
-    timeout_ms?: number | undefined;
     inherit_env?: boolean | undefined;
+    env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+    env_allowlist?: string[] | undefined;
+    env_denylist?: string[] | undefined;
+    max_output_bytes?: number | undefined;
+    allow_external_cwd?: boolean | undefined;
 }, {
     name: string;
-    type?: "native" | "process" | "cli" | undefined;
-    metadata?: Record<string, unknown> | undefined;
     command?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    type?: "native" | "process" | "cli" | undefined;
+    timeout_ms?: number | undefined;
     args?: string[] | undefined;
     cwd?: string | undefined;
     env?: Record<string, string> | undefined;
-    input_mode?: "stdin" | "arg" | "protocol" | undefined;
-    timeout_ms?: number | undefined;
+    input_mode?: "protocol" | "stdin" | "arg" | undefined;
     inherit_env?: boolean | undefined;
+    env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+    env_allowlist?: string[] | undefined;
+    env_denylist?: string[] | undefined;
+    max_output_bytes?: number | undefined;
+    allow_external_cwd?: boolean | undefined;
 }>;
 declare const roleConfigSchema: z.ZodObject<{
     id: z.ZodString;
@@ -670,6 +1041,8 @@ declare const pipelineStepConfigSchema: z.ZodObject<{
     depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     retries: z.ZodOptional<z.ZodNumber>;
     condition: z.ZodOptional<z.ZodEnum<["always", "on-success", "on-failure"]>>;
+    /** Constraints passed to the planner for plan steps (§15). */
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     id: string;
     kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -679,6 +1052,7 @@ declare const pipelineStepConfigSchema: z.ZodObject<{
     depends_on?: string[] | undefined;
     retries?: number | undefined;
     condition?: "always" | "on-success" | "on-failure" | undefined;
+    constraints?: string[] | undefined;
 }, {
     id: string;
     kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -688,6 +1062,7 @@ declare const pipelineStepConfigSchema: z.ZodObject<{
     depends_on?: string[] | undefined;
     retries?: number | undefined;
     condition?: "always" | "on-success" | "on-failure" | undefined;
+    constraints?: string[] | undefined;
 }>;
 declare const pipelineConfigSchema: z.ZodObject<{
     id: z.ZodString;
@@ -703,6 +1078,8 @@ declare const pipelineConfigSchema: z.ZodObject<{
         depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         retries: z.ZodOptional<z.ZodNumber>;
         condition: z.ZodOptional<z.ZodEnum<["always", "on-success", "on-failure"]>>;
+        /** Constraints passed to the planner for plan steps (§15). */
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         id: string;
         kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -712,6 +1089,7 @@ declare const pipelineConfigSchema: z.ZodObject<{
         depends_on?: string[] | undefined;
         retries?: number | undefined;
         condition?: "always" | "on-success" | "on-failure" | undefined;
+        constraints?: string[] | undefined;
     }, {
         id: string;
         kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -721,6 +1099,7 @@ declare const pipelineConfigSchema: z.ZodObject<{
         depends_on?: string[] | undefined;
         retries?: number | undefined;
         condition?: "always" | "on-success" | "on-failure" | undefined;
+        constraints?: string[] | undefined;
     }>, "many">;
 }, "strict", z.ZodTypeAny, {
     id: string;
@@ -733,9 +1112,10 @@ declare const pipelineConfigSchema: z.ZodObject<{
         depends_on?: string[] | undefined;
         retries?: number | undefined;
         condition?: "always" | "on-success" | "on-failure" | undefined;
+        constraints?: string[] | undefined;
     }[];
-    role?: string | undefined;
     name?: string | undefined;
+    role?: string | undefined;
     objective?: string | undefined;
 }, {
     id: string;
@@ -748,9 +1128,10 @@ declare const pipelineConfigSchema: z.ZodObject<{
         depends_on?: string[] | undefined;
         retries?: number | undefined;
         condition?: "always" | "on-success" | "on-failure" | undefined;
+        constraints?: string[] | undefined;
     }[];
-    role?: string | undefined;
     name?: string | undefined;
+    role?: string | undefined;
     objective?: string | undefined;
 }>;
 declare const plannerConfigSchema: z.ZodObject<{
@@ -773,6 +1154,7 @@ declare const projectConfigSchema: z.ZodObject<{
         type: z.ZodEnum<["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]>;
         base_url: z.ZodString;
         api_key_env_var: z.ZodOptional<z.ZodString>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -780,18 +1162,20 @@ declare const projectConfigSchema: z.ZodObject<{
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         api_key_env_var?: string | undefined;
+        timeout_ms?: number | undefined;
         headers?: Record<string, string> | undefined;
         enabled?: boolean | undefined;
-        metadata?: Record<string, unknown> | undefined;
     }, {
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         api_key_env_var?: string | undefined;
+        timeout_ms?: number | undefined;
         headers?: Record<string, string> | undefined;
         enabled?: boolean | undefined;
-        metadata?: Record<string, unknown> | undefined;
     }>, "many">>;
     agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -804,29 +1188,44 @@ declare const projectConfigSchema: z.ZodObject<{
         input_mode: z.ZodDefault<z.ZodEnum<["stdin", "arg", "protocol"]>>;
         timeout_ms: z.ZodOptional<z.ZodNumber>;
         inherit_env: z.ZodOptional<z.ZodBoolean>;
+        env_policy: z.ZodOptional<z.ZodEnum<["inherit", "allowlist", "denylist", "explicit"]>>;
+        env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env_denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        max_output_bytes: z.ZodOptional<z.ZodNumber>;
+        allow_external_cwd: z.ZodOptional<z.ZodBoolean>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strict", z.ZodTypeAny, {
         name: string;
         type: "native" | "process" | "cli";
-        input_mode: "stdin" | "arg" | "protocol";
-        metadata?: Record<string, unknown> | undefined;
+        input_mode: "protocol" | "stdin" | "arg";
         command?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        timeout_ms?: number | undefined;
         args?: string[] | undefined;
         cwd?: string | undefined;
         env?: Record<string, string> | undefined;
-        timeout_ms?: number | undefined;
         inherit_env?: boolean | undefined;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }, {
         name: string;
-        type?: "native" | "process" | "cli" | undefined;
-        metadata?: Record<string, unknown> | undefined;
         command?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        type?: "native" | "process" | "cli" | undefined;
+        timeout_ms?: number | undefined;
         args?: string[] | undefined;
         cwd?: string | undefined;
         env?: Record<string, string> | undefined;
-        input_mode?: "stdin" | "arg" | "protocol" | undefined;
-        timeout_ms?: number | undefined;
+        input_mode?: "protocol" | "stdin" | "arg" | undefined;
         inherit_env?: boolean | undefined;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }>, "many">>;
     roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -870,6 +1269,8 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             retries: z.ZodOptional<z.ZodNumber>;
             condition: z.ZodOptional<z.ZodEnum<["always", "on-success", "on-failure"]>>;
+            /** Constraints passed to the planner for plan steps (§15). */
+            constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         }, "strict", z.ZodTypeAny, {
             id: string;
             kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -879,6 +1280,7 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on?: string[] | undefined;
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
+            constraints?: string[] | undefined;
         }, {
             id: string;
             kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -888,6 +1290,7 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on?: string[] | undefined;
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
+            constraints?: string[] | undefined;
         }>, "many">;
     }, "strict", z.ZodTypeAny, {
         id: string;
@@ -900,9 +1303,10 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on?: string[] | undefined;
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
+            constraints?: string[] | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }, {
         id: string;
@@ -915,9 +1319,10 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on?: string[] | undefined;
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
+            constraints?: string[] | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }>, "many">>;
     planner: z.ZodOptional<z.ZodObject<{
@@ -937,37 +1342,47 @@ declare const projectConfigSchema: z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
         base_url: z.ZodOptional<z.ZodString>;
         api_key_env_var: z.ZodOptional<z.ZodString>;
+        /** When true, memory failures fail tasks instead of being tolerated (§12). */
+        required: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         provider: string;
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
+        required?: boolean | undefined;
     }, {
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
         provider?: string | undefined;
+        required?: boolean | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
     name: string;
     agents: {
         name: string;
         type: "native" | "process" | "cli";
-        input_mode: "stdin" | "arg" | "protocol";
-        metadata?: Record<string, unknown> | undefined;
+        input_mode: "protocol" | "stdin" | "arg";
         command?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        timeout_ms?: number | undefined;
         args?: string[] | undefined;
         cwd?: string | undefined;
         env?: Record<string, string> | undefined;
-        timeout_ms?: number | undefined;
         inherit_env?: boolean | undefined;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }[];
     providers: {
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         api_key_env_var?: string | undefined;
+        timeout_ms?: number | undefined;
         headers?: Record<string, string> | undefined;
         enabled?: boolean | undefined;
-        metadata?: Record<string, unknown> | undefined;
     }[];
     roles: {
         name: string;
@@ -990,9 +1405,10 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on?: string[] | undefined;
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
+            constraints?: string[] | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }[];
     planner?: {
@@ -1004,29 +1420,36 @@ declare const projectConfigSchema: z.ZodObject<{
         provider: string;
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
+        required?: boolean | undefined;
     } | undefined;
 }, {
     name: string;
     agents?: {
         name: string;
-        type?: "native" | "process" | "cli" | undefined;
-        metadata?: Record<string, unknown> | undefined;
         command?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        type?: "native" | "process" | "cli" | undefined;
+        timeout_ms?: number | undefined;
         args?: string[] | undefined;
         cwd?: string | undefined;
         env?: Record<string, string> | undefined;
-        input_mode?: "stdin" | "arg" | "protocol" | undefined;
-        timeout_ms?: number | undefined;
+        input_mode?: "protocol" | "stdin" | "arg" | undefined;
         inherit_env?: boolean | undefined;
+        env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+        env_allowlist?: string[] | undefined;
+        env_denylist?: string[] | undefined;
+        max_output_bytes?: number | undefined;
+        allow_external_cwd?: boolean | undefined;
     }[] | undefined;
     providers?: {
         name: string;
         type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
         base_url: string;
+        metadata?: Record<string, unknown> | undefined;
         api_key_env_var?: string | undefined;
+        timeout_ms?: number | undefined;
         headers?: Record<string, string> | undefined;
         enabled?: boolean | undefined;
-        metadata?: Record<string, unknown> | undefined;
     }[] | undefined;
     roles?: {
         name: string;
@@ -1049,9 +1472,10 @@ declare const projectConfigSchema: z.ZodObject<{
             depends_on?: string[] | undefined;
             retries?: number | undefined;
             condition?: "always" | "on-success" | "on-failure" | undefined;
+            constraints?: string[] | undefined;
         }[];
-        role?: string | undefined;
         name?: string | undefined;
+        role?: string | undefined;
         objective?: string | undefined;
     }[] | undefined;
     planner?: {
@@ -1063,6 +1487,7 @@ declare const projectConfigSchema: z.ZodObject<{
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
         provider?: string | undefined;
+        required?: boolean | undefined;
     } | undefined;
 }>;
 declare const appConfigSchema: z.ZodObject<{
@@ -1073,6 +1498,7 @@ declare const appConfigSchema: z.ZodObject<{
             type: z.ZodEnum<["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]>;
             base_url: z.ZodString;
             api_key_env_var: z.ZodOptional<z.ZodString>;
+            timeout_ms: z.ZodOptional<z.ZodNumber>;
             headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             enabled: z.ZodOptional<z.ZodBoolean>;
             metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -1080,18 +1506,20 @@ declare const appConfigSchema: z.ZodObject<{
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
+            timeout_ms?: number | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }, {
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
+            timeout_ms?: number | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }>, "many">>;
         agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -1104,29 +1532,44 @@ declare const appConfigSchema: z.ZodObject<{
             input_mode: z.ZodDefault<z.ZodEnum<["stdin", "arg", "protocol"]>>;
             timeout_ms: z.ZodOptional<z.ZodNumber>;
             inherit_env: z.ZodOptional<z.ZodBoolean>;
+            env_policy: z.ZodOptional<z.ZodEnum<["inherit", "allowlist", "denylist", "explicit"]>>;
+            env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            env_denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            max_output_bytes: z.ZodOptional<z.ZodNumber>;
+            allow_external_cwd: z.ZodOptional<z.ZodBoolean>;
             metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, "strict", z.ZodTypeAny, {
             name: string;
             type: "native" | "process" | "cli";
-            input_mode: "stdin" | "arg" | "protocol";
-            metadata?: Record<string, unknown> | undefined;
+            input_mode: "protocol" | "stdin" | "arg";
             command?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            timeout_ms?: number | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }, {
             name: string;
-            type?: "native" | "process" | "cli" | undefined;
-            metadata?: Record<string, unknown> | undefined;
             command?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            type?: "native" | "process" | "cli" | undefined;
+            timeout_ms?: number | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            input_mode?: "stdin" | "arg" | "protocol" | undefined;
-            timeout_ms?: number | undefined;
+            input_mode?: "protocol" | "stdin" | "arg" | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }>, "many">>;
         roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -1170,6 +1613,8 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
                 retries: z.ZodOptional<z.ZodNumber>;
                 condition: z.ZodOptional<z.ZodEnum<["always", "on-success", "on-failure"]>>;
+                /** Constraints passed to the planner for plan steps (§15). */
+                constraints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             }, "strict", z.ZodTypeAny, {
                 id: string;
                 kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -1179,6 +1624,7 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }, {
                 id: string;
                 kind: "custom" | "research" | "collect" | "analyze" | "plan" | "execute";
@@ -1188,6 +1634,7 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }>, "many">;
         }, "strict", z.ZodTypeAny, {
             id: string;
@@ -1200,9 +1647,10 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }, {
             id: string;
@@ -1215,9 +1663,10 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }>, "many">>;
         planner: z.ZodOptional<z.ZodObject<{
@@ -1237,37 +1686,47 @@ declare const appConfigSchema: z.ZodObject<{
             provider: z.ZodDefault<z.ZodString>;
             base_url: z.ZodOptional<z.ZodString>;
             api_key_env_var: z.ZodOptional<z.ZodString>;
+            /** When true, memory failures fail tasks instead of being tolerated (§12). */
+            required: z.ZodOptional<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
+            required?: boolean | undefined;
         }, {
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
         name: string;
         agents: {
             name: string;
             type: "native" | "process" | "cli";
-            input_mode: "stdin" | "arg" | "protocol";
-            metadata?: Record<string, unknown> | undefined;
+            input_mode: "protocol" | "stdin" | "arg";
             command?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            timeout_ms?: number | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[];
         providers: {
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
+            timeout_ms?: number | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[];
         roles: {
             name: string;
@@ -1290,9 +1749,10 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[];
         planner?: {
@@ -1304,29 +1764,36 @@ declare const appConfigSchema: z.ZodObject<{
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     }, {
         name: string;
         agents?: {
             name: string;
-            type?: "native" | "process" | "cli" | undefined;
-            metadata?: Record<string, unknown> | undefined;
             command?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            type?: "native" | "process" | "cli" | undefined;
+            timeout_ms?: number | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            input_mode?: "stdin" | "arg" | "protocol" | undefined;
-            timeout_ms?: number | undefined;
+            input_mode?: "protocol" | "stdin" | "arg" | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[] | undefined;
         providers?: {
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
+            timeout_ms?: number | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[] | undefined;
         roles?: {
             name: string;
@@ -1349,9 +1816,10 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[] | undefined;
         planner?: {
@@ -1363,6 +1831,7 @@ declare const appConfigSchema: z.ZodObject<{
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     }>;
     logging: z.ZodOptional<z.ZodObject<{
@@ -1378,23 +1847,29 @@ declare const appConfigSchema: z.ZodObject<{
         agents: {
             name: string;
             type: "native" | "process" | "cli";
-            input_mode: "stdin" | "arg" | "protocol";
-            metadata?: Record<string, unknown> | undefined;
+            input_mode: "protocol" | "stdin" | "arg";
             command?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            timeout_ms?: number | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            timeout_ms?: number | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[];
         providers: {
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
+            timeout_ms?: number | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[];
         roles: {
             name: string;
@@ -1417,9 +1892,10 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[];
         planner?: {
@@ -1431,6 +1907,7 @@ declare const appConfigSchema: z.ZodObject<{
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     };
     logging?: {
@@ -1441,24 +1918,30 @@ declare const appConfigSchema: z.ZodObject<{
         name: string;
         agents?: {
             name: string;
-            type?: "native" | "process" | "cli" | undefined;
-            metadata?: Record<string, unknown> | undefined;
             command?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            type?: "native" | "process" | "cli" | undefined;
+            timeout_ms?: number | undefined;
             args?: string[] | undefined;
             cwd?: string | undefined;
             env?: Record<string, string> | undefined;
-            input_mode?: "stdin" | "arg" | "protocol" | undefined;
-            timeout_ms?: number | undefined;
+            input_mode?: "protocol" | "stdin" | "arg" | undefined;
             inherit_env?: boolean | undefined;
+            env_policy?: "inherit" | "allowlist" | "denylist" | "explicit" | undefined;
+            env_allowlist?: string[] | undefined;
+            env_denylist?: string[] | undefined;
+            max_output_bytes?: number | undefined;
+            allow_external_cwd?: boolean | undefined;
         }[] | undefined;
         providers?: {
             name: string;
             type: "custom" | "openai-compatible" | "omnihilbras" | "openrouter" | "local";
             base_url: string;
+            metadata?: Record<string, unknown> | undefined;
             api_key_env_var?: string | undefined;
+            timeout_ms?: number | undefined;
             headers?: Record<string, string> | undefined;
             enabled?: boolean | undefined;
-            metadata?: Record<string, unknown> | undefined;
         }[] | undefined;
         roles?: {
             name: string;
@@ -1481,9 +1964,10 @@ declare const appConfigSchema: z.ZodObject<{
                 depends_on?: string[] | undefined;
                 retries?: number | undefined;
                 condition?: "always" | "on-success" | "on-failure" | undefined;
+                constraints?: string[] | undefined;
             }[];
-            role?: string | undefined;
             name?: string | undefined;
+            role?: string | undefined;
             objective?: string | undefined;
         }[] | undefined;
         planner?: {
@@ -1495,6 +1979,7 @@ declare const appConfigSchema: z.ZodObject<{
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     };
     logging?: {
@@ -1526,6 +2011,7 @@ interface AppConfig {
             provider: string;
             baseUrl?: string;
             apiKeyEnvVar?: string;
+            required?: boolean;
         };
     };
     logging?: {
@@ -1576,11 +2062,63 @@ declare function requestJson(url: string, options?: HttpRequestOptions): Promise
 declare const OPENAI_COMPATIBLE_TYPES: readonly ProviderType[];
 declare function createProvider(config: ProviderConfig): IChatProvider;
 
+/**
+ * Provider error normalization (roadmap §10).
+ *
+ * Every provider failure is mapped to one stable kind, so callers can react
+ * (retry a rate limit, surface an auth problem, treat a missing model
+ * differently) without string-matching provider-specific payloads.
+ */
+
+type ProviderErrorKind = "AUTHENTICATION_ERROR" | "RATE_LIMIT_ERROR" | "INVALID_REQUEST" | "MODEL_NOT_FOUND" | "TIMEOUT" | "NETWORK_ERROR" | "SERVER_ERROR" | "UNKNOWN_ERROR";
+interface ProviderErrorContext {
+    provider: string;
+    operation: string;
+    status?: number;
+    body?: unknown;
+    retryAfterMs?: number;
+    cause?: unknown;
+    /** Maps the normalized kind onto the legacy stable error code. */
+    code?: "PROVIDER_UNAVAILABLE" | "PROVIDER_AUTH_FAILED" | "MODEL_NOT_FOUND";
+}
+/** Kinds worth retrying automatically (rate limits and transient server errors). */
+declare function isRetryable(kind: ProviderErrorKind): boolean;
+/** Maps an HTTP status (and optional body) to a normalized kind. */
+declare function kindFromStatus(status: number): ProviderErrorKind;
+/** Extracts a human message from common provider error body shapes. */
+declare function extractMessage(body: unknown): string | undefined;
+/** Parses `Retry-After` (seconds or HTTP-date) into milliseconds. */
+declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** True for the abort/timeout errors raised by fetch's AbortSignal.timeout. */
+declare function isTimeoutError(error: unknown): boolean;
+/** True for transport failures (DNS, refused, TLS, offline). */
+declare function isNetworkError(error: unknown): boolean;
+declare function providerHttpError(context: ProviderErrorContext): ProviderError;
+/** Wraps a thrown transport/abort error into a normalized ProviderError. */
+declare function providerTransportError(context: Omit<ProviderErrorContext, "status" | "body">): ProviderError;
+
 declare class OpenAICompatibleProvider implements IChatProvider {
     readonly config: ProviderConfig;
+    readonly providerId: string;
+    readonly authentication: ProviderAuthentication;
     private readonly log;
-    constructor(config: ProviderConfig, log?: Logger);
+    /** Discovered models, so getModel() answers without another round-trip. */
+    private discovered?;
+    private readonly env;
+    constructor(config: ProviderConfig, log?: Logger, env?: Record<string, string | undefined>);
+    /** Provider-level request timeout (roadmap §6.6/§11) with the shared default. */
+    private get requestTimeoutMs();
+    /** Authenticate + discover (roadmap §10, Model Discovery). */
+    connect(): Promise<ModelInfo[]>;
+    getModel(modelId: string): Promise<ModelInfo | undefined>;
+    /** Raw /models body (protected so adapters can capture gateway-level metadata). */
+    protected rawModelsResponse(): Promise<unknown>;
+    private modelsRequest;
     listModels(): Promise<ModelInfo[]>;
+    /** Maps a raw model entry onto the normalized metadata shape (§10). */
+    private toModelInfo;
+    /** Streaming where the gateway supports it (§11). */
+    stream(request: ChatRequest, onChunk: (chunk: ChatStreamChunk) => void): Promise<ChatResponse>;
     healthCheck(): Promise<ProviderStatus>;
     chat(request: ChatRequest): Promise<ChatResponse>;
 }
@@ -1623,20 +2161,37 @@ interface OmniHilbrasConnectionResult {
     registered: number;
 }
 declare class OmniHilbrasProvider extends OpenAICompatibleProvider {
+    private gateway?;
+    listModels(): Promise<ModelInfo[]>;
     /**
      * Run the full connect flow. Throws on authentication or transport failure
      * (use healthCheck() for a non-throwing probe).
      */
-    connect(registry?: ModelRegistry): Promise<OmniHilbrasConnectionResult>;
+    /**
+     * Gateway metadata reported alongside the model list (gateway version, tier,
+     * region…), kept separate from per-model metadata (§11 — provider metadata).
+     */
+    gatewayMetadata(): Record<string, unknown> | undefined;
+    protected extractGatewayMetadata(body: unknown): Promise<void>;
+    connectAndRegister(registry?: ModelRegistry): Promise<OmniHilbrasConnectionResult>;
 }
 
 /**
- * Builds the child environment. By default the agent inherits the full
- * environment; with `inheritEnv: false` it receives only PATH plus the
- * explicitly configured variables — useful to avoid leaking OmniNode's
- * own secrets (e.g. provider API keys) into third-party agents.
+ * Process adapter (§9): runs CLI agents as child processes and communicates
+ * over stdin/stdout, managing the process lifecycle, working directory,
+ * environment, exit codes, logs and timeouts.
+ *
+ * Three input modes (§9, §21):
+ *  - "stdin":    the composed task text is written to the agent's stdin.
+ *  - "arg":      the composed task text is appended as the last command argument.
+ *  - "protocol": NodeToAgentMessage envelopes as JSON lines on stdin; the
+ *                agent answers with AgentToNodeMessage JSON lines (REPORT,
+ *                COMPLETION, ERROR, ...) whose structured payloads are parsed
+ *                into reports.
  */
-declare function buildChildEnv(config: AgentConfig): NodeJS.ProcessEnv;
+
+/** Per-stream byte budget before output is truncated and the agent killed. */
+declare const DEFAULT_MAX_OUTPUT_BYTES: number;
 declare function composeTaskText(input: AgentTaskInput): string;
 declare class ProcessAgent implements IAgent {
     readonly config: AgentConfig;
@@ -1649,6 +2204,63 @@ declare class ProcessAgent implements IAgent {
     cancel(taskId: string): Promise<void>;
     runningTaskIds(): string[];
 }
+/** Kills a child and, on POSIX, its whole process group (roadmap §8 tree cleanup). */
+declare function killTree(child: ChildProcess, signal: NodeJS.Signals): void;
+/** Human-readable exit reason, including signal terminations. */
+declare function describeExit(code: number | null, signal: NodeJS.Signals | null): string;
+/**
+ * Decodes a stdout/stderr chunk safely: invalid UTF-8 becomes replacement
+ * characters and NUL bytes are stripped, so binary noise cannot poison the
+ * protocol decoder or the terminal (roadmap §8, encoding hardening).
+ */
+declare function sanitizeChunk(chunk: Buffer): string;
+
+/**
+ * Agent environment policies (roadmap §8, Environment Isolation).
+ *
+ * Four explicit policies, so operators decide exactly what an agent can see:
+ *   - `inherit`   (default, backwards compatible): the full parent environment
+ *   - `allowlist`: only the allow-listed variables (+ PATH/HOME)
+ *   - `denylist`: the parent environment minus the deny-listed variables
+ *   - `explicit`: nothing from the parent; only PATH/HOME and `env`
+ *
+ * The v1 boolean `inherit_env: false` is still honored and maps to `explicit`.
+ */
+
+type EnvPolicy = "inherit" | "allowlist" | "denylist" | "explicit";
+declare function resolveEnvPolicy(config: Partial<AgentConfig>): EnvPolicy;
+declare function buildChildEnv(config: AgentConfig): NodeJS.ProcessEnv;
+
+interface CwdValidation {
+    /** Normalized absolute path. */
+    cwd: string;
+    /** True when the directory sits outside the project root (project boundary). */
+    outsideProject: boolean;
+}
+declare function validateWorkingDirectory(cwd: string | undefined, options?: {
+    projectRoot?: string;
+    allowExternal?: boolean;
+}): CwdValidation | undefined;
+
+interface IAgentAdapter {
+    /** Integration type this adapter serves, e.g. "native" or "process". */
+    readonly integration: string;
+    create(config: AgentConfig): IAgent;
+}
+declare class AgentAdapterRegistry {
+    private readonly adapters;
+    register(adapter: IAgentAdapter): void;
+    get(integration: string): IAgentAdapter | undefined;
+    list(): IAgentAdapter[];
+    create(config: AgentConfig): IAgent;
+}
+/** Process-level adapter — the built-in CLI integration. */
+declare class ProcessAgentAdapter implements IAgentAdapter {
+    private readonly factory;
+    readonly integration = "process";
+    constructor(factory: (config: AgentConfig) => IAgent);
+    create(config: AgentConfig): IAgent;
+}
 
 /** Agent registry (§10): the set of agents connected to OmniNode. */
 
@@ -1664,10 +2276,109 @@ declare class AgentRegistry {
  * "cli" agent configs are mapped to the process integration by the loader.
  */
 
-declare function createAgent(config: AgentConfig): IAgent;
+declare function createAgent(config: AgentConfig, adapters?: AgentAdapterRegistry): IAgent;
+
 /** Builds an agent registry from the project configuration, skipping agents that fail to construct. */
 declare function buildAgentRegistry(config: AppConfig, log?: Logger): AgentRegistry;
 
+/**
+ * OmniNode Agent Protocol v2 — versioning (roadmap §7.1).
+ *
+ * Protocol identifiers are namespaced strings so an agent can negotiate the
+ * dialect it speaks: `omninode-agent-protocol/2`.
+ */
+declare const PROTOCOL_V2 = "omninode-agent-protocol/2";
+/** Versions this build accepts. v1 is the unversioned dialect shipped with OmniNode 1.x. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+declare const MAX_MESSAGE_BYTES = 1048576;
+declare function isSupportedProtocol(protocol: string): boolean;
+
+type ProtocolViolationCode = "INVALID_JSON" | "NOT_AN_OBJECT" | "UNKNOWN_TYPE" | "MISSING_FIELD" | "UNSUPPORTED_VERSION" | "OVERSIZED" | "INVALID_PAYLOAD";
+interface ProtocolViolation {
+    code: ProtocolViolationCode;
+    message: string;
+    /** Raw line (truncated) for diagnostics. */
+    sample?: string;
+}
+type DecodeResult = {
+    ok: true;
+    envelope: ProtocolEnvelope;
+    legacy: boolean;
+} | {
+    ok: false;
+    error: ProtocolViolation;
+};
+/** Validates one decoded JSON value as a protocol envelope. */
+declare function validateEnvelope(value: unknown, line?: string): DecodeResult;
+/** Decodes one protocol line (no trailing newline). */
+declare function decodeMessage(line: string, maxBytes?: number): DecodeResult;
+/** Serializes an envelope to a single JSON line. */
+declare function encodeMessage(envelope: ProtocolEnvelope, maxBytes?: number): string;
+/**
+ * Streaming line decoder for agent stdout. Feed chunks; receive decoded
+ * envelopes and violations in order. Survives garbage: a bad line yields a
+ * violation and the stream continues.
+ */
+declare class ProtocolDecoder {
+    private buffer;
+    private readonly maxBytes;
+    constructor(maxBytes?: number);
+    push(chunk: string): DecodeResult[];
+    /** Flush any trailing line when the process exits. */
+    flush(): DecodeResult[];
+}
+
+/**
+ * OmniNode Agent Protocol v2 — session (roadmap §7.6).
+ *
+ * A session drives a protocol-mode agent: it emits v2 envelopes with
+ * correlation ids, tolerates legacy (unversioned) replies, answers agent
+ * questions through a responder callback, and collects reports, artifacts
+ * and the completion — never throwing on malformed input.
+ */
+
+interface SessionIds {
+    requestId: string;
+    taskId: string;
+    agentId: string;
+    pipelineId?: string;
+    executionId?: string;
+}
+interface QuestionResponder {
+    (question: {
+        questionId: string;
+        question: string;
+        expected?: string;
+    }): Promise<string> | string;
+}
+declare class ProtocolSession {
+    readonly decoder: ProtocolDecoder;
+    private readonly ids;
+    private readonly responder;
+    readonly violations: ProtocolViolation[];
+    readonly questions: AskedQuestion[];
+    readonly artifacts: ProtocolEnvelope["payload"][];
+    reports: ProtocolEnvelope["payload"][];
+    descriptor?: AgentDescriptor;
+    completionSummary?: string;
+    errorMessage?: string;
+    constructor(ids: SessionIds, options?: {
+        responder?: QuestionResponder;
+        maxBytes?: number;
+    });
+    /** The v2 messages OmniNode sends to open a task (written to the agent's stdin). */
+    taskMessages(objective: string, role?: unknown, context?: string, instruction?: string): string[];
+    helloAck(descriptor: AgentDescriptor): string;
+    /** Consumes decoded stdout, answering questions as they arrive. */
+    handle(decoded: DecodeResult): Promise<void>;
+    private answerQuestion;
+    readonly pendingAnswers: string[];
+    /** True once any inbound message carried the v2 protocol field. */
+    sawV2: boolean;
+}
+declare function decodeStream(session: ProtocolSession, chunk: string): Promise<string[]>;
+declare function requireCompletion(session: ProtocolSession): void;
+
 /** Role registry (§11): the set of roles available for task assignment. */
 
 declare class RoleRegistry {
@@ -1764,8 +2475,17 @@ declare function keywords(text: string): Set<string>;
 declare class LocalMemoryProvider extends JsonFileStore<MemoryEntry> implements IMemoryProvider {
     readonly name = "local";
     constructor(directory?: string);
+    metadata(): MemoryProviderMetadata;
+    search(text: string, options?: {
+        limit?: number;
+        scope?: MemoryQuery["scope"];
+    }): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link retrieve}. */
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link store}. */
     write(entry: MemoryEntry): Promise<void>;
+    retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
+    store(entry: MemoryEntry): Promise<void>;
     count(): Promise<number>;
 }
 
@@ -1781,9 +2501,20 @@ declare class RememberaMemoryProvider implements IMemoryProvider {
     private readonly env;
     private readonly log;
     constructor(config: RememberaConfig, log?: Logger);
+    private get authenticationConfigured();
     private headers;
+    /** Search delegates to the gateway's relevance query. */
+    search(text: string, options?: {
+        limit?: number;
+        scope?: MemoryQuery["scope"];
+    }): Promise<MemoryEntry[]>;
+    metadata(): MemoryProviderMetadata;
+    /** @deprecated v1 alias of {@link retrieve}. */
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link store}. */
     write(entry: MemoryEntry): Promise<void>;
+    retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
+    store(entry: MemoryEntry): Promise<void>;
     private request;
     private toEntry;
 }
@@ -1791,31 +2522,66 @@ declare class RememberaMemoryProvider implements IMemoryProvider {
 type MemoryProviderConfig = NonNullable<AppConfig["project"]["memory"]>;
 declare function createMemoryProvider(config?: MemoryProviderConfig): IMemoryProvider;
 
-/**
- * Memory service (§19–§20): gathers relevant memory before a task runs and
- * records outcomes afterwards — the Task → memory → relevant context →
- * agents → reports → memory loop. Memory failures are best-effort: they log
- * a warning and never fail a task, because memory is an enhancement, not a
- * dependency (§2).
- */
-
 interface MemoryContextQuery {
     objective: string;
     role?: string;
     project?: string;
+    /** Maximum entries to consider (relevance-ranked by the provider). */
+    limit?: number;
+}
+interface MemoryTaskContext {
+    /** Prompt-ready context text ("" when nothing relevant was found). */
+    text: string;
+    entries: MemoryEntry[];
+    /** True when the character budget cut the context short. */
+    truncated: boolean;
+}
+declare const MAX_CONTEXT_CHARS = 4000;
+interface MemoryServiceOptions {
+    /** When true, backend failures propagate instead of being logged. */
+    required?: boolean;
+    maxContextChars?: number;
 }
 declare class MemoryService {
     private readonly provider;
     private readonly log;
-    constructor(provider: IMemoryProvider, log?: Logger);
+    private readonly required;
+    private readonly maxContextChars;
+    constructor(provider: IMemoryProvider, log?: Logger, options?: MemoryServiceOptions);
     get providerRef(): IMemoryProvider;
     get providerName(): string;
-    /** Relevant context for a task objective; empty string when nothing matches. */
+    get isRequired(): boolean;
+    /** Structured, budgeted context for a task (§12 — avoid loading all memory). */
+    contextFor(query: MemoryContextQuery): Promise<MemoryTaskContext>;
+    /** Prompt-ready context text (v1 convenience wrapper). */
     gatherContext(query: MemoryContextQuery): Promise<string>;
-    /** Records a finished task's outcome — best-effort. */
+    /** Records a finished task's outcome — task history plus "known problems" (§12). */
     recordTaskOutcome(task: Task): Promise<void>;
+    private format;
+    /**
+     * Failure policy (§12): continue unless memory is explicitly required.
+     */
+    private handleFailure;
 }
 
+/**
+ * Shared memory-contract helpers (roadmap §12). Adapters implement
+ * `retrieve` / `store`; these helpers supply the defaults for `search`,
+ * `metadata` and the v1 `query` / `write` aliases, so the contract is
+ * defined once.
+ */
+
+/** Free-text search defaults to a relevance retrieve. */
+declare function defaultSearch(provider: Pick<IMemoryProvider, "retrieve">, text: string, options?: {
+    limit?: number;
+    scope?: MemoryQuery["scope"];
+}): Promise<MemoryEntry[]>;
+declare function defaultMetadata(name: string, options?: {
+    capabilities?: MemoryProviderMetadata["capabilities"];
+    relevanceRanking?: boolean;
+    backend?: Record<string, unknown>;
+}): MemoryProviderMetadata;
+
 interface CreateTaskInput {
     objective: string;
     project?: string;
@@ -1823,6 +2589,12 @@ interface CreateTaskInput {
     agent?: string;
     context?: TaskContext;
 }
+interface RunTaskOptions {
+    /** Total attempts (1 = no automatic retry). Retries apply to retryable errors only. */
+    maxAttempts?: number;
+    /** Linear backoff base in ms: waits backoffMs × attempt between attempts. */
+    retryBackoffMs?: number;
+}
 interface TaskEngineOptions {
     agents: AgentRegistry;
     roles: RoleRegistry;
@@ -1840,10 +2612,12 @@ declare class TaskEngine {
     get store(): TaskStore;
     create(input: CreateTaskInput): Promise<Task>;
     queue(id: string): Promise<Task>;
-    /** Runs the task through its assigned agent and records the result. */
-    run(id: string): Promise<Task>;
+    /** Runs the task through its assigned agent and records the result.
+     *  `maxAttempts` enables bounded automatic retries of *retryable* errors
+     *  with linear backoff; unknown/timed_out outcomes are never auto-retried. */
+    run(id: string, options?: RunTaskOptions): Promise<Task>;
     cancel(id: string): Promise<Task>;
-    /** Error recovery (§27 Phase 9): reset a failed/cancelled task so it can run again. */
+    /** Error recovery: reset a failed/cancelled/unknown/timed_out task so it can run again. */
     retry(id: string): Promise<Task>;
     get(id: string): Promise<Task | undefined>;
     list(filter?: TaskStoreFilter): Promise<Task[]>;
@@ -1902,12 +2676,24 @@ interface CombinedMeta {
     pipelineRunId?: string;
     taskIds?: string[];
 }
+interface CollectionDiagnostics {
+    collected: number;
+    accepted: number;
+    rejected: Array<{
+        key: string;
+        reason: string;
+        issues: string[];
+    }>;
+}
 declare class ReportService {
     private readonly store;
     private readonly log;
+    /** Rejected reports from the last collection (§13 — malformed never enters aggregation). */
+    lastDiagnostics: CollectionDiagnostics;
     constructor(store: ReportStore, log?: Logger);
     get storeRef(): ReportStore;
-    /** Normalizes finished tasks into reports (§17 — normalizer). */
+    /** Normalizes finished tasks into reports (§17 — normalizer), validating each
+     *  one so malformed reports never reach aggregation (§13). */
     collectFromTasks(tasks: Task[]): Promise<Report[]>;
     saveReports(reports: Report[]): Promise<void>;
     generateCombined(reports: Report[], meta?: CombinedMeta): Promise<CombinedReport | undefined>;
@@ -1935,18 +2721,49 @@ interface AggregateOptions {
     similarityThreshold?: number;
 }
 declare function aggregateReports(reports: Report[], options?: AggregateOptions): CombinedReport;
+/**
+ * Conflict detection (§14): agents disagreeing about the same finding is a
+ * first-class result. Both positions are preserved — OmniNode never silently
+ * chooses one.
+ */
+declare function detectConflicts(groups: AggregatedFinding[]): ReportConflict[];
 declare function similar(a: string, b: string, threshold: number): boolean;
 
+interface ReportValidationIssue {
+    path: string;
+    message: string;
+}
+type ReportValidationResult = {
+    valid: true;
+    report: Report;
+} | {
+    valid: false;
+    issues: ReportValidationIssue[];
+    reason: string;
+};
+/** Validates (and normalizes) a report; malformed reports are rejected. */
+declare function validateReport(value: unknown): ReportValidationResult;
+/** Normalizes evidence entries (strings or objects) to typed evidence. */
+declare function normalizeEvidence(input: EvidenceInput[] | undefined): Evidence[] | undefined;
+declare function normalizeFinding(finding: Finding): Finding;
+
 /** Planner interface and request contract (§18). The planner is replaceable. */
 
 interface PlanRequest {
+    /** The original task (§15, Planner Input). */
     objective: string;
-    /** Raw reports (already normalized) the plan is based on. */
+    /** Project context (repository/workspace background, role-derived context…). */
+    projectContext?: string;
+    /** Agent reports the plan is based on. */
     reports: Report[];
+    /** Aggregated findings (combined report) — consensus and conflicts made explicit. */
+    aggregated?: CombinedReport;
     /** Combined research context from upstream pipeline steps, if available. */
     context?: string;
     role?: RoleDefinition;
     memory?: MemoryEntry[];
+    /** Constraints the plan must respect. */
+    constraints?: string[];
     project?: string;
     taskId?: string;
     pipelineRunId?: string;
@@ -1957,10 +2774,9 @@ interface IPlanner {
 }
 
 /**
- * Planner context builder (§18): assembles everything the planner needs —
- * the objective, the combined findings from the AI reports (with source
- * attribution), relevant memory and the role definition — into one
- * structured text.
+ * Planner context builder (§15, Planner Input): assembles the original task,
+ * project context, agent reports, aggregated findings, relevant memory and
+ * constraints into one structured input, in that order.
  */
 
 declare function buildPlannerContext(request: PlanRequest): string;
@@ -1987,13 +2803,108 @@ declare class ModelPlanner implements IPlanner {
     plan(request: PlanRequest): Promise<Plan>;
     private degrade;
 }
-/** Extracts and validates the plan JSON from arbitrary model output. */
-declare function parsePlanJson(text: string): {
+type PlanJsonResult = {
+    ok: true;
+    goal: string;
     summary: string;
     steps: PlanStep[];
     risks?: string[];
     notes?: string[];
-} | undefined;
+} | {
+    ok: false;
+    reason: string;
+    issues: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/** Extracts and validates plan JSON from arbitrary model output (§15). */
+declare function parsePlanJson(text: string): PlanJsonResult;
+
+/**
+ * Plan validation (roadmap §15, Validation): every generated plan passes
+ * schema validation. Invalid plans are rejected with structured issues and
+ * — where a fallback is configured — fall back to heuristic planning.
+ */
+
+declare const planJsonSchema: z.ZodObject<{
+    goal: z.ZodString;
+    summary: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+        targets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        acceptance_criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        source_findings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        id?: string | undefined;
+        description?: string | undefined;
+        depends_on?: string[] | undefined;
+        order?: number | undefined;
+        targets?: string[] | undefined;
+        acceptance_criteria?: string[] | undefined;
+        source_findings?: string[] | undefined;
+    }, {
+        title: string;
+        id?: string | undefined;
+        description?: string | undefined;
+        depends_on?: string[] | undefined;
+        order?: number | undefined;
+        targets?: string[] | undefined;
+        acceptance_criteria?: string[] | undefined;
+        source_findings?: string[] | undefined;
+    }>, "many">;
+    risks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    steps: {
+        title: string;
+        id?: string | undefined;
+        description?: string | undefined;
+        depends_on?: string[] | undefined;
+        order?: number | undefined;
+        targets?: string[] | undefined;
+        acceptance_criteria?: string[] | undefined;
+        source_findings?: string[] | undefined;
+    }[];
+    summary: string;
+    goal: string;
+    risks?: string[] | undefined;
+    notes?: string[] | undefined;
+}, {
+    steps: {
+        title: string;
+        id?: string | undefined;
+        description?: string | undefined;
+        depends_on?: string[] | undefined;
+        order?: number | undefined;
+        targets?: string[] | undefined;
+        acceptance_criteria?: string[] | undefined;
+        source_findings?: string[] | undefined;
+    }[];
+    summary: string;
+    goal: string;
+    risks?: string[] | undefined;
+    notes?: string[] | undefined;
+}>;
+interface PlanValidationIssue {
+    path: string;
+    message: string;
+}
+type PlanValidationResult = {
+    valid: true;
+    plan: Plan;
+} | {
+    valid: false;
+    issues: PlanValidationIssue[];
+    reason: string;
+};
+/** Validates a plan object (ids/order filled by the caller). */
+declare function validatePlan(plan: Plan): PlanValidationResult;
 
 /**
  * Plan persistence (§27 Phase 8 — planner result storage). Same
@@ -2060,11 +2971,19 @@ interface RunPipelineOptions {
     objective?: string;
     onStep?: (stepRun: PipelineStepRun) => void;
 }
-declare class PipelineEngine {
+declare class PipelineEngine implements IPipelineExecutor {
     private readonly options;
     private readonly log;
+    /** Runs executing in THIS process — cancellation can terminate them directly. */
+    private readonly activeRuns;
     constructor(options: PipelineEngineOptions);
     get store(): PipelineRunStore;
+    /**
+     * Saves the run while preserving fields that may be set by another process
+     * (e.g. a cancellation request) — an in-memory snapshot must never clobber
+     * externally requested cancellation (§9.2).
+     */
+    private persist;
     /** Structural + semantic validation (§27 Phase 5 — pipeline parser). */
     validate(def: PipelineDefinition): void;
     private assertAcyclic;
@@ -2073,13 +2992,18 @@ declare class PipelineEngine {
      * dependencies, which enable parallel branches.
      */
     private effectiveDependencies;
-    run(def: PipelineDefinition, options?: RunPipelineOptions): Promise<PipelineRun>;
+    run(def: PipelineDefinition, options?: PipelineRunOptions): Promise<PipelineRun>;
+    /** First-class cancellation (§9.2): requests cancellation and terminates
+     *  tasks that are running in this process immediately. */
+    cancel(runId: string): Promise<void>;
     get(runId: string): Promise<PipelineRun | undefined>;
     listRuns(filter?: {
         pipelineId?: string;
     }): Promise<PipelineRun[]>;
     private shouldRun;
     private executeStep;
+    /** Registers tasks created for a step as live, so cancellation can terminate them (§9.2). */
+    private trackLiveTasks;
     private executeStepOnce;
     /** Research fan-out: one task per agent, in parallel (§15). */
     private runFanOut;
@@ -2111,6 +3035,6 @@ declare class ProjectStores {
     constructor(directory?: string);
 }
 
-declare const OMNINODE_VERSION = "2.0.0-alpha.1";
+declare const OMNINODE_VERSION = "2.0.0-alpha.11";
 
-export { type AgentConfig, type AgentConfigYaml, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type AuditAction, type AuditEvent, type AuditSink, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatUsage, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, ConsoleLogSink, type CreateTaskInput, type DiscoveryResult, type EnvelopeMeta, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingSeverity, type FindingSource, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IChatProvider, type IMemoryProvider, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, LocalMemoryProvider, type LogLevel, type LogSink, Logger, type LoggerOptions, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryQuery, type MemoryScope, MemoryService, type MessageEnvelope, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunFilter, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type Plan, type PlanFilter, type PlanRequest, type PlanStep, type PlanStore, type PlannerConfigYaml, PlannerError, ProcessAgent, type Project, type ProjectConfigYaml, ProjectStores, ProtocolError, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderHealth, type ProviderStatus, type ProviderType, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportFilter, ReportService, type ReportStore, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, defaultProjectConfigYaml, expandEnvRefs, extractReportFromText, findConfigFile, isOmniNodeError, keywords, loadConfig, logger, parsePlanJson, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, registryKey, requestJson, resolveApiKey, roleConfigSchema, similar };
+export { AgentAdapterRegistry, type AgentConfig, type AgentConfigYaml, type AgentDescriptor, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type ArtifactKind, type ArtifactPayload, type AskedQuestion, type AuditAction, type AuditEvent, type AuditSink, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatStreamChunk, type ChatUsage, type CollectionDiagnostics, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, type ConflictPosition, ConsoleLogSink, type CreateTaskInput, type CwdValidation, DEFAULT_MAX_OUTPUT_BYTES, type DecodeResult, type DiscoveryResult, type EnvPolicy, type EnvelopeMeta, type Evidence, type EvidenceInput, type EvidenceKind, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingOrigin, type FindingSeverity, type FindingSource, type HelloResult, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IAgentAdapter, type IChatProvider, type IMemoryProvider, type IPipelineExecutor, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, LocalMemoryProvider, type LogLevel, type LogSink, Logger, type LoggerOptions, MAX_CONTEXT_CHARS, MAX_MESSAGE_BYTES, type MemoryCategory, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryProviderMetadata, type MemoryQuery, type MemoryScope, MemoryService, type MemoryServiceOptions, type MemoryTaskContext, type MessageEnvelope, type Modality, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, PROTOCOL_V2, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunAttempt, type PipelineRunFilter, type PipelineRunOptions, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type Plan, type PlanFilter, type PlanJsonResult, type PlanRequest, type PlanStep, type PlanStore, type PlanValidationIssue, type PlanValidationResult, type PlannerConfigYaml, PlannerError, ProcessAgent, ProcessAgentAdapter, type Project, type ProjectConfigYaml, ProjectStores, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderAuthentication, type ProviderCapability, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderErrorKind, type ProviderHealth, type ProviderStatus, type ProviderType, type QuestionPayload, type QuestionResponder, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportArtifact, type ReportConflict, type ReportFilter, type ReportPayload, ReportService, type ReportStore, type ReportValidationIssue, type ReportValidationResult, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, SUPPORTED_PROTOCOL_VERSIONS, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskPayload, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, decodeStream, defaultMetadata, defaultProjectConfigYaml, defaultSearch, describeExit, detectConflicts, encodeMessage, envelope, expandEnvRefs, extractMessage, extractReportFromText, findConfigFile, isNetworkError, isOmniNodeError, isRetryable, isSupportedProtocol, isTimeoutError, keywords, killTree, kindFromStatus, loadConfig, logger, newMessageId, normalizeEvidence, normalizeFinding, parseHello, parsePlanJson, parseRetryAfter, pipelineConfigSchema, pipelineStepConfigSchema, planJsonSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, providerHttpError, providerTransportError, registryKey, requestJson, requireCompletion, resolveApiKey, resolveEnvPolicy, roleConfigSchema, sanitizeChunk, similar, validateEnvelope, validatePlan, validateReport, validateWorkingDirectory };