@hilbras/omninode 2.0.0-alpha.2 → 2.0.0-alpha.20

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,95 @@ 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 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 +261,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 +293,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 +312,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 +365,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,14 +444,25 @@ 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>;
 }
@@ -265,6 +505,24 @@ interface TaskResult {
     reportId?: string;
     /** Structured reports produced by protocol-mode agents (Phase 6 builds on this). */
     reports?: Report[];
+    /** Protocol-mode diagnostics (descriptor, questions, violations) — see docs/PROTOCOL.md. */
+    protocol?: {
+        protocol: string;
+        legacy: boolean;
+        descriptor?: {
+            protocol: string;
+            name: string;
+            version?: string;
+            capabilities: string[];
+            supports: string[];
+        };
+        questions: Array<{
+            questionId: string;
+            question: string;
+            answer?: string;
+        }>;
+        violations: string[];
+    };
     /** Truncated verbatim agent output, kept for report extraction and audit. */
     rawOutput?: string;
     error?: string;
@@ -273,6 +531,8 @@ interface TaskResult {
 interface Task {
     id: string;
     project?: string;
+    /** Pipeline run that owns this task, when created by a pipeline. */
+    pipelineId?: string;
     objective: string;
     /** Role id from the role system. */
     role?: string;
@@ -308,6 +568,8 @@ interface PipelineStep {
     dependsOn?: string[];
     condition?: PipelineStepCondition;
     retries?: number;
+    /** Constraints handed to the planner for plan steps (§15). */
+    constraints?: string[];
 }
 interface PipelineDefinition {
     id: string;
@@ -324,18 +586,37 @@ interface PipelineDefinition {
  * 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;
@@ -350,6 +631,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). */
@@ -369,6 +672,8 @@ interface PlanStep {
 interface Plan {
     id: string;
     objective: string;
+    /** Explicit goal statement (§15, Planner Output). */
+    goal?: string;
     summary: string;
     steps: PlanStep[];
     risks?: string[];
@@ -490,7 +795,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;
@@ -501,6 +819,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>;
 }
@@ -514,21 +836,37 @@ 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). */
-type OmniNodeErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "PROVIDER_NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "PROVIDER_AUTH_FAILED" | "MODEL_NOT_FOUND" | "AGENT_NOT_FOUND" | "AGENT_FAILED" | "AGENT_TIMEOUT" | "TASK_INVALID" | "TASK_NOT_FOUND" | "TASK_FAILED" | "PIPELINE_NOT_FOUND" | "PIPELINE_INVALID" | "PIPELINE_FAILED" | "PLANNER_FAILED" | "PLAN_INVALID" | "PROTOCOL_VIOLATION" | "MEMORY_UNAVAILABLE" | "REPORT_NOT_FOUND" | "NOT_IMPLEMENTED" | "CLI_USAGE" | "INTERNAL";
+type OmniNodeErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "PROVIDER_NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "PROVIDER_AUTH_FAILED" | "MODEL_NOT_FOUND" | "AGENT_NOT_FOUND" | "AGENT_FAILED" | "AGENT_TIMEOUT" | "TASK_INVALID" | "TASK_NOT_FOUND" | "TASK_FAILED" | "PIPELINE_NOT_FOUND" | "PIPELINE_INVALID" | "PIPELINE_FAILED" | "PLANNER_FAILED" | "PLAN_INVALID" | "TASK_NOT_FOUND" | "PROVIDER_NOT_FOUND" | "PROTOCOL_VIOLATION" | "MEMORY_UNAVAILABLE" | "REPORT_NOT_FOUND" | "NOT_IMPLEMENTED" | "CLI_USAGE" | "INTERNAL";
 interface OmniNodeErrorOptions {
     cause?: unknown;
     details?: Record<string, unknown>;
@@ -577,14 +915,18 @@ declare class ConsoleLogSink implements LogSink {
     constructor(stream?: WritableLike);
     write(_level: LogLevel, line: string): void;
 }
+type LogFormat = "text" | "json";
 interface LoggerOptions {
     level?: LogLevel;
     sink?: LogSink;
+    /** "text" (default) or machine-readable "json" lines (roadmap §18). */
+    format?: LogFormat;
     /** Structured fields attached to every line, e.g. { component: "config" }. */
     context?: Record<string, unknown>;
 }
 declare class Logger {
-    private readonly level;
+    level: LogLevel;
+    format: LogFormat;
     private readonly sink;
     private readonly context;
     constructor(options?: LoggerOptions);
@@ -597,6 +939,11 @@ declare class Logger {
 }
 /** Default application logger. Writes to stderr so stdout stays clean for CLI output. */
 declare const logger: Logger;
+/** Applies configuration (level/format) to the default logger — used by the CLI. */
+declare function configureLogger(options: {
+    level?: LogLevel;
+    format?: LogFormat;
+}): void;
 
 /**
  * Configuration schema. The project file (omninode.yaml) uses snake_case keys
@@ -609,6 +956,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>>;
@@ -616,18 +964,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;
@@ -640,29 +990,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;
@@ -701,6 +1066,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";
@@ -710,6 +1077,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";
@@ -719,6 +1087,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;
@@ -734,6 +1103,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";
@@ -743,6 +1114,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";
@@ -752,6 +1124,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;
@@ -764,9 +1137,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;
@@ -779,9 +1153,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<{
@@ -804,6 +1179,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>>;
@@ -811,18 +1187,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;
@@ -835,29 +1213,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;
@@ -901,6 +1294,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";
@@ -910,6 +1305,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";
@@ -919,6 +1315,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;
@@ -931,9 +1328,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;
@@ -946,9 +1344,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<{
@@ -968,37 +1367,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;
@@ -1021,9 +1430,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?: {
@@ -1035,29 +1445,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;
@@ -1080,9 +1497,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?: {
@@ -1094,9 +1512,14 @@ 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<{
+    /** Active profile; overlays live under `profiles` (§16). */
+    profile: z.ZodOptional<z.ZodString>;
+    /** Named partial overlays, e.g. development/production/testing. */
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     project: z.ZodObject<{
         name: z.ZodString;
         providers: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1104,6 +1527,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>>;
@@ -1111,18 +1535,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;
@@ -1135,29 +1561,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;
@@ -1201,6 +1642,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";
@@ -1210,6 +1653,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";
@@ -1219,6 +1663,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;
@@ -1231,9 +1676,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;
@@ -1246,9 +1692,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<{
@@ -1268,37 +1715,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;
@@ -1321,9 +1778,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?: {
@@ -1335,29 +1793,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;
@@ -1380,9 +1845,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?: {
@@ -1394,14 +1860,18 @@ 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<{
         level: z.ZodEnum<["debug", "info", "warn", "error"]>;
+        format: z.ZodOptional<z.ZodEnum<["text", "json"]>>;
     }, "strict", z.ZodTypeAny, {
         level: "info" | "error" | "debug" | "warn";
+        format?: "text" | "json" | undefined;
     }, {
         level: "info" | "error" | "debug" | "warn";
+        format?: "text" | "json" | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
     project: {
@@ -1409,23 +1879,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;
@@ -1448,9 +1924,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?: {
@@ -1462,34 +1939,44 @@ declare const appConfigSchema: z.ZodObject<{
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     };
+    profile?: string | undefined;
+    profiles?: Record<string, unknown> | undefined;
     logging?: {
         level: "info" | "error" | "debug" | "warn";
+        format?: "text" | "json" | undefined;
     } | undefined;
 }, {
     project: {
         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;
@@ -1512,9 +1999,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?: {
@@ -1526,20 +2014,36 @@ declare const appConfigSchema: z.ZodObject<{
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     };
+    profile?: string | undefined;
+    profiles?: Record<string, unknown> | undefined;
     logging?: {
         level: "info" | "error" | "debug" | "warn";
+        format?: "text" | "json" | undefined;
     } | undefined;
 }>;
-type ProviderConfigYaml = z.infer<typeof providerConfigSchema>;
-type AgentConfigYaml = z.infer<typeof agentConfigSchema>;
-type RoleConfigYaml = z.infer<typeof roleConfigSchema>;
-type PipelineConfigYaml = z.infer<typeof pipelineConfigSchema>;
-type PipelineStepConfigYaml = z.infer<typeof pipelineStepConfigSchema>;
-type PlannerConfigYaml = z.infer<typeof plannerConfigSchema>;
-type ProjectConfigYaml = z.infer<typeof projectConfigSchema>;
-type AppConfigYaml = z.infer<typeof appConfigSchema>;
+
+/**
+ * Inline secret detection (roadmap §17, Secrets).
+ *
+ * OmniNode configuration must never contain literal credentials — only
+ * environment-variable *references*. This scanner runs before the config is
+ * parsed and reports anything that looks like an inline secret, so the file
+ * is rejected before it can be committed or persisted.
+ */
+interface SecretFinding {
+    /** 1-based line number in the source. */
+    line: number;
+    /** The offending key, e.g. `api_key`. */
+    key: string;
+    /** Redacted excerpt — never echoes the value. */
+    excerpt: string;
+}
+declare function scanForInlineSecrets(source: string): SecretFinding[];
+/** Formats findings as an actionable configuration error message. */
+declare function describeSecretFindings(file: string, findings: SecretFinding[]): string;
 
 interface AppConfig {
     project: {
@@ -1557,6 +2061,7 @@ interface AppConfig {
             provider: string;
             baseUrl?: string;
             apiKeyEnvVar?: string;
+            required?: boolean;
         };
     };
     logging?: {
@@ -1564,11 +2069,13 @@ interface AppConfig {
     };
 }
 interface LoadConfigOptions {
-    /** Explicit path; otherwise omninode.yaml/yml/json is looked up in the given directory. */
+    /** Explicit path (CLI --config); otherwise the project file is discovered. */
     path?: string;
     directory?: string;
-    /** Environment used for ${VAR} expansion; defaults to process.env. */
+    /** Environment used for ${VAR} expansion and OMNINODE_* overrides; defaults to process.env. */
     env?: Record<string, string | undefined>;
+    /** Profile override (CLI --profile), above environment and file selection. */
+    profile?: string;
 }
 declare function findConfigFile(directory?: string): string | undefined;
 /**
@@ -1577,7 +2084,36 @@ declare function findConfigFile(directory?: string): string | undefined;
  * authentication.
  */
 declare function expandEnvRefs(text: string, env: Record<string, string | undefined>, source?: string): string;
+interface LoadConfigResult {
+    config: AppConfig;
+    sources: ConfigSources;
+}
+/**
+ * Composes configuration from every source with the documented precedence
+ * (roadmap §16): CLI → environment → project file → user file → profile
+ * overlay → defaults.
+ */
+declare function loadConfigDetailed(options?: LoadConfigOptions): LoadConfigResult;
+/** Backwards-compatible wrapper: the composed configuration. */
 declare function loadConfig(options?: LoadConfigOptions): AppConfig;
+/**
+ * Actionable configuration diagnostics (roadmap §16) — the kind of message a
+ * user can act on, rather than a generic schema failure.
+ */
+declare function configDiagnostics(config: AppConfig): string[];
+
+interface ConfigSources {
+    /** Project-level configuration file, if any. */
+    projectFile?: string;
+    /** User-level configuration file, if any. */
+    userFile?: string;
+    /** Active profile. */
+    profile: string;
+    /** Environment variables that overrode configuration. */
+    envOverrides: string[];
+    /** Values that came from built-in defaults. */
+    defaults: string[];
+}
 
 /** Template written by `omninode init` (§22, §23). */
 declare function defaultProjectConfigYaml(projectName?: string): string;
@@ -1603,15 +2139,112 @@ interface HttpResponse {
 }
 declare function requestJson(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
 
+type AuditAction = "task.created" | "task.queued" | "task.running" | "task.completed" | "task.failed" | "task.cancelled" | "task.retry" | "pipeline.run.started" | "pipeline.run.finished" | "pipeline.run.failed" | "pipeline.run.cancelled" | "plan.generated" | "agent.started" | "agent.completed" | "provider.error" | "memory.context.gathered" | "memory.outcome.recorded";
+/**
+ * Every event carries correlation ids so a failed execution can be traced
+ * across task → execution → pipeline run → agent → provider (roadmap §18).
+ */
+interface AuditEvent {
+    at: string;
+    action: AuditAction;
+    project?: string;
+    /** Primary subject: task id, pipeline run id, plan id… */
+    id?: string;
+    taskId?: string;
+    pipelineId?: string;
+    executionId?: string;
+    agentId?: string;
+    providerId?: string;
+    actor?: string;
+    detail?: Record<string, unknown>;
+}
+interface AuditSink {
+    record(event: AuditEvent): Promise<void>;
+}
+/** Default rotation threshold: the audit log is rotated past this size (§24). */
+declare const DEFAULT_AUDIT_MAX_BYTES: number;
+/** Append-only JSONL sink. Failures are logged, never propagated. */
+declare class FileAuditLog implements AuditSink {
+    private readonly filePath;
+    private readonly maxBytes;
+    private readonly log;
+    constructor(directory?: string, log?: Logger, maxBytes?: number);
+    /** Rotates the log once it passes the size budget, keeping one backup. */
+    private rotateIfNeeded;
+    record(event: AuditEvent): Promise<void>;
+    /** Recent events, oldest first; used by the CLI. */
+    recent(limit?: number): Promise<AuditEvent[]>;
+}
+
 /** Provider types served by the OpenAI-compatible adapter. */
 declare const OPENAI_COMPATIBLE_TYPES: readonly ProviderType[];
-declare function createProvider(config: ProviderConfig): IChatProvider;
+interface CreateProviderOptions {
+    /** Correlates provider errors in the audit log (§18). */
+    audit?: AuditSink;
+    env?: Record<string, string | undefined>;
+}
+declare function createProvider(config: ProviderConfig, options?: CreateProviderOptions): 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;
+    private readonly audit?;
+    constructor(config: ProviderConfig, log?: Logger, env?: Record<string, string | undefined>, audit?: AuditSink);
+    /** 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>;
+    /** Provider errors are part of the audit trail (§14 correlation, §18 observability). */
+    private recordProviderError;
     healthCheck(): Promise<ProviderStatus>;
     chat(request: ChatRequest): Promise<ChatResponse>;
 }
@@ -1654,20 +2287,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;
@@ -1680,6 +2330,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. */
 
@@ -1695,7 +2402,13 @@ declare class AgentRegistry {
  * "cli" agent configs are mapped to the process integration by the loader.
  */
 
-declare function createAgent(config: AgentConfig): IAgent;
+/**
+ * Registry consulted first so native/API-level integrations plug in without
+ * touching core (roadmap §8, Native Adapters).
+ */
+declare const defaultAgentAdapters: AgentAdapterRegistry;
+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;
 
@@ -1711,27 +2424,64 @@ declare class RoleRegistry {
 /** Builds a role registry from the project configuration. */
 declare function buildRoleRegistry(config: AppConfig): RoleRegistry;
 
+/** Current on-disk schema version. */
+declare const SCHEMA_VERSION = 2;
 interface JsonDocument<T> {
-    /** Bumped when the persisted shape changes in a breaking way (v2 Phase 12). */
     schemaVersion?: number;
     items: T[];
 }
+type DocumentState = {
+    status: "missing";
+} | {
+    status: "empty";
+} | {
+    status: "v1-legacy";
+} | {
+    status: "current";
+    schemaVersion: number;
+    count: number;
+} | {
+    status: "future";
+    schemaVersion: number;
+} | {
+    status: "corrupt";
+    detail: string;
+};
 interface JsonFileStoreOptions {
     directory?: string;
     fileName: string;
+    /** Schema version to write (defaults to the current version). */
     schemaVersion?: number;
-    /** Called when a persisted file cannot be parsed. */
+    /** Power-loss durability: "rename" (default) or "fsync" (slower). */
+    durability?: Durability;
+    /** Called when a persisted file is corrupt (after quarantine). */
     onCorrupt?: (path: string, error: unknown) => void;
+    /** Disable file moves (used by dry runs / tests that inspect in place). */
+    quarantine?: boolean;
 }
+type Durability = "rename" | "fsync";
+/**
+ * Writes a file atomically: temp → rename. The rename guarantees readers
+ * never observe a torn file. With `durability: "fsync"` the data and the
+ * directory entry are also flushed, which additionally survives power loss —
+ * at a significant per-write cost, so it is opt-in.
+ */
+declare function writeFileAtomic(target: string, contents: string, durability?: Durability): Promise<void>;
+/** Reads and classifies a persisted document without modifying it. */
+declare function inspectDocument(path: string): Promise<DocumentState>;
+/** Reads a document, migrating v1 shapes and quarantining corruption. */
+declare function readDocument<T>(path: string, onCorrupt?: (path: string, error: unknown) => void, quarantine?: boolean): Promise<T[]>;
 declare class JsonFileStore<T> {
     private readonly filePath;
     private readonly schemaVersion;
+    private readonly durability;
     private readonly onCorrupt?;
+    private readonly quarantine;
     private readonly log;
     private queue;
     constructor(options: JsonFileStoreOptions);
     get path(): string;
-    /** All items, or [] when missing/corrupt. */
+    /** All items, or [] when missing/migrated-from-v1/corrupt. */
     protected readAll(): Promise<T[]>;
     protected writeAll(items: T[]): Promise<void>;
     /** Serializes an async operation against this file. */
@@ -1762,28 +2512,6 @@ declare class FileTaskStore extends JsonFileStore<Task> implements TaskStore {
     list(filter?: TaskStoreFilter): Promise<Task[]>;
 }
 
-type AuditAction = "task.created" | "task.queued" | "task.running" | "task.completed" | "task.failed" | "task.cancelled" | "task.retry" | "pipeline.run.started" | "pipeline.run.finished" | "plan.generated" | "memory.context.gathered" | "memory.outcome.recorded";
-interface AuditEvent {
-    at: string;
-    action: AuditAction;
-    project?: string;
-    id?: string;
-    actor?: string;
-    detail?: Record<string, unknown>;
-}
-interface AuditSink {
-    record(event: AuditEvent): Promise<void>;
-}
-/** Append-only JSONL sink. Failures are logged, never propagated. */
-declare class FileAuditLog implements AuditSink {
-    private readonly filePath;
-    private readonly log;
-    constructor(directory?: string, log?: Logger);
-    record(event: AuditEvent): Promise<void>;
-    /** Recent events, oldest first; used by the CLI. */
-    recent(limit?: number): Promise<AuditEvent[]>;
-}
-
 /**
  * Local file-based memory provider: the default implementation so persistent
  * memory works out of the box, locally (§25), with no external service.
@@ -1791,12 +2519,20 @@ declare class FileAuditLog implements AuditSink {
  * dependency-free.
  */
 
-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>;
 }
 
@@ -1812,9 +2548,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;
 }
@@ -1822,34 +2569,52 @@ 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;
 }
 
 interface CreateTaskInput {
     objective: string;
     project?: string;
+    pipelineId?: string;
     role?: string;
     agent?: string;
     context?: TaskContext;
@@ -1941,12 +2706,26 @@ interface CombinedMeta {
     pipelineRunId?: string;
     taskIds?: string[];
 }
+/** Serialized size budget for a single report (roadmap §17 — output limits). */
+declare const MAX_REPORT_BYTES: number;
+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>;
@@ -1966,26 +2745,61 @@ interface ExtractionMeta {
 }
 declare function extractReportFromText(raw: string, meta: ExtractionMeta): Report;
 
+/** Default cap on retained finding groups per combined report (§24, memory). */
+declare const MAX_COMBINED_FINDINGS = 200;
 interface AggregateOptions {
     objective?: string;
     pipelineRunId?: string;
     taskIds?: string[];
     /** Token-set Jaccard similarity above which findings are merged. */
     similarityThreshold?: number;
+    /** Cap on retained finding groups; excess is counted in metadata. */
+    maxFindings?: 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;
@@ -1996,10 +2810,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;
@@ -2026,13 +2839,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
@@ -2093,17 +3001,36 @@ interface PipelineEngineOptions {
     audit?: AuditSink;
     /** When present, finished runs have their reports collected, stored and combined (§16–§17). */
     reports?: ReportService;
+    /** Max steps executed concurrently within one wave (§24 execution-storm guard). */
+    maxParallelSteps?: number;
+    /** Combined-context budget in characters (§24 memory bound). */
+    maxContextChars?: number;
     log?: Logger;
 }
 interface RunPipelineOptions {
     objective?: string;
     onStep?: (stepRun: PipelineStepRun) => void;
 }
-declare class PipelineEngine {
+
+/** Default cap on steps running concurrently in one wave (§24). */
+declare const DEFAULT_MAX_PARALLEL_STEPS = 8;
+/** Default combined-context budget for downstream steps (§24). */
+declare const MAX_COMBINED_CONTEXT_CHARS = 20000;
+/** Keeps the most recent context within budget, marking what was dropped. */
+declare function budgetContext(context: string, maxChars?: number): string;
+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;
@@ -2112,13 +3039,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;
@@ -2127,16 +3059,19 @@ declare class PipelineEngine {
     private getChat;
 }
 /** Default chat function: resolves "provider:model" against the configured providers. */
-declare function createDefaultChatFn(providers: AppConfig["project"]["providers"]): ChatFn;
+interface DefaultChatOptions {
+    /** Correlates provider errors in the audit log (§18). */
+    audit?: AuditSink;
+    env?: Record<string, string | undefined>;
+}
+declare function createDefaultChatFn(providers: AppConfig["project"]["providers"], options?: DefaultChatOptions): ChatFn;
 
 declare function buildPipelineEngine(config: AppConfig, log?: Logger): PipelineEngine;
 
 /**
- * Persistence layer (v2 Phase 1): one entry point to every local store.
- *
- * All stores are interfaces with a local JSON default
- * (TaskStore, PipelineRunStore, ReportStore, PlanStore, IMemoryProvider,
- * AuditSink) — see docs/API.md for the inventory and stability status.
+ * Persistence layer (v2 Phase 12): one entry point to every local store,
+ * the canonical storage interface names, and the migration path that upgrades
+ * v1 data in place.
  */
 
 /** Bundles every store for a single project directory. */
@@ -2149,7 +3084,120 @@ declare class ProjectStores {
     readonly audit: FileAuditLog;
     constructor(directory?: string);
 }
+interface MigrationReport {
+    file: string;
+    state: DocumentState["status"];
+    before?: number;
+    after?: number;
+    migrated: boolean;
+    note?: string;
+}
+/**
+ * Migration (roadmap §16): inspects every store file, reports its schema
+ * state, and — unless `checkOnly` — rewrites v1 documents at the current
+ * schema version. Idempotent and safe: unknown/future versions are reported,
+ * never rewritten.
+ */
+declare function migrateProjectStores(directory?: string, options?: {
+    checkOnly?: boolean;
+}): Promise<MigrationReport[]>;
+
+/**
+ * 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[];
+}
 
-declare const OMNINODE_VERSION = "2.0.0-alpha.2";
+/**
+ * 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.
+ */
 
-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 ExecutionRecord, 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, TERMINAL_TASK_STATUSES, 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 };
+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 const OMNINODE_VERSION = "2.0.0-alpha.20";
+
+export { AgentAdapterRegistry, type AgentConfig, type AgentDescriptor, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type ArtifactPayload, type AskedQuestion, type AuditAction, type AuditEvent, type AuditSink, type AuditSink as AuditStore, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatStreamChunk, type ChatUsage, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, type ConflictPosition, ConsoleLogSink, type CreateProviderOptions, type CreateTaskInput, type CwdValidation, DEFAULT_AUDIT_MAX_BYTES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_MAX_PARALLEL_STEPS, type DecodeResult, type DefaultChatOptions, type DocumentState, type Durability, type EnvPolicy, type EnvelopeMeta, type Evidence, type EvidenceInput, type EvidenceKind, type ExecutionRecord, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingOrigin, type FindingSeverity, type FindingSource, type HelloResult, HeuristicPlanner, type IAgent, type IAgentAdapter, type IChatProvider, type IMemoryProvider, type IPipelineExecutor, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, type LoadConfigResult, LocalMemoryProvider, type LogFormat, type LogLevel, type LogSink, Logger, type LoggerOptions, MAX_COMBINED_CONTEXT_CHARS, MAX_COMBINED_FINDINGS, MAX_CONTEXT_CHARS, MAX_MESSAGE_BYTES, MAX_REPORT_BYTES, type MemoryCategory, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryProviderMetadata, type MemoryQuery, type MemoryScope, MemoryService, type MemoryServiceOptions, LocalMemoryProvider as MemoryStore, type MemoryTaskContext, type MessageEnvelope, type MigrationReport, type Modality, type ModelCapabilities, type ModelInfo, ModelPlanner, type ModelPlannerOptions, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, OmniHilbrasProvider, OmniNodeError, OpenAICompatibleProvider, PROTOCOL_V2, type PipelineDefinition, PipelineEngine, PipelineError, type PipelineRun, type PipelineRunAttempt, type PipelineRunFilter, type PipelineRunOptions, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepKind, type PipelineStepRun, type PipelineRunStore as PipelineStore, type Plan, type PlanFilter, type PlanRequest, type PlanStep, type PlanStore, type PlanValidationIssue, type PlanValidationResult, PlannerError, ProcessAgent, ProcessAgentAdapter, type Project, ProjectStores, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderAuthentication, type ProviderCapability, type ProviderConfig, ProviderError, 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 RoleDefinition, RoleRegistry, type RunPipelineOptions, type RunTaskOptions, SCHEMA_VERSION, SUPPORTED_PROTOCOL_VERSIONS, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, budgetContext, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, configDiagnostics, configureLogger, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, defaultAgentAdapters, defaultProjectConfigYaml, describeExit, describeSecretFindings, detectConflicts, encodeMessage, envelope, expandEnvRefs, extractMessage, extractReportFromText, findConfigFile, inspectDocument, isNetworkError, isOmniNodeError, isRetryable, isSupportedProtocol, isTimeoutError, killTree, kindFromStatus, loadConfig, loadConfigDetailed, logger, migrateProjectStores, newMessageId, normalizeEvidence, normalizeFinding, parseHello, parsePlanJson, parseRetryAfter, pipelineConfigSchema, pipelineStepConfigSchema, planJsonSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, providerHttpError, providerTransportError, readDocument, registryKey, requestJson, resolveApiKey, resolveEnvPolicy, roleConfigSchema, sanitizeChunk, scanForInlineSecrets, similar, validateEnvelope, validatePlan, validateReport, validateWorkingDirectory, writeFileAtomic };