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

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.1";
+var OMNINODE_VERSION = "2.0.0-alpha.11";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -44,11 +44,6 @@ var PipelineError = class extends OmniNodeError {
     super(code, message, options);
   }
 };
-var ProtocolError = class extends OmniNodeError {
-  constructor(message, options = {}) {
-    super("PROTOCOL_VIOLATION", message, options);
-  }
-};
 var PlannerError = class extends OmniNodeError {
   constructor(code, message, options = {}) {
     super(code, message, options);
@@ -73,6 +68,7 @@ var providerConfigSchema = z.object({
   type: z.enum(["openai-compatible", "omnihilbras", "openrouter", "local", "custom"]),
   base_url: z.string().url(),
   api_key_env_var: z.string().min(1).optional(),
+  timeout_ms: z.number().int().positive().optional(),
   headers: z.record(z.string()).optional(),
   enabled: z.boolean().optional(),
   metadata: z.record(z.unknown()).optional()
@@ -88,6 +84,11 @@ var agentConfigSchema = z.object({
   input_mode: z.enum(["stdin", "arg", "protocol"]).default("stdin"),
   timeout_ms: z.number().int().positive().optional(),
   inherit_env: z.boolean().optional(),
+  env_policy: z.enum(["inherit", "allowlist", "denylist", "explicit"]).optional(),
+  env_allowlist: z.array(z.string()).optional(),
+  env_denylist: z.array(z.string()).optional(),
+  max_output_bytes: z.number().int().positive().optional(),
+  allow_external_cwd: z.boolean().optional(),
   metadata: z.record(z.unknown()).optional()
 }).strict();
 var roleConfigSchema = z.object({
@@ -108,7 +109,9 @@ var pipelineStepConfigSchema = z.object({
   model: z.string().optional(),
   depends_on: z.array(z.string()).optional(),
   retries: z.number().int().min(0).max(10).optional(),
-  condition: z.enum(["always", "on-success", "on-failure"]).optional()
+  condition: z.enum(["always", "on-success", "on-failure"]).optional(),
+  /** Constraints passed to the planner for plan steps (§15). */
+  constraints: z.array(z.string()).optional()
 }).strict();
 var pipelineConfigSchema = z.object({
   id: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "pipeline id must be kebab-case"),
@@ -132,7 +135,9 @@ var projectConfigSchema = z.object({
   memory: z.object({
     provider: z.string().min(1).default("local"),
     base_url: z.string().url().optional(),
-    api_key_env_var: z.string().min(1).optional()
+    api_key_env_var: z.string().min(1).optional(),
+    /** When true, memory failures fail tasks instead of being tolerated (§12). */
+    required: z.boolean().optional()
   }).strict().optional()
 }).strict();
 var appConfigSchema = z.object({
@@ -214,7 +219,8 @@ function toAppConfig(yaml) {
         memory: {
           provider: yaml.project.memory.provider,
           baseUrl: yaml.project.memory.base_url,
-          apiKeyEnvVar: yaml.project.memory.api_key_env_var
+          apiKeyEnvVar: yaml.project.memory.api_key_env_var,
+          required: yaml.project.memory.required
         }
       } : {}
     },
@@ -235,7 +241,8 @@ function toPipelineDefinition(raw) {
       model: step.model,
       dependsOn: step.depends_on,
       retries: step.retries,
-      condition: step.condition
+      condition: step.condition,
+      constraints: step.constraints
     }))
   };
 }
@@ -245,6 +252,7 @@ function toProviderConfig(raw) {
     type: raw.type,
     baseUrl: raw.base_url,
     apiKeyEnvVar: raw.api_key_env_var,
+    timeoutMs: raw.timeout_ms,
     headers: raw.headers,
     enabled: raw.enabled,
     metadata: raw.metadata
@@ -262,6 +270,11 @@ function toAgentConfig(raw) {
     inputMode: raw.input_mode,
     timeoutMs: raw.timeout_ms,
     inheritEnv: raw.inherit_env,
+    envPolicy: raw.env_policy,
+    envAllowlist: raw.env_allowlist,
+    envDenylist: raw.env_denylist,
+    maxOutputBytes: raw.max_output_bytes,
+    allowExternalCwd: raw.allow_external_cwd,
     metadata: raw.metadata
   };
 }
@@ -358,35 +371,32 @@ function authHeaders(config, env = process.env) {
 }
 
 // src/providers/http.ts
+var HttpResponseError = class extends Error {
+  constructor(message, status, cause) {
+    super(message, { cause });
+    this.status = status;
+    this.name = "HttpResponseError";
+  }
+  status;
+};
 var DEFAULT_TIMEOUT_MS = 3e4;
 async function requestJson(url, options = {}) {
   const { method = "GET", headers = {}, body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
-  let response;
-  try {
-    response = await fetch(url, {
-      method,
-      headers: {
-        accept: "application/json",
-        ...body !== void 0 ? { "content-type": "application/json" } : {},
-        ...headers
-      },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {},
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-  } catch (error) {
-    const reason = error instanceof Error && error.name === "TimeoutError" ? `timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : String(error);
-    throw new ProviderError("PROVIDER_UNAVAILABLE", `Request to ${url} failed: ${reason}.`, {
-      cause: error
-    });
-  }
+  const response = await fetch(url, {
+    method,
+    headers: {
+      accept: "application/json",
+      ...body !== void 0 ? { "content-type": "application/json" } : {},
+      ...headers
+    },
+    ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+    signal: AbortSignal.timeout(timeoutMs)
+  });
   let parsed;
   try {
     parsed = await response.json();
   } catch (error) {
-    throw new ProviderError("PROVIDER_UNAVAILABLE", `Response from ${url} was not valid JSON.`, {
-      cause: error,
-      details: { status: response.status }
-    });
+    throw new HttpResponseError(`Response from ${url} was not valid JSON.`, response.status, error);
   }
   return { status: response.status, body: parsed };
 }
@@ -447,24 +457,167 @@ var Logger = class _Logger {
 };
 var logger = new Logger();
 
+// src/providers/errors.ts
+function kindToCode(kind) {
+  switch (kind) {
+    case "AUTHENTICATION_ERROR":
+      return "PROVIDER_AUTH_FAILED";
+    case "MODEL_NOT_FOUND":
+      return "MODEL_NOT_FOUND";
+    default:
+      return "PROVIDER_UNAVAILABLE";
+  }
+}
+function isRetryable(kind) {
+  return kind === "RATE_LIMIT_ERROR" || kind === "SERVER_ERROR" || kind === "NETWORK_ERROR";
+}
+function kindFromStatus(status) {
+  if (status === 401 || status === 403) return "AUTHENTICATION_ERROR";
+  if (status === 429) return "RATE_LIMIT_ERROR";
+  if (status === 404) return "MODEL_NOT_FOUND";
+  if (status === 408 || status === 504) return "TIMEOUT";
+  if (status >= 500) return "SERVER_ERROR";
+  if (status >= 400) return "INVALID_REQUEST";
+  return "UNKNOWN_ERROR";
+}
+function extractMessage(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const root = body;
+  const error = root.error ?? root;
+  const message = error.message ?? error.detail ?? root.message;
+  return typeof message === "string" ? message : void 0;
+}
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+function isTimeoutError(error) {
+  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError") || typeof error?.code === "string" && error.code === "ABORT_ERR";
+}
+function fallbackMessage(kind, context, status) {
+  const { provider, operation } = context;
+  switch (kind) {
+    case "AUTHENTICATION_ERROR":
+      return `Authentication with provider "${provider}" failed (HTTP ${status}). Check that the referenced API key is set and valid.`;
+    case "RATE_LIMIT_ERROR":
+      return `Provider "${provider}" rate-limited ${operation} (HTTP ${status}). Retry later.`;
+    case "MODEL_NOT_FOUND":
+      return `Provider "${provider}" does not expose the requested model (HTTP ${status}).`;
+    case "TIMEOUT":
+      return `Provider "${provider}" timed out during ${operation} (HTTP ${status}).`;
+    case "SERVER_ERROR":
+      return `Provider "${provider}" returned a server error during ${operation} (HTTP ${status}).`;
+    case "INVALID_REQUEST":
+      return `Provider "${provider}" rejected ${operation} as invalid (HTTP ${status}).`;
+    default:
+      return `Provider "${provider}" failed during ${operation} (HTTP ${status}).`;
+  }
+}
+function providerHttpError(context) {
+  const status = context.status ?? 0;
+  const kind = kindFromStatus(status);
+  const detail = extractMessage(context.body);
+  const retryAfterMs = context.retryAfterMs ?? parseRetryAfter(void 0);
+  return new ProviderError(
+    context.code ?? kindToCode(kind),
+    detail ?? fallbackMessage(kind, context, status),
+    {
+      cause: context.cause,
+      details: {
+        kind,
+        provider: context.provider,
+        operation: context.operation,
+        status,
+        retryable: isRetryable(kind),
+        ...retryAfterMs !== void 0 ? { retryAfterMs } : {},
+        ...detail ? { providerMessage: detail } : {}
+      }
+    }
+  );
+}
+function providerTransportError(context) {
+  const cause = context.cause;
+  const kind = isTimeoutError(cause) ? "TIMEOUT" : cause instanceof SyntaxError || cause?.name === "HttpResponseError" ? "UNKNOWN_ERROR" : "NETWORK_ERROR";
+  const message = context.cause instanceof Error ? context.cause.message : String(context.cause);
+  return new ProviderError("PROVIDER_UNAVAILABLE", `Provider request failed: ${message}`, {
+    cause: context.cause,
+    details: {
+      kind,
+      provider: context.provider,
+      operation: context.operation,
+      retryable: isRetryable(kind)
+    }
+  });
+}
+
 // src/providers/openai-compatible/index.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var OpenAICompatibleProvider = class {
   config;
+  providerId;
+  authentication;
   log;
-  constructor(config, log = logger) {
+  /** Discovered models, so getModel() answers without another round-trip. */
+  discovered;
+  env;
+  constructor(config, log = logger, env = process.env) {
     this.config = { ...config, baseUrl: normalizeBaseUrl(config.baseUrl) };
+    this.env = env;
+    this.providerId = config.providerId ?? config.name;
+    this.authentication = {
+      method: config.apiKeyEnvVar ? "bearer" : "none",
+      ...config.apiKeyEnvVar ? { envVar: config.apiKeyEnvVar } : {},
+      configured: config.apiKeyEnvVar ? Boolean(env[config.apiKeyEnvVar]) : true
+    };
     this.log = log.child({ provider: config.name });
   }
-  async listModels() {
-    const { status, body } = await requestJson(`${this.config.baseUrl}/models`, {
-      headers: authHeaders(this.config)
-    });
-    if (status === 401 || status === 403) {
-      throw authFailed(this.config, status);
+  /** Provider-level request timeout (roadmap §6.6/§11) with the shared default. */
+  get requestTimeoutMs() {
+    return this.config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  /** Authenticate + discover (roadmap §10, Model Discovery). */
+  async connect() {
+    authHeaders(this.config, this.env);
+    const models = await this.listModels();
+    this.discovered = models;
+    return models;
+  }
+  async getModel(modelId) {
+    const models = this.discovered ?? await this.connect();
+    return models.find((m) => m.id === modelId);
+  }
+  /** Raw /models body (protected so adapters can capture gateway-level metadata). */
+  async rawModelsResponse() {
+    const response = await this.modelsRequest();
+    return response.body;
+  }
+  async modelsRequest() {
+    let response;
+    try {
+      response = await requestJson(`${this.config.baseUrl}/models`, {
+        headers: authHeaders(this.config, this.env),
+        timeoutMs: this.requestTimeoutMs
+      });
+    } catch (error) {
+      if (error instanceof ProviderError) throw error;
+      throw providerTransportError({ provider: this.config.name, operation: "listModels", cause: error });
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Model discovery returned HTTP ${status}.`, status);
+      throw providerHttpError({
+        provider: this.config.name,
+        operation: "listModels",
+        status,
+        body
+      });
     }
+    return response;
+  }
+  async listModels() {
+    const body = await this.rawModelsResponse();
     const entries = extractModelEntries(body, this.config);
     const models = [];
     let skipped = 0;
@@ -473,22 +626,44 @@ var OpenAICompatibleProvider = class {
         skipped += 1;
         continue;
       }
-      models.push({
-        provider: this.config.name,
-        id: entry2.id,
-        displayName: entry2.id,
-        status: "available",
-        metadata: {
-          ...typeof entry2.owned_by === "string" ? { ownedBy: entry2.owned_by } : {},
-          ...typeof entry2.created === "number" ? { createdAt: entry2.created } : {}
-        }
-      });
+      models.push(this.toModelInfo(entry2));
     }
     if (skipped > 0) {
       this.log.warn(`Skipped ${skipped} model entr(y/ies) without a valid id.`);
     }
     return models;
   }
+  /** Maps a raw model entry onto the normalized metadata shape (§10). */
+  toModelInfo(entry2) {
+    const parameters = Array.isArray(entry2.supported_parameters) ? entry2.supported_parameters.filter((p) => typeof p === "string") : void 0;
+    const contextWindow = typeof entry2.context_length === "number" ? entry2.context_length : typeof entry2.context_window === "number" ? entry2.context_window : void 0;
+    const inputTypes = normalizeModalities(entry2.input_modalities);
+    const outputTypes = normalizeModalities(entry2.output_modalities);
+    return {
+      provider: this.config.name,
+      id: entry2.id,
+      displayName: entry2.id,
+      ...typeof entry2.name === "string" ? { name: entry2.name } : {},
+      status: "available",
+      ...contextWindow !== void 0 ? { contextWindow } : {},
+      ...inputTypes !== void 0 ? { inputTypes } : {},
+      ...outputTypes !== void 0 ? { outputTypes } : {},
+      ...parameters !== void 0 ? {
+        supportsTools: parameters.includes("tools") || parameters.includes("tool_choice"),
+        supportsStructuredOutput: parameters.includes("response_format"),
+        supportsStreaming: parameters.includes("stream")
+      } : {},
+      metadata: {
+        ...typeof entry2.owned_by === "string" ? { ownedBy: entry2.owned_by } : {},
+        ...typeof entry2.created === "number" ? { createdAt: entry2.created } : {},
+        ...parameters !== void 0 ? { supportedParameters: parameters } : {}
+      }
+    };
+  }
+  /** Streaming where the gateway supports it (§11). */
+  stream(request, onChunk) {
+    return streamChatCompletion(this.config, request, onChunk, this.env);
+  }
   async healthCheck() {
     const lastCheckedAt = (/* @__PURE__ */ new Date()).toISOString();
     try {
@@ -518,27 +693,35 @@ var OpenAICompatibleProvider = class {
     }
   }
   async chat(request) {
-    const { status, body } = await requestJson(`${this.config.baseUrl}/chat/completions`, {
-      method: "POST",
-      headers: authHeaders(this.config),
-      body: {
-        model: request.model,
-        messages: request.messages,
-        ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
-        ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {},
-        ...request.stop !== void 0 ? { stop: request.stop } : {}
-      }
-    });
-    if (status === 401 || status === 403) throw authFailed(this.config, status);
-    if (status === 404) {
-      throw new ProviderError(
-        "MODEL_NOT_FOUND",
-        `Model "${request.model}" or the chat endpoint was not found on provider "${this.config.name}" (HTTP 404).`,
-        { details: { status } }
-      );
+    let response;
+    try {
+      response = await requestJson(`${this.config.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: authHeaders(this.config, this.env),
+        timeoutMs: this.requestTimeoutMs,
+        body: {
+          model: request.model,
+          messages: request.messages,
+          ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+          ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {},
+          ...request.stop !== void 0 ? { stop: request.stop } : {}
+        }
+      });
+    } catch (error) {
+      if (error instanceof ProviderError) throw error;
+      throw providerTransportError({ provider: this.config.name, operation: "chat", cause: error });
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Chat completion returned HTTP ${status}.`, status);
+      throw providerHttpError({
+        provider: this.config.name,
+        operation: "chat",
+        status,
+        body,
+        ...status === 404 ? {
+          code: "MODEL_NOT_FOUND"
+        } : {}
+      });
     }
     const payload = body;
     const choices = Array.isArray(payload.choices) ? payload.choices : [];
@@ -560,6 +743,81 @@ var OpenAICompatibleProvider = class {
     };
   }
 };
+async function streamChatCompletion(config, request, onChunk, env = process.env) {
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  let response;
+  try {
+    response = await fetch(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        accept: "text/event-stream",
+        "content-type": "application/json",
+        ...authHeaders(config, env)
+      },
+      body: JSON.stringify({
+        model: request.model,
+        messages: request.messages,
+        stream: true,
+        ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+        ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {}
+      }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    throw providerTransportError({ provider: config.name, operation: "stream", cause: error });
+  }
+  if (!response.ok) {
+    const body = await response.json().catch(() => void 0);
+    throw providerHttpError({ provider: config.name, operation: "stream", status: response.status, body });
+  }
+  if (!response.body) {
+    throw providerHttpError({
+      provider: config.name,
+      operation: "stream",
+      status: 500,
+      body: { error: { message: "streaming is not supported by this endpoint" } }
+    });
+  }
+  let content = "";
+  let model = request.model;
+  let finishReason;
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const piece of response.body) {
+    buffer += decoder.decode(piece, { stream: true });
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+      if (line.length === 0 || line.startsWith(":")) continue;
+      const data = line.startsWith("data:") ? line.slice(5).trim() : line;
+      if (data === "[DONE]") continue;
+      let event;
+      try {
+        event = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (typeof event.model === "string") model = event.model;
+      const choices = Array.isArray(event.choices) ? event.choices : [];
+      const first = choices[0];
+      const delta = typeof first?.delta?.content === "string" ? first.delta.content : "";
+      if (delta.length > 0) content += delta;
+      if (typeof first?.finish_reason === "string") finishReason = first.finish_reason;
+      onChunk({ delta, ...finishReason !== void 0 ? { finishReason } : {}, raw: event });
+    }
+  }
+  return { model, content, ...finishReason !== void 0 ? { finishReason } : {} };
+}
+function normalizeModalities(value) {
+  const list = Array.isArray(value) ? value : typeof value === "string" ? [value] : void 0;
+  if (!list) return void 0;
+  const allowed = /* @__PURE__ */ new Set(["text", "image", "audio", "video", "embedding"]);
+  const modalities = list.filter((m) => typeof m === "string" && allowed.has(m));
+  return modalities.length > 0 ? modalities : void 0;
+}
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
@@ -574,14 +832,6 @@ function extractModelEntries(body, config) {
     { details: { endpoint: "models" } }
   );
 }
-function authFailed(config, status) {
-  const envHint = config.apiKeyEnvVar ? ` Check that $${config.apiKeyEnvVar} is set and valid.` : " The provider requires authentication; configure api_key_env_var for it.";
-  return new ProviderError(
-    "PROVIDER_AUTH_FAILED",
-    `Authentication with provider "${config.name}" failed (HTTP ${status}).${envHint}`,
-    { details: { status } }
-  );
-}
 function unavailable(config, message, status) {
   return new ProviderError("PROVIDER_UNAVAILABLE", `Provider "${config.name}": ${message}`, {
     details: { status }
@@ -594,11 +844,33 @@ function inferHealth(error) {
 
 // src/providers/omnihilbras/index.ts
 var OmniHilbrasProvider = class extends OpenAICompatibleProvider {
+  gateway;
+  async listModels() {
+    const raw = await this.rawModelsResponse();
+    await this.extractGatewayMetadata(raw);
+    const models = await super.listModels();
+    return this.gateway ? models.map((model) => ({ ...model, metadata: { ...model.metadata, gateway: this.gateway } })) : models;
+  }
   /**
    * Run the full connect flow. Throws on authentication or transport failure
    * (use healthCheck() for a non-throwing probe).
    */
-  async connect(registry) {
+  /**
+   * Gateway metadata reported alongside the model list (gateway version, tier,
+   * region…), kept separate from per-model metadata (§11 — provider metadata).
+   */
+  gatewayMetadata() {
+    return this.gateway;
+  }
+  async extractGatewayMetadata(body) {
+    if (body !== null && typeof body === "object") {
+      const gateway = body.gateway;
+      if (gateway !== null && typeof gateway === "object") {
+        this.gateway = gateway;
+      }
+    }
+  }
+  async connectAndRegister(registry) {
     const apiKey = resolveApiKey(this.config);
     const discovered = await this.listModels();
     const seen = /* @__PURE__ */ new Set();
@@ -822,7 +1094,7 @@ async function testProvider(name, options = {}) {
   if (options.connect && provider instanceof OmniHilbrasProvider) {
     const registry = new ModelRegistry();
     try {
-      const result = await provider.connect(registry);
+      const result = await provider.connectAndRegister(registry);
       printProviderStatus(result.status);
       console.log(`  registered: ${result.registered}`);
     } catch (error) {
@@ -897,19 +1169,416 @@ function registerModelsCommand(program) {
 
 // src/agents/process/index.ts
 import { spawn } from "child_process";
-var DEFAULT_TIMEOUT_MS2 = 6e5;
-var KILL_GRACE_MS = 5e3;
+
+// src/agent-protocol/version.ts
+var PROTOCOL_V2 = "omninode-agent-protocol/2";
+var SUPPORTED_PROTOCOL_VERSIONS = [
+  "omninode-agent-protocol/1",
+  PROTOCOL_V2
+];
+var MAX_MESSAGE_BYTES = 1048576;
+function isSupportedProtocol(protocol) {
+  return SUPPORTED_PROTOCOL_VERSIONS.includes(protocol);
+}
+
+// src/agent-protocol/types.ts
+function newMessageId(prefix = "msg") {
+  const random = Math.random().toString(36).slice(2, 10);
+  return `${prefix}-${Date.now().toString(36)}-${random}`;
+}
+function envelope(type, payload, ids = {}) {
+  return {
+    protocol: PROTOCOL_V2,
+    messageId: newMessageId(),
+    ...ids.requestId !== void 0 ? { requestId: ids.requestId } : {},
+    ...ids.taskId !== void 0 ? { taskId: ids.taskId } : {},
+    ...ids.agentId !== void 0 ? { agentId: ids.agentId } : {},
+    ...ids.pipelineId !== void 0 ? { pipelineId: ids.pipelineId } : {},
+    ...ids.executionId !== void 0 ? { executionId: ids.executionId } : {},
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    type,
+    payload,
+    ...ids.metadata !== void 0 ? { metadata: ids.metadata } : {}
+  };
+}
+
+// src/agent-protocol/codec.ts
+var KNOWN_TYPES = /* @__PURE__ */ new Set([
+  // node → agent
+  "TASK",
+  "HELLO_ACK",
+  "CONTEXT",
+  "INSTRUCTION",
+  "RESPONSE",
+  "CANCEL",
+  // agent → node
+  "HELLO",
+  "TASK_REQUEST",
+  "TASK_ACCEPTED",
+  "TASK_STARTED",
+  "STATUS",
+  "QUESTION",
+  "REPORT",
+  "ARTIFACT",
+  "COMPLETION",
+  "ERROR",
+  "CANCELLED"
+]);
+var PAYLOAD_REQUIRED_TYPES = /* @__PURE__ */ new Set(["TASK", "REPORT", "COMPLETION", "ERROR", "QUESTION", "ARTIFACT", "HELLO"]);
+function validateEnvelope(value, line) {
+  const sample = line?.slice(0, 200);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, error: { code: "NOT_AN_OBJECT", message: "message must be a JSON object", ...sample ? { sample } : {} } };
+  }
+  const raw = value;
+  const protocol = raw.protocol;
+  if (protocol === void 0) {
+    const type = raw.type;
+    if (typeof type !== "string" || !KNOWN_TYPES.has(type)) {
+      return { ok: false, error: { code: "UNKNOWN_TYPE", message: `unknown message type ${String(type)}`, ...sample ? { sample } : {} } };
+    }
+    return {
+      ok: true,
+      legacy: true,
+      envelope: {
+        protocol: "omninode-agent-protocol/1",
+        messageId: typeof raw.messageId === "string" ? raw.messageId : "legacy",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type,
+        payload: raw.payload
+      }
+    };
+  }
+  if (typeof protocol !== "string" || !isSupportedProtocol(protocol)) {
+    return {
+      ok: false,
+      error: { code: "UNSUPPORTED_VERSION", message: `unsupported protocol "${String(protocol)}"`, ...sample ? { sample } : {} }
+    };
+  }
+  if (raw.type === void 0) {
+    return { ok: false, error: { code: "MISSING_FIELD", message: "message is missing 'type'", ...sample ? { sample } : {} } };
+  }
+  if (typeof raw.type !== "string" || !KNOWN_TYPES.has(raw.type)) {
+    return { ok: false, error: { code: "UNKNOWN_TYPE", message: `unknown message type ${String(raw.type)}`, ...sample ? { sample } : {} } };
+  }
+  if (raw.timestamp !== void 0 && typeof raw.timestamp !== "string") {
+    return { ok: false, error: { code: "MISSING_FIELD", message: "'timestamp' must be a string", ...sample ? { sample } : {} } };
+  }
+  if (PAYLOAD_REQUIRED_TYPES.has(raw.type) && (raw.payload === void 0 || raw.payload === null)) {
+    return { ok: false, error: { code: "INVALID_PAYLOAD", message: `${raw.type} requires a payload`, ...sample ? { sample } : {} } };
+  }
+  return {
+    ok: true,
+    legacy: protocol !== PROTOCOL_V2,
+    envelope: {
+      protocol,
+      messageId: typeof raw.messageId === "string" ? raw.messageId : "unknown",
+      ...typeof raw.requestId === "string" ? { requestId: raw.requestId } : {},
+      ...typeof raw.taskId === "string" ? { taskId: raw.taskId } : {},
+      ...typeof raw.agentId === "string" ? { agentId: raw.agentId } : {},
+      ...typeof raw.pipelineId === "string" ? { pipelineId: raw.pipelineId } : {},
+      ...typeof raw.executionId === "string" ? { executionId: raw.executionId } : {},
+      timestamp: typeof raw.timestamp === "string" ? raw.timestamp : (/* @__PURE__ */ new Date()).toISOString(),
+      type: raw.type,
+      payload: raw.payload,
+      ...raw.metadata !== null && typeof raw.metadata === "object" ? { metadata: raw.metadata } : {}
+    }
+  };
+}
+function decodeMessage(line, maxBytes = MAX_MESSAGE_BYTES) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, error: { code: "INVALID_JSON", message: "empty line" } };
+  }
+  if (trimmed.length > maxBytes) {
+    return {
+      ok: false,
+      error: { code: "OVERSIZED", message: `message of ${trimmed.length} bytes exceeds the ${maxBytes} byte limit`, sample: trimmed.slice(0, 200) }
+    };
+  }
+  let value;
+  try {
+    value = JSON.parse(trimmed);
+  } catch (error) {
+    return {
+      ok: false,
+      error: { code: "INVALID_JSON", message: error instanceof Error ? error.message : "invalid JSON", sample: trimmed.slice(0, 200) }
+    };
+  }
+  return validateEnvelope(value, trimmed);
+}
+function encodeMessage(envelope2, maxBytes = MAX_MESSAGE_BYTES) {
+  const line = JSON.stringify(envelope2);
+  if (line.length > maxBytes) {
+    throw new Error(`outbound protocol message of ${line.length} bytes exceeds the ${maxBytes} byte limit`);
+  }
+  return line;
+}
+var ProtocolDecoder = class {
+  buffer = "";
+  maxBytes;
+  constructor(maxBytes = MAX_MESSAGE_BYTES) {
+    this.maxBytes = maxBytes;
+  }
+  push(chunk) {
+    this.buffer += chunk;
+    const results = [];
+    let index = this.buffer.indexOf("\n");
+    while (index >= 0) {
+      const line = this.buffer.slice(0, index);
+      this.buffer = this.buffer.slice(index + 1);
+      if (line.trim().length > 0) results.push(decodeMessage(line, this.maxBytes));
+      index = this.buffer.indexOf("\n");
+    }
+    if (this.buffer.length > this.maxBytes) {
+      results.push({
+        ok: false,
+        error: { code: "OVERSIZED", message: `line exceeded ${this.maxBytes} bytes without a newline`, sample: this.buffer.slice(0, 200) }
+      });
+      this.buffer = "";
+    }
+    return results;
+  }
+  /** Flush any trailing line when the process exits. */
+  flush() {
+    if (this.buffer.trim().length === 0) {
+      this.buffer = "";
+      return [];
+    }
+    const result = decodeMessage(this.buffer, this.maxBytes);
+    this.buffer = "";
+    return [result];
+  }
+};
+
+// src/agent-protocol/handshake.ts
+function parseHello(envelopeValue) {
+  if (envelopeValue.type !== "HELLO") {
+    return { ok: false, reason: `expected HELLO, received ${envelopeValue.type}` };
+  }
+  const payload = envelopeValue.payload;
+  if (payload === null || typeof payload !== "object") {
+    return { ok: false, reason: "HELLO payload must be an object" };
+  }
+  const p = payload;
+  if (typeof p.name !== "string" || p.name.length === 0) {
+    return { ok: false, reason: "HELLO payload is missing 'name'" };
+  }
+  return {
+    ok: true,
+    descriptor: {
+      protocol: envelopeValue.protocol,
+      name: p.name,
+      ...typeof p.version === "string" ? { version: p.version } : {},
+      capabilities: Array.isArray(p.capabilities) ? p.capabilities.filter((c) => typeof c === "string") : [],
+      supports: Array.isArray(p.supports) ? p.supports.filter((s) => typeof s === "string") : []
+    }
+  };
+}
+function buildHelloAck(descriptor) {
+  return envelope("HELLO_ACK", {
+    ok: true,
+    protocol: PROTOCOL_V2,
+    agent: descriptor.name,
+    ...descriptor.version !== void 0 ? { agentVersion: descriptor.version } : {},
+    supportedProtocols: [PROTOCOL_V2]
+  }, { agentId: descriptor.name });
+}
+
+// src/agent-protocol/session.ts
+var ProtocolSession = class {
+  decoder;
+  ids;
+  responder;
+  violations = [];
+  questions = [];
+  artifacts = [];
+  reports = [];
+  descriptor;
+  completionSummary;
+  errorMessage;
+  constructor(ids, options = {}) {
+    this.ids = ids;
+    this.responder = options.responder;
+    this.decoder = new ProtocolDecoder(options.maxBytes);
+  }
+  /** The v2 messages OmniNode sends to open a task (written to the agent's stdin). */
+  taskMessages(objective, role, context, instruction) {
+    const ids = this.ids;
+    const messages = [envelope("TASK", { taskId: ids.taskId, objective }, ids)];
+    if (role !== void 0) messages.push(envelope("CONTEXT", { role }, ids));
+    if (context !== void 0 && context.length > 0) messages.push(envelope("CONTEXT", { body: context }, ids));
+    if (instruction !== void 0 && instruction.length > 0) messages.push(envelope("INSTRUCTION", { text: instruction }, ids));
+    return messages.map((m) => encodeMessage(m));
+  }
+  helloAck(descriptor) {
+    return encodeMessage(buildHelloAck(descriptor));
+  }
+  /** Consumes decoded stdout, answering questions as they arrive. */
+  async handle(decoded) {
+    if (!decoded.ok) {
+      this.violations.push(decoded.error);
+      return;
+    }
+    const message = decoded.envelope;
+    if (message.protocol === PROTOCOL_V2) this.sawV2 = true;
+    if (message.type === "HELLO") {
+      const hello = parseHello(message);
+      if (hello.ok) this.descriptor = hello.descriptor;
+      else this.violations.push({ code: "INVALID_PAYLOAD", message: `bad HELLO: ${hello.reason}` });
+      return;
+    }
+    if (message.type === "QUESTION") {
+      await this.answerQuestion(message);
+      return;
+    }
+    if (message.type === "REPORT") {
+      this.reports.push(message.payload);
+      return;
+    }
+    if (message.type === "ARTIFACT") {
+      this.artifacts.push(message.payload);
+      return;
+    }
+    if (message.type === "COMPLETION") {
+      const payload = message.payload;
+      this.completionSummary = typeof payload?.summary === "string" ? payload.summary : "";
+      return;
+    }
+    if (message.type === "ERROR") {
+      const payload = message.payload;
+      const detail = typeof payload?.message === "string" ? payload.message : "agent reported an error";
+      const code = typeof payload?.code === "string" ? ` [${payload.code}]` : "";
+      this.errorMessage = `Agent error${code}: ${detail}`;
+      return;
+    }
+    if (message.type === "TASK_ACCEPTED" || message.type === "TASK_STARTED" || message.type === "STATUS") {
+      return;
+    }
+    this.violations.push({
+      code: "UNKNOWN_TYPE",
+      message: `unexpected message type ${message.type} from agent`
+    });
+  }
+  async answerQuestion(message) {
+    const payload = message.payload ?? {};
+    const questionId = typeof payload.questionId === "string" ? payload.questionId : message.messageId;
+    const question = typeof payload.question === "string" ? payload.question : "";
+    const expected = typeof payload.expected === "string" ? payload.expected : "text";
+    let answer;
+    if (this.responder) {
+      try {
+        answer = await this.responder({ questionId, question, expected });
+      } catch (error) {
+        this.violations.push({
+          code: "INVALID_PAYLOAD",
+          message: `question responder failed: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+    }
+    this.questions.push({ questionId, question, ...answer !== void 0 ? { answer } : {} });
+    this.pendingAnswers.push(
+      encodeMessage(
+        envelope("RESPONSE", { questionId, ...answer !== void 0 ? { body: answer } : {} }, {
+          ...this.ids,
+          requestId: message.requestId ?? this.ids.requestId
+        })
+      )
+    );
+  }
+  pendingAnswers = [];
+  /** True once any inbound message carried the v2 protocol field. */
+  sawV2 = false;
+};
+
+// src/agents/cwd.ts
+import { statSync } from "fs";
+import { isAbsolute, relative, resolve } from "path";
+function validateWorkingDirectory(cwd, options = {}) {
+  if (!cwd) return void 0;
+  const normalized = isAbsolute(cwd) ? resolve(cwd) : resolve(process.cwd(), cwd);
+  let stats;
+  try {
+    stats = statSync(normalized);
+  } catch (error) {
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Working directory "${normalized}" does not exist or is not accessible.`,
+      { cause: error, details: { cwd: normalized } }
+    );
+  }
+  if (!stats.isDirectory()) {
+    throw new AgentError("AGENT_NOT_FOUND", `Working directory "${normalized}" is not a directory.`, {
+      details: { cwd: normalized }
+    });
+  }
+  try {
+    statSync(resolve(normalized, "."));
+  } catch (error) {
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Working directory "${normalized}" is not accessible.`,
+      { cause: error }
+    );
+  }
+  const projectRoot = resolve(options.projectRoot ?? process.cwd());
+  const rel = relative(projectRoot, normalized);
+  const outsideProject = rel.startsWith("..") || isAbsolute(rel);
+  if (outsideProject && options.allowExternal !== true) {
+    throw new AgentError(
+      "AGENT_NOT_FOUND",
+      `Working directory "${normalized}" is outside the project root "${projectRoot}". Set allow_external_cwd: true on the agent to permit this.`,
+      { details: { cwd: normalized, projectRoot } }
+    );
+  }
+  return { cwd: normalized, outsideProject };
+}
+
+// src/agents/env.ts
+var BASELINE_KEYS = ["PATH", "HOME"];
+function resolveEnvPolicy(config) {
+  if (config.envPolicy !== void 0) return config.envPolicy;
+  if (config.inheritEnv === false) return "explicit";
+  return "inherit";
+}
 function buildChildEnv(config) {
   const configured = config.env ?? {};
-  if (config.inheritEnv !== false) {
+  const policy = resolveEnvPolicy(config);
+  if (policy === "inherit") {
     return { ...process.env, ...configured };
   }
-  return {
-    PATH: process.env.PATH ?? "",
-    HOME: process.env.HOME ?? "",
-    ...configured
-  };
+  const base = {};
+  for (const key of BASELINE_KEYS) {
+    const value = process.env[key];
+    if (value !== void 0) base[key] = value;
+  }
+  switch (policy) {
+    case "explicit":
+      return { ...base, ...configured };
+    case "allowlist": {
+      const allowed = { ...base };
+      for (const key of config.envAllowlist ?? []) {
+        const value = process.env[key];
+        if (value !== void 0) allowed[key] = value;
+      }
+      return { ...allowed, ...configured };
+    }
+    case "denylist": {
+      const denied = new Set((config.envDenylist ?? []).map((k) => k.toUpperCase()));
+      const filtered = {};
+      for (const [key, value] of Object.entries(process.env)) {
+        if (denied.has(key.toUpperCase())) continue;
+        filtered[key] = value;
+      }
+      return { ...filtered, ...configured };
+    }
+  }
 }
+
+// src/agents/process/index.ts
+var DEFAULT_TIMEOUT_MS2 = 6e5;
+var KILL_GRACE_MS = 5e3;
+var DEFAULT_MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
 function composeTaskText(input) {
   const sections = [`# Objective
 ${input.objective}`];
@@ -930,18 +1599,19 @@ ${input.instruction}`);
   return sections.join("\n\n");
 }
 function buildProtocolMessages(input, agentName) {
-  const meta = {
+  const session = new ProtocolSession({
+    requestId: `req-${input.taskId}`,
     taskId: input.taskId,
-    agent: agentName,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  const messages = [
-    { type: "TASK", payload: { taskId: input.taskId, objective: input.objective } }
-  ];
-  if (input.role) messages.push({ type: "ROLE", payload: input.role });
-  if (input.context) messages.push({ type: "CONTEXT", payload: { body: input.context } });
-  if (input.instruction) messages.push({ type: "INSTRUCTION", payload: { text: input.instruction } });
-  return messages.map((message) => JSON.stringify({ meta, message }));
+    agentId: agentName,
+    ...input.pipelineId !== void 0 ? { pipelineId: input.pipelineId } : {},
+    ...input.executionId !== void 0 ? { executionId: input.executionId } : {}
+  });
+  return session.taskMessages(
+    input.objective,
+    input.role,
+    input.context,
+    input.instruction
+  );
 }
 var ProcessAgent = class {
   config;
@@ -970,40 +1640,73 @@ var ProcessAgent = class {
     }
     const mode = this.config.inputMode ?? "stdin";
     const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
+      let cwd;
+      try {
+        cwd = validateWorkingDirectory(this.config.cwd, {
+          allowExternal: this.config.allowExternalCwd
+        })?.cwd;
+      } catch (error) {
+        reject(error);
+        return;
+      }
       const child = spawn(
         command,
         [...this.config.args ?? [], ...mode === "arg" ? [composeTaskText(input)] : []],
         {
-          cwd: this.config.cwd,
+          ...cwd !== void 0 ? { cwd } : {},
           env: buildChildEnv(this.config),
-          stdio: ["pipe", "pipe", "pipe"]
+          stdio: ["pipe", "pipe", "pipe"],
+          // Own process group so the whole tree can be terminated together
+          // (roadmap §8: no orphaned children).
+          ...process.platform === "win32" ? {} : { detached: true }
         }
       );
       this.running.set(input.taskId, child);
+      GLOBAL_RUNNING.add(child);
+      installSignalForwarding();
       let stdout = "";
       let stderr = "";
       let timedOut = false;
+      let outputLimitExceeded = false;
       let settled = false;
+      const maxOutputBytes = this.config.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
       const timer = setTimeout(() => {
         timedOut = true;
-        this.log.warn(`Task ${input.taskId} exceeded ${timeoutMs}ms \u2014 killing process.`);
-        child.kill("SIGTERM");
-        setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS).unref();
+        this.log.warn(`Task ${input.taskId} exceeded ${timeoutMs}ms \u2014 killing process tree.`);
+        killTree(child, "SIGTERM");
+        setTimeout(() => killTree(child, "SIGKILL"), KILL_GRACE_MS).unref();
       }, timeoutMs);
       const settle = (finish) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
         this.running.delete(input.taskId);
+        GLOBAL_RUNNING.delete(child);
         finish();
       };
-      child.stdout?.on("data", (chunk) => {
-        stdout += chunk.toString();
-      });
-      child.stderr?.on("data", (chunk) => {
-        stderr += chunk.toString();
-      });
+      const collect = (into, chunk) => {
+        if (outputLimitExceeded) return;
+        const text = sanitizeChunk(chunk);
+        if (into === "stdout") {
+          if (stdout.length + text.length > maxOutputBytes) {
+            stdout = (stdout + text).slice(0, maxOutputBytes);
+            outputLimitExceeded = true;
+            this.log.warn(`Agent "${this.config.name}" exceeded the ${maxOutputBytes} byte output limit \u2014 killing it.`);
+            killTree(child, "SIGKILL");
+            return;
+          }
+          stdout += text;
+        } else {
+          if (stderr.length + text.length > maxOutputBytes) {
+            stderr = (stderr + text).slice(0, maxOutputBytes);
+            return;
+          }
+          stderr += text;
+        }
+      };
+      child.stdout?.on("data", (chunk) => collect("stdout", chunk));
+      child.stderr?.on("data", (chunk) => collect("stderr", chunk));
       child.stdin?.on("error", () => {
       });
       if (mode !== "arg") {
@@ -1037,7 +1740,19 @@ var ProcessAgent = class {
               new AgentError(
                 "AGENT_TIMEOUT",
                 `Agent "${this.config.name}" timed out after ${timeoutMs}ms and was killed.`,
-                { details: { taskId: input.taskId, stdout: stdout.slice(0, 4e3), stderr: stderr.slice(0, 2e3) } }
+                {
+                  details: {
+                    operation: "agent.run",
+                    agent: this.config.name,
+                    durationMs: timeoutMs,
+                    // The process was started and may have performed side
+                    // effects before being killed — the outcome is unknown,
+                    // not failed (roadmap §6.3).
+                    dispatched: true,
+                    stdout: stdout.slice(0, 4e3),
+                    stderr: stderr.slice(0, 2e3)
+                  }
+                }
               )
             );
             return;
@@ -1045,7 +1760,7 @@ var ProcessAgent = class {
           const logs = stderr.trim().length > 0 ? stderr.split("\n") : void 0;
           if (mode === "protocol") {
             try {
-              resolve(
+              resolve2(
                 interpretProtocolRun({
                   input,
                   agentName: this.config.name,
@@ -1060,14 +1775,14 @@ var ProcessAgent = class {
             return;
           }
           const trimmed = stdout.trim();
-          resolve({
+          resolve2({
             taskId: input.taskId,
-            status: code === 0 ? "completed" : "failed",
+            status: code === 0 && !outputLimitExceeded ? "completed" : "failed",
             summary: trimmed.length > 0 ? firstLine(trimmed) : void 0,
             rawOutput: trimmed.length > 0 ? trimmed : void 0,
             exitCode: code ?? void 0,
             logs,
-            error: code === 0 ? void 0 : `Process exited with code ${code ?? "unknown"}${signal ? ` (signal: ${signal})` : ""}`
+            ...outputLimitExceeded ? { error: `Agent exceeded the ${maxOutputBytes} byte output limit and was terminated.` } : code === 0 ? {} : { error: describeExit(code, signal) }
           });
         });
       });
@@ -1076,67 +1791,117 @@ var ProcessAgent = class {
   /** Ask the agent to stop current work (SIGTERM). */
   async cancel(taskId) {
     const child = this.running.get(taskId);
-    if (child) child.kill("SIGTERM");
+    if (child) killTree(child, "SIGTERM");
   }
   runningTaskIds() {
     return [...this.running.keys()];
   }
 };
-function interpretProtocolRun({ input, agentName, stdout, exitCode, logs }) {
-  const reports = [];
-  let summary;
-  let error;
-  let sawProtocolMessage = false;
-  for (const line of stdout.split("\n")) {
-    const trimmed2 = line.trim();
-    if (trimmed2.length === 0) continue;
-    const message = parseAgentMessage(trimmed2);
-    if (!message) continue;
-    sawProtocolMessage = true;
-    if (message.type === "REPORT") {
-      const report = normalizeReport(message.payload, input.taskId, agentName, reports.length);
-      if (report) reports.push(report);
-    } else if (message.type === "COMPLETION") {
-      const payload = message.payload;
-      if (typeof payload?.summary === "string") summary = payload.summary;
-    } else if (message.type === "ERROR") {
-      const payload = message.payload;
-      const detail = typeof payload?.message === "string" ? payload.message : "unknown error";
-      const code = typeof payload?.code === "string" ? ` [${payload.code}]` : "";
-      error = `Agent error${code}: ${detail}`;
-    }
+function interpretProtocolRun({
+  input,
+  agentName,
+  stdout,
+  exitCode,
+  logs,
+  responder
+}) {
+  const session = new ProtocolSession(
+    {
+      requestId: `req-${input.taskId}`,
+      taskId: input.taskId,
+      agentId: agentName,
+      ...input.pipelineId !== void 0 ? { pipelineId: input.pipelineId } : {},
+      ...input.executionId !== void 0 ? { executionId: input.executionId } : {}
+    },
+    { ...responder !== void 0 ? { responder } : {} }
+  );
+  for (const result of session.decoder.push(stdout)) {
+    session.handle(result);
   }
-  if (!sawProtocolMessage && exitCode === 0) {
-    throw new ProtocolError(
-      `Agent "${agentName}" produced no protocol messages on stdout (input mode "protocol").`,
-      { details: { taskId: input.taskId, stdout: stdout.slice(0, 2e3) } }
-    );
+  for (const result of session.decoder.flush()) {
+    session.handle(result);
   }
+  const reports = session.reports.flatMap((payload) => Array.isArray(payload) ? payload : [payload]).map((payload, index) => normalizeReport(payload, input.taskId, agentName, index)).filter((report) => report !== void 0);
   const trimmed = stdout.trim();
+  const protocolBlock = {
+    protocol: session.descriptor?.protocol ?? PROTOCOL_V2,
+    legacy: !session.sawV2 && session.descriptor === void 0,
+    ...session.descriptor !== void 0 ? { descriptor: session.descriptor } : {},
+    questions: session.questions,
+    violations: session.violations.map((v) => `${v.code}: ${v.message}`)
+  };
+  if (session.errorMessage !== void 0) {
+    return {
+      taskId: input.taskId,
+      status: "failed",
+      error: session.errorMessage,
+      rawOutput: trimmed.length > 0 ? trimmed : void 0,
+      exitCode: exitCode ?? void 0,
+      logs,
+      protocol: protocolBlock,
+      ...reports.length > 0 ? { reports } : {}
+    };
+  }
+  if (session.descriptor === void 0 && session.violations.length > 0 && session.reports.length === 0 && session.completionSummary === void 0) {
+    return {
+      taskId: input.taskId,
+      status: "failed",
+      error: `agent produced no valid protocol messages: ${protocolBlock.violations.join("; ")}`,
+      rawOutput: trimmed.length > 0 ? trimmed : void 0,
+      exitCode: exitCode ?? void 0,
+      logs,
+      protocol: protocolBlock
+    };
+  }
+  const completed = exitCode === 0 && session.completionSummary !== void 0;
   return {
     taskId: input.taskId,
-    status: error !== void 0 || exitCode !== 0 ? "failed" : "completed",
-    summary: summary ?? reports[0]?.summary,
+    status: completed || exitCode === 0 ? completed ? "completed" : "completed" : "failed",
+    summary: session.completionSummary ?? reports[0]?.summary,
     rawOutput: trimmed.length > 0 ? trimmed : void 0,
     exitCode: exitCode ?? void 0,
     logs,
-    reports: reports.length > 0 ? reports : void 0,
-    error: error ?? (exitCode !== 0 ? `Process exited with code ${exitCode ?? "unknown"}` : void 0)
+    protocol: protocolBlock,
+    ...reports.length > 0 ? { reports } : {},
+    ...exitCode !== 0 ? { error: `Process exited with code ${exitCode ?? "unknown"}` } : {}
   };
 }
-function parseAgentMessage(line) {
-  try {
-    const parsed = JSON.parse(line);
-    if (typeof parsed.type === "string") {
-      return { type: parsed.type, payload: parsed.payload };
-    }
-    const inner = parsed.message;
-    if (inner && typeof inner.type === "string") {
-      return { type: inner.type, payload: inner.payload };
+var GLOBAL_RUNNING = /* @__PURE__ */ new Set();
+var signalForwardingInstalled = false;
+function installSignalForwarding() {
+  if (signalForwardingInstalled) return;
+  signalForwardingInstalled = true;
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      for (const child of GLOBAL_RUNNING) {
+        killTree(child, "SIGTERM");
+      }
+    });
+  }
+}
+function killTree(child, signal) {
+  if (child.pid === void 0) return;
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
     }
+  }
+  try {
+    child.kill(signal);
   } catch {
   }
-  return void 0;
+}
+function describeExit(code, signal) {
+  if (signal !== null) {
+    return signal === "SIGKILL" ? "Process was killed (SIGKILL) \u2014 usually an external kill or OOM." : `Process terminated by signal ${signal}.`;
+  }
+  if (code === null) return "Process terminated without an exit code.";
+  return `Process exited with code ${code}.`;
+}
+function sanitizeChunk(chunk) {
+  return [...chunk.toString("utf8")].filter((char) => char.charCodeAt(0) !== 0).join("");
 }
 function normalizeReport(payload, taskId, agentName, index) {
   if (payload === null || typeof payload !== "object") return void 0;
@@ -1157,6 +1922,40 @@ function firstLine(text, maxLength = 200) {
   return line.length > maxLength ? `${line.slice(0, maxLength)}\u2026` : line;
 }
 
+// src/agents/adapters.ts
+var AgentAdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    this.adapters.set(adapter.integration, adapter);
+  }
+  get(integration) {
+    return this.adapters.get(integration);
+  }
+  list() {
+    return [...this.adapters.values()];
+  }
+  create(config) {
+    const adapter = this.get(config.integration);
+    if (!adapter) {
+      throw new AgentError(
+        "AGENT_NOT_FOUND",
+        `No agent adapter registered for integration "${config.integration}". Registered: ${[...this.adapters.keys()].join(", ") || "(none)"}.`
+      );
+    }
+    return adapter.create(config);
+  }
+};
+var ProcessAgentAdapter = class {
+  constructor(factory) {
+    this.factory = factory;
+  }
+  factory;
+  integration = "process";
+  create(config) {
+    return this.factory(config);
+  }
+};
+
 // src/agents/registry.ts
 var AgentRegistry = class {
   agents = /* @__PURE__ */ new Map();
@@ -1172,14 +1971,15 @@ var AgentRegistry = class {
 };
 
 // src/agents/factory.ts
-function createAgent(config) {
-  if (config.integration === "process") {
-    return new ProcessAgent(config);
-  }
+var defaultAgentAdapters = new AgentAdapterRegistry();
+defaultAgentAdapters.register(new ProcessAgentAdapter((config) => new ProcessAgent(config)));
+function createAgent(config, adapters = defaultAgentAdapters) {
+  const registered = adapters.get(config.integration);
+  if (registered) return registered.create(config);
   if (config.integration === "native") {
     throw new OmniNodeError(
       "NOT_IMPLEMENTED",
-      `Native agent adapters are planned for a later phase. Use input over stdin/stdout (type "cli") for "${config.name}" for now.`
+      `No native adapter is registered for "${config.name}". Register an IAgentAdapter (createAgent(config, adapters)) or use input over stdin/stdout (type "cli").`
     );
   }
   throw new OmniNodeError("NOT_IMPLEMENTED", `Agent integration "${config.integration}" has no adapter yet.`);
@@ -1222,7 +2022,7 @@ function registerAgentCommands(program) {
     "--input-mode <mode>",
     "How the task is delivered: stdin (prompt on stdin), arg (prompt as last argument) or protocol (\xA721 JSON-lines task protocol).",
     "stdin"
-  ).option(
+  ).option("--env-policy <policy>", "Environment policy: inherit, allowlist, denylist or explicit.").option("--allow-env <name>", "Variable to forward under the allowlist policy (repeatable).", collectArgs).option("--deny-env <name>", "Variable to remove under the denylist policy (repeatable).", collectArgs).option("--max-output-bytes <n>", "Per-stream output budget in bytes (default 5 MiB).", (value) => Number(value)).option("--allow-external-cwd", "Allow a working directory outside the project root.").option(
     "--timeout-ms <ms>",
     "Per-task timeout in milliseconds.",
     (value) => Number(value)
@@ -1237,7 +2037,12 @@ async function addAgent(options) {
     ...options.arg !== void 0 && options.arg.length > 0 ? { args: options.arg } : {},
     ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
     input_mode: options.inputMode,
-    ...options.timeoutMs !== void 0 ? { timeout_ms: options.timeoutMs } : {}
+    ...options.timeoutMs !== void 0 ? { timeout_ms: options.timeoutMs } : {},
+    ...options.envPolicy !== void 0 ? { env_policy: options.envPolicy } : {},
+    ...options.allowEnv !== void 0 && options.allowEnv.length > 0 ? { env_allowlist: options.allowEnv } : {},
+    ...options.denyEnv !== void 0 && options.denyEnv.length > 0 ? { env_denylist: options.denyEnv } : {},
+    ...options.maxOutputBytes !== void 0 ? { max_output_bytes: options.maxOutputBytes } : {},
+    ...options.allowExternalCwd !== void 0 ? { allow_external_cwd: options.allowExternalCwd } : {}
   });
   if (!candidate.success) {
     const issues = candidate.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
@@ -1397,12 +2202,18 @@ import { randomBytes } from "crypto";
 var ALLOWED_TRANSITIONS = {
   created: ["queued", "running", "cancelled"],
   queued: ["running", "cancelled"],
-  running: ["completed", "failed", "cancelled"],
+  running: ["completed", "failed", "timed_out", "unknown", "cancelled", "partially_completed"],
   waiting: ["running", "cancelled"],
   completed: [],
-  failed: [],
-  cancelled: []
+  // failed → running is the only re-entry: bounded automatic retry (§6.4).
+  failed: ["running"],
+  timed_out: [],
+  cancelled: [],
+  unknown: [],
+  partially_completed: []
 };
+var RETRYABLE_ERROR_CODES = ["AGENT_FAILED"];
+var EXECUTION_HISTORY_LIMIT = 10;
 var TaskEngine = class {
   constructor(options) {
     this.options = options;
@@ -1434,6 +2245,7 @@ var TaskEngine = class {
       id: generateTaskId(),
       objective: input.objective.trim(),
       status: "created",
+      attempt: 0,
       createdAt: now,
       updatedAt: now,
       ...input.project !== void 0 ? { project: input.project } : {},
@@ -1450,8 +2262,10 @@ var TaskEngine = class {
     const task = await this.mustGet(id);
     return this.transition(task, "queued");
   }
-  /** Runs the task through its assigned agent and records the result. */
-  async run(id) {
+  /** Runs the task through its assigned agent and records the result.
+   *  `maxAttempts` enables bounded automatic retries of *retryable* errors
+   *  with linear backoff; unknown/timed_out outcomes are never auto-retried. */
+  async run(id, options = {}) {
     const task = await this.mustGet(id);
     if (task.status !== "created" && task.status !== "queued") {
       throw new TaskError("TASK_INVALID", `Task ${id} is "${task.status}" and cannot be run.`);
@@ -1464,49 +2278,89 @@ var TaskEngine = class {
       throw new TaskError("TASK_INVALID", `Agent "${task.agent}" is not registered anymore.`);
     }
     const role = task.role ? this.options.roles.get(task.role) : void 0;
-    const running = await this.transition(task, "running");
     this.log.info(`Running task ${task.id} on agent "${task.agent}".`);
-    let background = running.context?.background;
+    let background = task.context?.background;
     if (this.options.memory) {
       const memoryContext = await this.options.memory.gatherContext({
-        objective: running.objective,
-        ...running.role ? { role: running.role } : {},
-        ...running.project ? { project: running.project } : {}
+        objective: task.objective,
+        ...task.role ? { role: task.role } : {},
+        ...task.project ? { project: task.project } : {}
       });
       if (memoryContext.length > 0) {
         background = [memoryContext, background].filter((part) => part && part.length > 0).join("\n\n");
       }
     }
-    let output;
-    try {
-      output = await agent.run({
-        taskId: running.id,
-        objective: running.objective,
-        ...role ? { role } : {},
-        ...background !== void 0 ? { context: background } : {}
-      });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.log.error(`Task ${task.id} failed: ${message}`);
-      return this.transition(running, "failed", {
-        result: { error: message, finishedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 1);
+    const backoffMs = options.retryBackoffMs ?? 0;
+    let current = task;
+    for (let i = 0; i < maxAttempts; i += 1) {
+      const attempt = current.attempt + 1;
+      const executionId = `exec-${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      current = await this.transition(current, "running", { attempt });
+      let output;
+      let thrown;
+      try {
+        output = await agent.run({
+          taskId: current.id,
+          objective: current.objective,
+          ...role ? { role } : {},
+          ...background !== void 0 ? { context: background } : {}
+        });
+      } catch (error) {
+        thrown = error;
+      }
+      const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+      if (thrown !== void 0 || output === void 0) {
+        const outcome = classifyThrown(thrown);
+        const message = thrown instanceof Error ? thrown.message : String(thrown);
+        const retryable = outcome === "failed" && RETRYABLE_ERROR_CODES.includes(errorCode(thrown)) && i < maxAttempts - 1;
+        current = await this.transition(current, outcome, {
+          attempt,
+          lastError: message,
+          execution: {
+            executionId,
+            attempt,
+            startedAt,
+            finishedAt,
+            outcome,
+            error: message
+          }
+        });
+        this.log.warn(`Task ${current.id} attempt ${attempt} \u2192 ${outcome}: ${message}`);
+        if (retryable) {
+          if (backoffMs > 0) await sleep(backoffMs * attempt);
+          continue;
+        }
+        if (this.options.memory) await this.options.memory.recordTaskOutcome(current);
+        return current;
+      }
+      const currentState = await this.options.store.get(current.id);
+      if (currentState?.status === "cancelled") {
+        current = currentState;
+        break;
+      }
+      const result = {
+        ...output.summary !== void 0 ? { summary: output.summary } : {},
+        ...output.reports !== void 0 && output.reports.length > 0 ? { reports: output.reports } : {},
+        // Keep the verbatim output (bounded) for report extraction and audit.
+        ...output.rawOutput !== void 0 && output.rawOutput.length > 0 ? { rawOutput: output.rawOutput.slice(0, 1e4) } : {},
+        ...output.error !== void 0 ? { error: output.error } : {},
+        finishedAt
+      };
+      const finalStatus = output.status === "completed" ? "completed" : "failed";
+      current = await this.transition(current, finalStatus, {
+        attempt,
+        result,
+        execution: { executionId, attempt, startedAt, finishedAt, outcome: finalStatus }
       });
+      this.log.info(`Task ${current.id} finished: ${finalStatus}.`);
+      break;
     }
-    const result = {
-      ...output.summary !== void 0 ? { summary: output.summary } : {},
-      ...output.reports !== void 0 && output.reports.length > 0 ? { reports: output.reports } : {},
-      // Keep the verbatim output (bounded) for report extraction and audit.
-      ...output.rawOutput !== void 0 && output.rawOutput.length > 0 ? { rawOutput: output.rawOutput.slice(0, 1e4) } : {},
-      ...output.error !== void 0 ? { error: output.error } : {},
-      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    const finalStatus = output.status === "completed" ? "completed" : "failed";
-    const finished = await this.transition(running, finalStatus, { result });
-    this.log.info(`Task ${task.id} finished: ${finalStatus}.`);
     if (this.options.memory) {
-      await this.options.memory.recordTaskOutcome(finished);
+      await this.options.memory.recordTaskOutcome(current);
     }
-    return finished;
+    return current;
   }
   async cancel(id) {
     const task = await this.mustGet(id);
@@ -1519,13 +2373,14 @@ var TaskEngine = class {
     }
     return this.transition(task, "cancelled");
   }
-  /** Error recovery (§27 Phase 9): reset a failed/cancelled task so it can run again. */
+  /** Error recovery: reset a failed/cancelled/unknown/timed_out task so it can run again. */
   async retry(id) {
     const task = await this.mustGet(id);
-    if (task.status !== "failed" && task.status !== "cancelled") {
+    const retryableStates = ["failed", "cancelled", "unknown", "timed_out"];
+    if (!retryableStates.includes(task.status)) {
       throw new TaskError(
         "TASK_INVALID",
-        `Only failed or cancelled tasks can be retried \u2014 task ${id} is "${task.status}".`
+        `Only failed, timed out, unknown or cancelled tasks can be retried \u2014 task ${id} is "${task.status}".`
       );
     }
     const { result: _discarded, ...rest } = task;
@@ -1557,10 +2412,14 @@ var TaskEngine = class {
     if (!allowed.includes(to)) {
       throw new TaskError("TASK_INVALID", `Task ${task.id} cannot move from "${task.status}" to "${to}".`);
     }
+    const executions = extra.execution ? [...task.executions ?? [], extra.execution].slice(-EXECUTION_HISTORY_LIMIT) : task.executions;
     const updated = {
       ...task,
       status: to,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...extra.attempt !== void 0 ? { attempt: extra.attempt } : {},
+      ...extra.lastError !== void 0 ? { lastError: extra.lastError } : {},
+      ...executions !== void 0 ? { executions } : {},
       ...extra.result !== void 0 ? { result: { ...task.result, ...extra.result } } : {}
     };
     await this.options.store.save(updated);
@@ -1581,6 +2440,19 @@ var TaskEngine = class {
 function generateTaskId() {
   return `task-${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
 }
+function errorCode(error) {
+  return error?.code ?? "";
+}
+function classifyThrown(error) {
+  if (error instanceof AgentError && error.code === "AGENT_TIMEOUT") {
+    const dispatched = error.details?.dispatched;
+    return dispatched === false ? "timed_out" : "unknown";
+  }
+  return "failed";
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 
 // src/audit/index.ts
 import { appendFile, mkdir as mkdir2 } from "fs/promises";
@@ -1623,6 +2495,23 @@ var FileAuditLog = class {
   }
 };
 
+// src/memory/base.ts
+function defaultSearch(provider, text, options = {}) {
+  return provider.retrieve({
+    text,
+    ...options.scope !== void 0 ? { scope: options.scope } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {}
+  });
+}
+function defaultMetadata(name, options = {}) {
+  return {
+    name,
+    capabilities: options.capabilities ?? ["retrieve", "store", "search"],
+    relevanceRanking: options.relevanceRanking ?? false,
+    ...options.backend !== void 0 ? { backend: options.backend } : {}
+  };
+}
+
 // src/memory/local.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
   "the",
@@ -1685,9 +2574,27 @@ var LocalMemoryProvider = class extends JsonFileStore {
   constructor(directory) {
     super({ ...directory !== void 0 ? { directory } : {}, fileName: "memory.json" });
   }
-  async query(query) {
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "json-file", deterministicScoring: true }
+    });
+  }
+  search(text, options = {}) {
+    return defaultSearch(this, text, options);
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(entry2) {
+    return this.store(entry2);
+  }
+  async retrieve(query) {
     const entries = await this.readAll();
-    const filtered = entries.filter((entry2) => query.scope ? entry2.scope === query.scope : true).filter(
+    const filtered = entries.filter((entry2) => query.scope ? entry2.scope === query.scope : true).filter((entry2) => query.category ? entry2.category === query.category : true).filter(
       (entry2) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry2.tags ?? []).includes(tag)) : true
     );
     if (!query.text || query.text.trim().length === 0) {
@@ -1696,7 +2603,7 @@ var LocalMemoryProvider = class extends JsonFileStore {
     const queryKeywords = keywords(query.text);
     return filtered.map((entry2) => ({ entry: entry2, score: relevanceScore(queryKeywords, entry2) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry: entry2 }) => entry2);
   }
-  write(entry2) {
+  store(entry2) {
     return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry2.key);
       const stamped = {
@@ -1727,11 +2634,40 @@ var RememberaMemoryProvider = class {
     this.env = config.env ?? process.env;
     this.log = log.child({ component: "remembera" });
   }
+  get authenticationConfigured() {
+    return this.apiKeyEnvVar === void 0 || Boolean(this.env[this.apiKeyEnvVar]);
+  }
   headers() {
     const key = this.apiKeyEnvVar ? resolveApiKey({ name: "remembera", apiKeyEnvVar: this.apiKeyEnvVar }, this.env) : void 0;
     return key ? { authorization: `Bearer ${key}` } : {};
   }
-  async query(query) {
+  /** Search delegates to the gateway's relevance query. */
+  search(text, options = {}) {
+    return defaultSearch(
+      this,
+      text,
+      {
+        ...options.scope !== void 0 ? { scope: options.scope } : {},
+        ...options.limit !== void 0 ? { limit: options.limit } : {}
+      }
+    );
+  }
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "http", baseUrl: this.baseUrl, authenticated: this.authenticationConfigured }
+    });
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(entry2) {
+    return this.store(entry2);
+  }
+  async retrieve(query) {
     const { status, body } = await this.request(`${this.baseUrl}/api/memory/query`, query);
     if (status !== 200) {
       throw new MemoryError(`Remembera query returned HTTP ${status}.`);
@@ -1742,7 +2678,7 @@ var RememberaMemoryProvider = class {
     }
     return entries.map((entry2) => this.toEntry(entry2)).filter((entry2) => entry2 !== void 0);
   }
-  async write(entry2) {
+  async store(entry2) {
     const { status } = await this.request(`${this.baseUrl}/api/memory`, entry2);
     if (status !== 200 && status !== 201) {
       throw new MemoryError(`Remembera write returned HTTP ${status}.`);
@@ -1777,6 +2713,7 @@ var RememberaMemoryProvider = class {
       content: entry2.content,
       scope: scope === "project" || scope === "role" || scope === "task" || scope === "knowledge" ? scope : "knowledge",
       ...Array.isArray(entry2.tags) ? { tags: entry2.tags.filter((t) => typeof t === "string") } : {},
+      ...typeof entry2.category === "string" ? { category: entry2.category } : {},
       ...typeof entry2.createdAt === "string" ? { createdAt: entry2.createdAt } : {},
       ...typeof entry2.updatedAt === "string" ? { updatedAt: entry2.updatedAt } : {}
     };
@@ -1807,57 +2744,54 @@ function createMemoryProvider(config) {
 }
 
 // src/memory/service.ts
+var DEFAULT_ENTRY_LIMIT = 8;
 var MAX_CONTEXT_CHARS = 4e3;
 var MemoryService = class {
-  constructor(provider, log = logger) {
+  constructor(provider, log = logger, options = {}) {
     this.provider = provider;
     this.log = log.child({ component: "memory", provider: provider.name });
+    this.required = options.required ?? false;
+    this.maxContextChars = options.maxContextChars ?? MAX_CONTEXT_CHARS;
   }
   provider;
   log;
+  required;
+  maxContextChars;
   get providerRef() {
     return this.provider;
   }
   get providerName() {
     return this.provider.name;
   }
-  /** Relevant context for a task objective; empty string when nothing matches. */
-  async gatherContext(query) {
+  get isRequired() {
+    return this.required;
+  }
+  /** Structured, budgeted context for a task (§12 — avoid loading all memory). */
+  async contextFor(query) {
+    let entries;
     try {
-      const entries = await this.provider.query({
+      entries = await this.provider.retrieve({
         text: query.objective,
         ...query.role ? { tags: [query.role] } : {},
-        limit: 8
+        limit: query.limit ?? DEFAULT_ENTRY_LIMIT
       });
-      if (entries.length === 0) return "";
-      const byScope = /* @__PURE__ */ new Map();
-      for (const entry2 of entries) {
-        byScope.set(entry2.scope, [...byScope.get(entry2.scope) ?? [], entry2]);
-      }
-      const parts = [];
-      for (const scope of ["project", "task", "role", "knowledge"]) {
-        const scopeEntries = byScope.get(scope) ?? [];
-        if (scopeEntries.length === 0) continue;
-        const lines = scopeEntries.map((entry2) => `- ${entry2.content}`).join("\n");
-        parts.push(`### Relevant memory (${scope})
-${lines}`);
-      }
-      const context = parts.join("\n\n");
-      return context.length > MAX_CONTEXT_CHARS ? `${context.slice(0, MAX_CONTEXT_CHARS)}\u2026` : context;
     } catch (error) {
-      this.log.warn(
-        `Memory query failed (continuing without memory): ${error instanceof Error ? error.message : String(error)}`
-      );
-      return "";
+      return this.handleFailure("retrieve", error, { text: "", entries: [], truncated: false });
     }
+    return this.format(entries);
+  }
+  /** Prompt-ready context text (v1 convenience wrapper). */
+  async gatherContext(query) {
+    return (await this.contextFor(query)).text;
   }
-  /** Records a finished task's outcome — best-effort. */
+  /** Records a finished task's outcome — task history plus "known problems" (§12). */
   async recordTaskOutcome(task) {
     const outcome = task.result?.summary ?? task.result?.error ?? "(no output)";
     try {
-      await this.provider.write({
+      await this.provider.store({
         key: `task:${task.id}`,
         scope: "task",
+        category: "tasks",
         content: `Objective: ${task.objective}
 Status: ${task.status}
 Outcome: ${outcome}`,
@@ -1868,18 +2802,53 @@ Outcome: ${outcome}`,
         (report) => report.findings.filter((finding) => finding.severity === "high" || finding.severity === "critical").map((finding) => ({ report, finding }))
       );
       for (const { report, finding } of significant) {
-        await this.provider.write({
+        await this.provider.store({
           key: `finding:${report.id}:${finding.id}`,
           scope: "project",
+          category: "problems",
           content: `[${finding.severity}] ${finding.title} \u2014 ${finding.detail}`,
           tags: ["known-problem", report.agent]
         });
       }
     } catch (error) {
-      this.log.warn(
-        `Memory write failed (continuing): ${error instanceof Error ? error.message : String(error)}`
+      this.handleFailure("store", error, void 0);
+    }
+  }
+  format(entries) {
+    if (entries.length === 0) return { text: "", entries, truncated: false };
+    const byScope = /* @__PURE__ */ new Map();
+    for (const entry2 of entries) {
+      byScope.set(entry2.scope, [...byScope.get(entry2.scope) ?? [], entry2]);
+    }
+    const parts = [];
+    for (const scope of ["project", "task", "role", "knowledge"]) {
+      const scopeEntries = byScope.get(scope) ?? [];
+      if (scopeEntries.length === 0) continue;
+      const lines = scopeEntries.map((entry2) => {
+        const category = entry2.category ? `[${entry2.category}] ` : "";
+        return `- ${category}${entry2.content}`;
+      }).join("\n");
+      parts.push(`### Relevant memory (${scope})
+${lines}`);
+    }
+    let text = parts.join("\n\n");
+    const truncated = text.length > this.maxContextChars;
+    if (truncated) text = `${text.slice(0, this.maxContextChars - 1)}\u2026`;
+    return { text, entries, truncated };
+  }
+  /**
+   * Failure policy (§12): continue unless memory is explicitly required.
+   */
+  handleFailure(operation, error, fallback) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (this.required) {
+      throw new MemoryError(
+        `Memory is marked required, but ${operation} failed: ${message}`,
+        { cause: error }
       );
     }
+    this.log.warn(`Memory ${operation} failed (continuing without memory): ${message}`);
+    return fallback ?? { text: "", entries: [], truncated: false };
   }
 };
 
@@ -1913,7 +2882,11 @@ function createTaskEngine(config, log = logger, directory) {
     agents,
     roles,
     store: new FileTaskStore(directory),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
     audit: new FileAuditLog(),
     log
   });
@@ -1980,7 +2953,7 @@ function registerTaskCommands(program) {
     const cancelled = await engine.cancel(taskId);
     console.log(`Task ${cancelled.id} is now "${cancelled.status}".`);
   });
-  task.command("retry <task-id>").description("Reset a failed/cancelled task to created; combine with --run to execute it again.").option("--run", "Run the task again immediately after resetting it.").action(async (taskId, options) => {
+  task.command("retry <task-id>").description("Reset a failed, timed out, unknown or cancelled task to created; combine with --run to execute it again.").option("--run", "Run the task again immediately after resetting it.").action(async (taskId, options) => {
     const config = loadConfig();
     const engine = createTaskEngine(config);
     const reset = await engine.retry(taskId);
@@ -2003,6 +2976,15 @@ function printOutcome(task, options = {}) {
     if (task.context?.files) console.log(`  files:   ${task.context.files.join(", ")}`);
     console.log(`  objective: ${task.objective}`);
   }
+  if (options.verbose && task.attempt > 0) {
+    console.log(`  attempt: ${task.attempt}`);
+  }
+  if (task.lastError) console.log(`  error:   ${task.lastError}`);
+  if (options.verbose && task.executions && task.executions.length > 0) {
+    console.log(
+      `  executions: ${task.executions.map((e) => `#${e.attempt}:${e.outcome}`).join(", ")}`
+    );
+  }
   const result = task.result;
   if (!result) return;
   if (result.summary) console.log(`  summary: ${result.summary}`);
@@ -2018,6 +3000,87 @@ function truncate2(text, max) {
 
 // src/reports/aggregate.ts
 import { randomBytes as randomBytes2 } from "crypto";
+
+// src/reports/schema.ts
+import { z as z2 } from "zod";
+var evidenceSchema = z2.union([
+  z2.string().transform((excerpt) => ({ kind: "observation", excerpt })),
+  z2.object({
+    kind: z2.enum(["file", "line", "url", "command", "observation", "artifact"]),
+    ref: z2.string().optional(),
+    line: z2.number().int().optional(),
+    excerpt: z2.string().optional(),
+    agent: z2.string().optional()
+  })
+]);
+var findingSchema = z2.object({
+  id: z2.string().min(1),
+  title: z2.string().min(1),
+  detail: z2.string().default(""),
+  description: z2.string().optional(),
+  severity: z2.enum(["info", "low", "medium", "high", "critical"]).optional(),
+  confidence: z2.enum(["low", "medium", "high"]).optional(),
+  severityBySource: z2.record(z2.enum(["info", "low", "medium", "high", "critical"])).optional(),
+  confidenceBySource: z2.record(z2.enum(["low", "medium", "high"])).optional(),
+  recommendations: z2.array(z2.string()).optional(),
+  evidence: z2.array(evidenceSchema).optional(),
+  location: z2.string().optional(),
+  tags: z2.array(z2.string()).optional(),
+  source: z2.object({ agent: z2.string().optional(), reportId: z2.string().optional(), pipelineRunId: z2.string().optional() }).optional(),
+  recommendation: z2.string().optional()
+});
+var artifactSchema = z2.object({
+  kind: z2.enum(["file", "patch", "log", "screenshot", "document", "data"]),
+  ref: z2.string().min(1),
+  description: z2.string().optional(),
+  mediaType: z2.string().optional(),
+  bytes: z2.number().int().optional()
+});
+var reportSchema = z2.object({
+  id: z2.string().min(1),
+  taskId: z2.string().min(1),
+  agent: z2.string().min(1),
+  agentId: z2.string().optional(),
+  pipelineRunId: z2.string().optional(),
+  model: z2.string().optional(),
+  summary: z2.string(),
+  findings: z2.array(findingSchema),
+  recommendations: z2.array(z2.string()),
+  confidence: z2.enum(["low", "medium", "high"]).optional(),
+  evidence: z2.array(evidenceSchema).optional(),
+  artifacts: z2.array(artifactSchema).optional(),
+  createdAt: z2.string().min(1),
+  metadata: z2.record(z2.unknown()).optional()
+});
+function validateReport(value) {
+  const parsed = reportSchema.safeParse(value);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => ({
+      path: issue.path.join(".") || "(root)",
+      message: issue.message
+    }));
+    return {
+      valid: false,
+      issues,
+      reason: `report failed schema validation (${issues.length} issue(s))`
+    };
+  }
+  const report = parsed.data;
+  report.findings = report.findings.map((finding) => ({
+    ...finding,
+    description: finding.description ?? finding.detail,
+    ...finding.source === void 0 ? { source: { agent: report.agent, reportId: report.id, ...report.pipelineRunId !== void 0 ? { pipelineRunId: report.pipelineRunId } : {} } } : {}
+  }));
+  return { valid: true, report };
+}
+function normalizeEvidence(input) {
+  if (input === void 0) return void 0;
+  return input.map(
+    (item) => typeof item === "string" ? { kind: "observation", excerpt: item } : item
+  );
+}
+
+// src/reports/aggregate.ts
 var SEVERITY_RANK = {
   info: 0,
   low: 1,
@@ -2039,7 +3102,12 @@ function aggregateReports(reports, options = {}) {
   }
   const sources = [...new Set(reports.map((r) => r.agent))].sort();
   const totalRawFindings = reports.reduce((sum, r) => sum + r.findings.length, 0);
-  const summary = `${reports.length} report(s) from ${sources.length > 0 ? sources.join(", ") : "no agents"}: ${findingGroups.length} unique finding group(s) (${totalRawFindings} raw), ${recommendationGroups.length} recommendation group(s).`;
+  const conflicts = detectConflicts(findingGroups);
+  const agreements = findingGroups.filter(
+    (group) => group.sources.length > 1 && group.severity !== void 0 && new Set(Object.values(group.severityBySource ?? {})).size === 1
+  );
+  const disputed = conflicts.length;
+  const summary = `${reports.length} report(s) from ${sources.length > 0 ? sources.join(", ") : "no agents"}: ${findingGroups.length} unique finding group(s) (${totalRawFindings} raw), ${agreements.length} agreement(s), ${disputed} conflict(s), ${recommendationGroups.length} recommendation group(s).`;
   return {
     id: `combined-${Date.now().toString(36)}-${randomBytes2(3).toString("hex")}`,
     title: options.objective !== void 0 ? truncate3(options.objective, 120) : "Combined report",
@@ -2048,10 +3116,57 @@ function aggregateReports(reports, options = {}) {
     taskIds: options.taskIds ?? [],
     summary,
     findings: findingGroups.sort((a, b) => rank(b) - rank(a)),
+    agreements,
+    conflicts,
     recommendations: recommendationGroups,
     sources,
     reportIds: reports.map((r) => r.id),
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata: {
+      agents: sources.length,
+      reports: reports.length,
+      rawFindings: totalRawFindings,
+      findingGroups: findingGroups.length,
+      agreements: agreements.length,
+      conflicts: conflicts.length
+    }
+  };
+}
+function rankConfidence(confidence) {
+  return confidence ? { low: 1, medium: 2, high: 3 }[confidence] : 0;
+}
+function detectConflicts(groups) {
+  const conflicts = [];
+  for (const group of groups) {
+    if (group.sources.length < 2) continue;
+    const severities = new Set(Object.values(group.severityBySource ?? {}));
+    if (severities.size > 1) {
+      conflicts.push({
+        type: "severity",
+        findingTitle: group.title,
+        positions: group.sources.map((source) => position(source, group)),
+        note: `Agents disagree on severity (${[...severities].sort((a, b) => SEVERITY_RANK[a] - SEVERITY_RANK[b]).join(", ")}); the highest severity is shown, every position is preserved.`
+      });
+    }
+    const recommendations = (group.recommendations ?? []).filter((r) => r.length > 0);
+    if (recommendations.length > 1) {
+      conflicts.push({
+        type: "recommendation",
+        findingTitle: group.title,
+        positions: group.sources.map((source) => position(source, group)),
+        note: `Agents proposed ${recommendations.length} different fixes; none was discarded.`
+      });
+    }
+  }
+  return conflicts;
+}
+function position(source, group) {
+  return {
+    agent: source.agent,
+    reportId: source.reportId,
+    ...group.severityBySource?.[source.agent] !== void 0 ? { severity: group.severityBySource[source.agent] } : {},
+    ...group.confidenceBySource?.[source.agent] !== void 0 ? { confidence: group.confidenceBySource[source.agent] } : {},
+    ...group.recommendations?.[0] !== void 0 ? { recommendation: group.recommendations[0] } : {}
   };
 }
 function rank(finding) {
@@ -2064,10 +3179,22 @@ function mergeFinding(groups, finding, report, threshold) {
     group.occurrences += 1;
     group.details.push(finding.detail);
     group.sources.push(source);
-    group.evidence.push(...finding.evidence ?? []);
+    group.evidence.push(...normalizeEvidence(finding.evidence) ?? []);
     if (finding.severity && (!group.severity || SEVERITY_RANK[finding.severity] > SEVERITY_RANK[group.severity])) {
       group.severity = finding.severity;
     }
+    if (finding.confidence && rankConfidence(finding.confidence) > rankConfidence(group.confidence)) {
+      group.confidence = finding.confidence;
+    }
+    if (finding.severity) {
+      group.severityBySource = { ...group.severityBySource, [report.agent]: finding.severity };
+    }
+    if (finding.confidence) {
+      group.confidenceBySource = { ...group.confidenceBySource, [report.agent]: finding.confidence };
+    }
+    if (finding.recommendation && !group.recommendations?.includes(finding.recommendation)) {
+      group.recommendations = [...group.recommendations ?? [], finding.recommendation];
+    }
     return;
   }
   groups.push({
@@ -2076,7 +3203,11 @@ function mergeFinding(groups, finding, report, threshold) {
     sources: [source],
     occurrences: 1,
     ...finding.severity ? { severity: finding.severity } : {},
-    evidence: [...finding.evidence ?? []]
+    ...finding.confidence ? { confidence: finding.confidence } : {},
+    ...finding.severity ? { severityBySource: { [report.agent]: finding.severity } } : {},
+    ...finding.confidence ? { confidenceBySource: { [report.agent]: finding.confidence } } : {},
+    ...finding.recommendation ? { recommendations: [finding.recommendation] } : {},
+    evidence: [...normalizeEvidence(finding.evidence) ?? []]
   });
 }
 function mergeRecommendation(groups, text, report, threshold) {
@@ -2158,6 +3289,7 @@ function extractReportFromText(raw, meta) {
     id: `${meta.taskId}-f-${index + 1}`,
     title: truncate4(text, 120),
     detail: text,
+    description: text,
     severity: guessSeverity(text)
   }));
   return {
@@ -2168,7 +3300,8 @@ function extractReportFromText(raw, meta) {
     summary,
     findings,
     recommendations: recommendationTexts.map((t) => truncate4(t, 200)),
-    metadata: evidenceTexts.length > 0 ? { evidence: evidenceTexts } : void 0,
+    ...evidenceTexts.length > 0 ? { evidence: evidenceTexts.map((excerpt) => ({ kind: "observation", excerpt })) } : {},
+    metadata: evidenceTexts.length > 0 ? { evidenceCount: evidenceTexts.length } : void 0,
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
@@ -2184,27 +3317,46 @@ var ReportService = class {
   }
   store;
   log;
+  /** Rejected reports from the last collection (§13 — malformed never enters aggregation). */
+  lastDiagnostics = { collected: 0, accepted: 0, rejected: [] };
   get storeRef() {
     return this.store;
   }
-  /** Normalizes finished tasks into reports (§17 — normalizer). */
+  /** Normalizes finished tasks into reports (§17 — normalizer), validating each
+   *  one so malformed reports never reach aggregation (§13). */
   async collectFromTasks(tasks) {
-    const reports = [];
+    const candidates = [];
     for (const task of tasks) {
       const structured = task.result?.reports ?? [];
       if (structured.length > 0) {
-        reports.push(...structured);
+        candidates.push(...structured);
         continue;
       }
       const text = task.result?.rawOutput ?? task.result?.summary ?? "";
       if (text.trim().length === 0) continue;
-      reports.push(
+      candidates.push(
         extractReportFromText(text, {
           taskId: task.id,
           agent: task.agent ?? "unknown"
         })
       );
     }
+    const reports = [];
+    const rejected = [];
+    for (const candidate of candidates) {
+      const result = validateReport(candidate);
+      if (result.valid) {
+        reports.push(result.report);
+      } else {
+        rejected.push({
+          key: candidate?.id ?? "(unknown)",
+          reason: result.reason,
+          issues: result.issues.map((issue) => `${issue.path}: ${issue.message}`)
+        });
+        this.log.warn(`Rejected malformed report: ${result.reason}`);
+      }
+    }
+    this.lastDiagnostics = { collected: candidates.length, accepted: reports.length, rejected };
     return reports;
   }
   async saveReports(reports) {
@@ -2293,8 +3445,9 @@ function registerReportCommands(program) {
       return;
     }
     for (const c of combined) {
+      const conflicts = c.conflicts.length > 0 ? `  ${c.conflicts.length} CONFLICT(S)` : "";
       console.log(
-        `${c.id}  ${c.findings.length} finding(s) from ${c.sources.length} source(s)${c.pipelineRunId ? `  run=${c.pipelineRunId}` : ""}`
+        `${c.id}  ${c.findings.length} finding(s) from ${c.sources.length} source(s)${conflicts}${c.pipelineRunId ? `  run=${c.pipelineRunId}` : ""}`
       );
     }
   });
@@ -2331,6 +3484,21 @@ function registerReportCommands(program) {
       console.log(`  reports:   ${combined.reportIds.length}`);
       if (combined.pipelineRunId) console.log(`  run:       ${combined.pipelineRunId}`);
       console.log(`  summary:   ${combined.summary}`);
+      if (combined.conflicts.length > 0) {
+        console.log(`  CONFLICTS (${combined.conflicts.length}) \u2014 both positions preserved:`);
+        for (const conflict of combined.conflicts) {
+          console.log(`    ! ${conflict.findingTitle} [${conflict.type}]`);
+          for (const position2 of conflict.positions) {
+            console.log(
+              `        ${position2.agent}: severity=${position2.severity ?? "unstated"}${position2.recommendation ? ` fix="${position2.recommendation}"` : ""}`
+            );
+          }
+          console.log(`        ${conflict.note}`);
+        }
+      }
+      if (combined.agreements.length > 0) {
+        console.log(`  agreements: ${combined.agreements.length} (multi-agent consensus)`);
+      }
       if (combined.findings.length > 0) {
         console.log("  findings (grouped, duplicates merged):");
         for (const finding of combined.findings) {
@@ -2367,19 +3535,32 @@ var HeuristicPlanner = class {
   name = "heuristic";
   async plan(request) {
     const steps = [];
-    const findings = request.reports.flatMap(
-      (report) => report.findings.map((finding) => ({ finding, agent: report.agent }))
-    );
     const recommendations = dedupe(request.reports.flatMap((r) => r.recommendations));
-    for (const [index, text] of recommendations.entries()) {
+    for (const text of recommendations) {
       steps.push({
         id: `step-${steps.length + 1}`,
         title: truncate5(text, 120),
         order: steps.length + 1,
-        ...index > 0 ? { dependsOn: [`step-${steps.length}`] } : {}
+        ...steps.length > 0 ? { dependsOn: [`step-${steps.length}`] } : {}
       });
     }
-    const significant = findings.filter(({ finding }) => finding.severity ? SEVERITY_RANK2[finding.severity] >= SEVERITY_RANK2.high : false).sort((a, b) => SEVERITY_RANK2[b.finding.severity ?? "info"] - SEVERITY_RANK2[a.finding.severity ?? "info"]);
+    const contributed = request.aggregated ? request.aggregated.findings.map((finding) => ({
+      finding: {
+        id: `agg-${slug(finding.title)}`,
+        title: finding.title,
+        detail: finding.details[0] ?? finding.title,
+        ...finding.severity ? { severity: finding.severity } : {},
+        ...finding.recommendations && finding.recommendations.length > 0 ? { recommendation: finding.recommendations[0] } : {}
+      },
+      agent: finding.sources.map((s) => s.agent).join("+")
+    })) : request.reports.flatMap(
+      (report) => report.findings.map((finding) => ({ finding, agent: report.agent }))
+    );
+    const significant = contributed.filter(
+      ({ finding }) => finding.severity ? SEVERITY_RANK2[finding.severity] >= SEVERITY_RANK2.high : false
+    ).sort(
+      (a, b) => SEVERITY_RANK2[b.finding.severity ?? "info"] - SEVERITY_RANK2[a.finding.severity ?? "info"]
+    );
     for (const { finding } of significant) {
       steps.push(remediationStep(finding, steps.length + 1));
     }
@@ -2392,12 +3573,20 @@ var HeuristicPlanner = class {
       });
     }
     const risks = significant.filter(({ finding }) => finding.severity === "critical").map(({ finding }) => `Critical finding unaddressed until its step completes: ${finding.title}`);
+    const conflicts = request.aggregated?.conflicts ?? [];
+    if (conflicts.length > 0) {
+      risks.push(
+        `${conflicts.length} unresolved agent disagreement(s): ${conflicts.map((c) => c.findingTitle).join("; ")}`
+      );
+    }
     return {
       id: `plan-${Date.now().toString(36)}-${randomBytes3(3).toString("hex")}`,
       objective: request.objective,
+      goal: request.aggregated?.title ?? truncate5(request.objective, 120),
       summary: `Derived from ${request.reports.length} report(s): ${recommendations.length} recommendation step(s), ${significant.length} remediation step(s).`,
       steps,
       ...risks.length > 0 ? { risks } : {},
+      ...request.constraints !== void 0 && request.constraints.length > 0 ? { constraints: request.constraints } : {},
       generatedBy: "heuristic",
       ...request.taskId !== void 0 ? { taskId: request.taskId } : {},
       ...request.pipelineRunId !== void 0 ? { pipelineRunId: request.pipelineRunId } : {},
@@ -2412,24 +3601,76 @@ function remediationStep(finding, order) {
     description: finding.detail,
     order,
     dependsOn: order > 1 ? [`step-${order - 1}`] : [],
-    sourceFindings: [finding.id]
+    sourceFindings: [finding.id],
+    ...finding.recommendation ? { recommendation: finding.recommendation } : {}
   };
 }
 function dedupe(texts) {
   return [...new Set(texts.map((t) => t.trim()).filter((t) => t.length > 0))];
 }
+function slug(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+}
 function truncate5(text, max) {
   return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
 }
 
 // src/planner/model.ts
 import { randomBytes as randomBytes4 } from "crypto";
-import { z as z2 } from "zod";
+
+// src/planner/schema.ts
+import { z as z3 } from "zod";
+var planStepSchema = z3.object({
+  id: z3.string().min(1).optional(),
+  title: z3.string().min(1),
+  description: z3.string().optional(),
+  order: z3.number().int().optional(),
+  targets: z3.array(z3.string()).optional(),
+  acceptance_criteria: z3.array(z3.string()).optional(),
+  depends_on: z3.array(z3.string()).optional(),
+  source_findings: z3.array(z3.string()).optional()
+});
+var planJsonSchema = z3.object({
+  goal: z3.string().min(1),
+  summary: z3.string().min(1),
+  steps: z3.array(planStepSchema).min(1),
+  risks: z3.array(z3.string()).optional(),
+  notes: z3.array(z3.string()).optional()
+});
+function validatePlan(plan) {
+  const issues = [];
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const [index, step] of plan.steps.entries()) {
+    if (stepIds.has(step.id)) {
+      issues.push({ path: `steps.${index}.id`, message: `duplicate step id "${step.id}"` });
+    }
+    stepIds.add(step.id);
+    if (!step.title || step.title.trim().length === 0) {
+      issues.push({ path: `steps.${index}.title`, message: "title must not be empty" });
+    }
+    for (const dep of step.dependsOn ?? []) {
+      if (!stepIds.has(dep) && !plan.steps.some((s) => s.id === dep)) {
+        issues.push({ path: `steps.${index}.dependsOn`, message: `unknown step dependency "${dep}"` });
+      }
+    }
+  }
+  if (plan.steps.length === 0) {
+    issues.push({ path: "steps", message: "a plan needs at least one step" });
+  }
+  if (!plan.summary || plan.summary.trim().length === 0) {
+    issues.push({ path: "summary", message: "summary must not be empty" });
+  }
+  return issues.length > 0 ? { valid: false, issues, reason: `plan failed validation (${issues.length} issue(s))` } : { valid: true, plan };
+}
 
 // src/planner/context.ts
 function buildPlannerContext(request) {
-  const parts = [`# Objective
+  const parts = [`# Task
 ${request.objective}`];
+  if (request.projectContext) {
+    parts.push(`# Project context
+${request.projectContext}`);
+  }
   if (request.role) {
     const roleLines = [`# Role
 ${request.role.name} (${request.role.id})`];
@@ -2449,7 +3690,7 @@ ${request.role.name} (${request.role.id})`];
       )
     );
     parts.push(
-      `# Findings (${request.reports.length} report(s) by ${agents})
+      `# Agent reports (${request.reports.length} by ${agents})
 ` + (findingLines.length > 0 ? findingLines.join("\n") : "(no findings reported)")
     );
     const recommendationLines = request.reports.flatMap(
@@ -2459,9 +3700,20 @@ ${request.role.name} (${request.role.id})`];
       parts.push(`# Recommendations
 ${recommendationLines.join("\n")}`);
     }
-    const summaryLines = request.reports.map((report) => `- [${report.agent}] ${report.summary}`);
-    parts.push(`# Report summaries
-${summaryLines.join("\n")}`);
+  }
+  if (request.aggregated) {
+    const aggregatedLines = [
+      `- findings: ${request.aggregated.findings.length} (agreements: ${request.aggregated.agreements.length}, conflicts: ${request.aggregated.conflicts.length})`,
+      ...request.aggregated.findings.map(
+        (finding) => `- [${finding.severity ?? "info"}] ${finding.title} (x${finding.occurrences})`
+      ),
+      // Conflicts stay visible to the planner — it must plan around disagreement.
+      ...request.aggregated.conflicts.map(
+        (conflict) => `- CONFLICT (${conflict.type}) on "${conflict.findingTitle}": ${conflict.note}`
+      )
+    ];
+    parts.push(`# Aggregated findings
+${aggregatedLines.join("\n")}`);
   }
   if (request.memory && request.memory.length > 0) {
     parts.push(
@@ -2469,7 +3721,11 @@ ${summaryLines.join("\n")}`);
 ` + request.memory.map((entry2) => `- [${entry2.scope}] ${entry2.content}`).join("\n")
     );
   }
-  if (request.context && request.context.length > 0) {
+  if (request.constraints && request.constraints.length > 0) {
+    parts.push(`# Constraints
+${request.constraints.map((c) => `- ${c}`).join("\n")}`);
+  }
+  if (request.context) {
     parts.push(`# Research context
 ${request.context}`);
   }
@@ -2477,22 +3733,6 @@ ${request.context}`);
 }
 
 // src/planner/model.ts
-var planStepJsonSchema = z2.object({
-  id: z2.string().optional(),
-  title: z2.string().min(1),
-  description: z2.string().optional(),
-  order: z2.number().int().optional(),
-  targets: z2.array(z2.string()).optional(),
-  acceptance_criteria: z2.array(z2.string()).optional(),
-  depends_on: z2.array(z2.string()).optional(),
-  source_findings: z2.array(z2.string()).optional()
-}).strict();
-var planJsonSchema = z2.object({
-  summary: z2.string().min(1),
-  steps: z2.array(planStepJsonSchema).min(1),
-  risks: z2.array(z2.string()).optional(),
-  notes: z2.array(z2.string()).optional()
-}).strict();
 var ModelPlanner = class {
   constructor(options) {
     this.options = options;
@@ -2506,7 +3746,7 @@ var ModelPlanner = class {
     const messages = [
       {
         role: "system",
-        content: 'You are the OmniNode planner. Given the objective and the combined research context, produce a final analysis and a prioritized, actionable implementation plan. Respond with JSON ONLY (no prose, no code fences) matching exactly this shape: {"summary": string, "steps": [{"id": string, "title": string, "description": string, "order": number, "targets": string[], "acceptance_criteria": string[], "source_findings": string[]}], "risks": string[], "notes": string[]}. ' + (this.options.instruction ?? "")
+        content: 'You are the OmniNode planner. Given the objective and the combined research context, produce a final analysis and a prioritized, actionable implementation plan. Respond with JSON ONLY (no prose, no code fences) matching exactly this shape: {"goal": string, "summary": string, "steps": [{"id": string, "title": string, "description": string, "order": number, "targets": string[], "acceptance_criteria": string[], "source_findings": string[]}], "risks": string[], "notes": string[]}. ' + (this.options.instruction ?? "")
       },
       { role: "user", content: context }
     ];
@@ -2517,60 +3757,86 @@ var ModelPlanner = class {
       return this.degrade(request, `planner model call failed: ${describe(error)}`);
     }
     const parsed = parsePlanJson(responseText);
-    if (!parsed) {
-      return this.degrade(request, "planner model output was not valid plan JSON");
+    if (!parsed.ok) {
+      return this.degrade(request, `planner model output rejected: ${parsed.reason}`, parsed.issues);
     }
     const plan = {
       id: `plan-${Date.now().toString(36)}-${randomBytes4(3).toString("hex")}`,
       objective: request.objective,
+      goal: parsed.goal,
       summary: parsed.summary,
       steps: parsed.steps,
       ...parsed.risks !== void 0 ? { risks: parsed.risks } : {},
       ...parsed.notes !== void 0 ? { notes: parsed.notes } : {},
+      ...request.constraints !== void 0 && request.constraints.length > 0 ? { constraints: request.constraints } : {},
       generatedBy: `model:${this.options.model}`,
       model: this.options.model,
       ...request.taskId !== void 0 ? { taskId: request.taskId } : {},
       ...request.pipelineRunId !== void 0 ? { pipelineRunId: request.pipelineRunId } : {},
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    return plan;
+    const validation = validatePlan(plan);
+    if (!validation.valid) {
+      return this.degrade(request, `generated plan rejected: ${validation.reason}`, validation.issues);
+    }
+    return validation.plan;
   }
-  async degrade(request, reason) {
+  async degrade(request, reason, issues = []) {
     if (this.options.fallback) {
       this.log.warn(`${reason} \u2014 using the heuristic fallback planner.`);
       return this.options.fallback.plan(request);
     }
-    throw new PlannerError("PLANNER_FAILED", `Planner failed: ${reason}.`);
+    throw new PlannerError("PLAN_INVALID", `Planner failed: ${reason}.`, {
+      details: { reason, issues }
+    });
   }
 };
 function parsePlanJson(text) {
   const unfenced = text.replace(/```(?:json)?/gi, "");
   const start = unfenced.indexOf("{");
   const end = unfenced.lastIndexOf("}");
-  if (start < 0 || end <= start) return void 0;
+  if (start < 0 || end <= start) {
+    return { ok: false, reason: "planner output contained no JSON object", issues: [] };
+  }
+  let json;
   try {
-    const json = JSON.parse(unfenced.slice(start, end + 1));
-    const parsed = planJsonSchema.safeParse(json);
-    if (!parsed.success) return void 0;
-    const steps = parsed.data.steps.map((step, index) => ({
-      id: step.id ?? `step-${index + 1}`,
-      title: step.title,
-      description: step.description,
-      order: step.order ?? index + 1,
-      targets: step.targets,
-      acceptanceCriteria: step.acceptance_criteria,
-      dependsOn: step.depends_on,
-      sourceFindings: step.source_findings
-    }));
+    json = JSON.parse(unfenced.slice(start, end + 1));
+  } catch (error) {
     return {
-      summary: parsed.data.summary,
-      steps: steps.sort((a, b) => a.order - b.order),
-      risks: parsed.data.risks,
-      notes: parsed.data.notes
+      ok: false,
+      reason: `planner output was not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      issues: []
+    };
+  }
+  const parsed = planJsonSchema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      reason: "planner output did not match the plan schema",
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path.join(".") || "(root)",
+        message: issue.message
+      }))
     };
-  } catch {
-    return void 0;
   }
+  const steps = parsed.data.steps.map((step, index) => ({
+    id: step.id ?? `step-${index + 1}`,
+    title: step.title,
+    description: step.description,
+    order: step.order ?? index + 1,
+    targets: step.targets,
+    acceptanceCriteria: step.acceptance_criteria,
+    dependsOn: step.depends_on,
+    sourceFindings: step.source_findings
+  })).sort((a, b) => a.order - b.order);
+  return {
+    ok: true,
+    goal: parsed.data.goal,
+    summary: parsed.data.summary,
+    steps,
+    risks: parsed.data.risks,
+    notes: parsed.data.notes
+  };
 }
 function describe(error) {
   return error instanceof Error ? error.message : String(error);
@@ -2584,9 +3850,23 @@ var PipelineEngine = class {
   }
   options;
   log;
+  /** Runs executing in THIS process — cancellation can terminate them directly. */
+  activeRuns = /* @__PURE__ */ new Map();
   get store() {
     return this.options.store;
   }
+  /**
+   * 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).
+   */
+  async persist(run2) {
+    const current = await this.options.store.get(run2.id);
+    await this.options.store.save({
+      ...run2,
+      ...current?.cancellationRequested === true ? { cancellationRequested: true, cancellationRequestedAt: current.cancellationRequestedAt } : {}
+    });
+  }
   /** Structural + semantic validation (§27 Phase 5 — pipeline parser). */
   validate(def) {
     const ids = /* @__PURE__ */ new Set();
@@ -2686,18 +3966,44 @@ var PipelineEngine = class {
           );
         }
       }
+      if (step.model) {
+        const separator = step.model.indexOf(":");
+        if (separator <= 0 || separator === step.model.length - 1) {
+          throw new PipelineError(
+            "PIPELINE_INVALID",
+            `Step "${step.id}" has an invalid model reference "${step.model}" \u2014 use "provider:model-id".`
+          );
+        }
+        const providerName = step.model.slice(0, separator);
+        if (!this.options.providers.some((p) => p.name === providerName)) {
+          throw new PipelineError(
+            "PIPELINE_INVALID",
+            `Step "${step.id}" uses model "${step.model}" but provider "${providerName}" is not configured.`
+          );
+        }
+      }
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const run2 = {
       id: `run-${Date.now().toString(36)}-${randomBytes5(3).toString("hex")}`,
       pipelineId: def.id,
+      attempt: 1,
       objective,
       status: "running",
       startedAt: now,
       stepRuns: []
     };
     await this.options.store.save(run2);
-    this.log.info(`Running pipeline ${def.id} as ${run2.id}.`);
+    const liveTaskIds = /* @__PURE__ */ new Set();
+    this.activeRuns.set(run2.id, {
+      taskIds: liveTaskIds,
+      cancelTasks: async () => {
+        for (const taskId of liveTaskIds) {
+          await this.options.tasks.cancel(taskId).catch(() => void 0);
+        }
+      }
+    });
+    this.log.info(`Running pipeline ${def.id} as ${run2.id} (attempt ${run2.attempt}).`);
     await this.options.audit?.record({
       at: (/* @__PURE__ */ new Date()).toISOString(),
       action: "pipeline.run.started",
@@ -2709,7 +4015,22 @@ var PipelineEngine = class {
     const pending = new Set(def.steps.map((s) => s.id));
     const contextParts = [];
     const allReports = [];
+    let cancelled = false;
     while (pending.size > 0) {
+      const persisted = await this.options.store.get(run2.id);
+      if (persisted?.cancellationRequested === true) {
+        cancelled = true;
+        run2.cancellationRequested = true;
+        run2.cancellationRequestedAt = persisted.cancellationRequestedAt;
+        await this.activeRuns.get(run2.id)?.cancelTasks();
+        for (const step of def.steps.filter((s) => pending.has(s.id))) {
+          const stepRun = { stepId: step.id, status: "cancelled" };
+          run2.stepRuns.push(stepRun);
+          options.onStep?.(stepRun);
+        }
+        pending.clear();
+        break;
+      }
       const ready = def.steps.filter(
         (step) => pending.has(step.id) && (deps.get(step.id) ?? []).every((d) => outcomes.has(d))
       );
@@ -2726,7 +4047,8 @@ var PipelineEngine = class {
             ...role ? { role } : {},
             combinedContext: contextParts.join("\n\n"),
             reports: [...allReports],
-            pipelineRunId: run2.id
+            pipelineRunId: run2.id,
+            runId: run2.id
           };
           return this.executeStep(step, ctx);
         })
@@ -2743,7 +4065,9 @@ ${contribution}`);
         }
         const stepRun = {
           stepId: step.id,
-          status: outcome.status === "skipped" ? "cancelled" : outcome.status === "failed" ? "failed" : "completed",
+          attempt: outcome.attempt ?? 1,
+          ...outcome.executionIds && outcome.executionIds.length > 0 ? { executionIds: outcome.executionIds } : {},
+          status: outcome.status === "skipped" ? "cancelled" : outcome.status === "failed" ? "failed" : outcome.status === "partial" ? "partially_completed" : "completed",
           ...outcome.taskIds.length > 0 ? { taskIds: outcome.taskIds } : {},
           ...outcome.planId !== void 0 ? { planId: outcome.planId } : {},
           ...outcome.error !== void 0 ? { error: outcome.error } : {}
@@ -2752,10 +4076,12 @@ ${contribution}`);
         options.onStep?.(stepRun);
       });
       run2.reports = [...allReports];
-      await this.options.store.save(run2);
+      await this.persist(run2);
     }
-    const failed = [...outcomes.values()].some((o) => o.status === "failed");
-    const finalStatus = failed ? "failed" : "completed";
+    const allOutcomes = [...outcomes.values()];
+    const failed = !cancelled && allOutcomes.some((o) => o.status === "failed");
+    const partial = !cancelled && !failed && allOutcomes.some((o) => o.status === "partial");
+    const finalStatus = cancelled ? "cancelled" : failed ? "failed" : partial ? "partial" : "completed";
     const planId = [...outcomes.values()].find((o) => o.planId !== void 0)?.planId;
     let resultSummary;
     for (let i = def.steps.length - 1; i >= 0; i -= 1) {
@@ -2783,16 +4109,19 @@ ${contribution}`);
         run2.reports = collected;
       }
     }
+    const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.activeRuns.delete(run2.id);
     const finished = {
       ...run2,
       status: finalStatus,
-      finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      finishedAt,
+      attempts: [...run2.attempts ?? [], { attempt: run2.attempt, startedAt: run2.startedAt ?? finishedAt, finishedAt, status: finalStatus }],
       ...run2.reports !== void 0 && run2.reports.length > 0 ? { reports: run2.reports } : {},
       ...combinedReportId !== void 0 ? { combinedReportId } : {},
       ...planId !== void 0 ? { planId } : {},
       ...resultSummary !== void 0 ? { resultSummary } : {}
     };
-    await this.options.store.save(finished);
+    await this.persist(finished);
     this.log.info(`Pipeline ${def.id} finished: ${finalStatus}.`);
     await this.options.audit?.record({
       at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2802,6 +4131,23 @@ ${contribution}`);
     });
     return finished;
   }
+  /** First-class cancellation (§9.2): requests cancellation and terminates
+   *  tasks that are running in this process immediately. */
+  async cancel(runId) {
+    const run2 = await this.options.store.get(runId);
+    if (!run2) {
+      throw new PipelineError("PIPELINE_NOT_FOUND", `Pipeline run "${runId}" does not exist.`);
+    }
+    await this.options.store.save({
+      ...run2,
+      cancellationRequested: true,
+      cancellationRequestedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const active = this.activeRuns.get(runId);
+    if (active) {
+      await active.cancelTasks();
+    }
+  }
   async get(runId) {
     return this.options.store.get(runId);
   }
@@ -2825,9 +4171,16 @@ ${contribution}`);
         this.log.warn(`Step "${step.id}" failed \u2014 retry ${attempt}/${retries}.`);
       }
       last = await this.executeStepOnce(step, ctx);
-      if (last.status !== "failed") return last;
+      if (last.status !== "failed") return { ...last, attempt: attempt + 1 };
     }
-    return last;
+    return { ...last, attempt: retries + 1 };
+  }
+  /** Registers tasks created for a step as live, so cancellation can terminate them (§9.2). */
+  trackLiveTasks(runId, taskIds) {
+    if (!runId) return;
+    const active = this.activeRuns.get(runId);
+    if (!active) return;
+    for (const id of taskIds) active.taskIds.add(id);
   }
   async executeStepOnce(step, ctx) {
     switch (step.kind) {
@@ -2860,7 +4213,10 @@ ${contribution}`);
         })
       )
     );
+    this.trackLiveTasks(ctx.runId, created.map((t) => t.id));
     const results = await Promise.all(created.map((task) => this.options.tasks.run(task.id)));
+    const executionIds = results.map((r) => r.executions?.at(-1)?.executionId).filter((id) => id !== void 0);
+    const completedTasks = results.filter((r) => r.status === "completed");
     const failedTasks = results.filter((r) => r.status !== "completed");
     const lines = results.map((result, index) => {
       const agentName = agentNames[index] ?? "unknown";
@@ -2870,16 +4226,25 @@ ${contribution}`);
     const reports = results.flatMap((r) => r.result?.reports ?? []);
     const summary = lines.join("\n");
     if (failedTasks.length > 0) {
-      const firstError = failedTasks[0]?.result?.error ?? "unknown error";
+      const firstError = failedTasks[0]?.result?.error ?? failedTasks[0]?.lastError ?? "unknown outcome";
+      const states = failedTasks.map((r) => r.status).join(", ");
       return {
-        status: "failed",
+        // Some agents succeeded → the step produced usable but incomplete
+        // intelligence: partial, not failed (roadmap §9.3).
+        status: completedTasks.length > 0 ? "partial" : "failed",
         summary,
         taskIds: created.map((t) => t.id),
-        error: `${failedTasks.length}/${results.length} task(s) failed \u2014 ${firstError}`,
+        error: `${failedTasks.length}/${results.length} task(s) incomplete (${states}) \u2014 ${firstError}`,
         reports
       };
     }
-    return { status: "completed", summary, taskIds: created.map((t) => t.id), reports };
+    return {
+      status: "completed",
+      summary,
+      taskIds: created.map((t) => t.id),
+      ...executionIds.length > 0 ? { executionIds } : {},
+      reports
+    };
   }
   async runSingle(step, ctx, agentName) {
     const task = await this.options.tasks.create({
@@ -2888,10 +4253,13 @@ ${contribution}`);
       ...ctx.role ? { role: ctx.role.id } : {},
       ...ctx.combinedContext.length > 0 ? { context: { background: ctx.combinedContext } } : {}
     });
+    this.trackLiveTasks(ctx.runId, [task.id]);
     const result = await this.options.tasks.run(task.id);
     if (result.status !== "completed") {
       return {
-        status: "failed",
+        // Unknown/timed_out outcomes are not failures — the work may have
+        // happened remotely; the step is incomplete, not broken.
+        status: result.status === "unknown" || result.status === "timed_out" ? "partial" : "failed",
         summary: result.result?.summary ?? "",
         taskIds: [task.id],
         error: result.result?.error ?? `task ${task.id} did not complete`,
@@ -2906,11 +4274,14 @@ ${contribution}`);
     };
   }
   async runPlan(step, ctx) {
+    const aggregated = ctx.reports.length > 0 ? aggregateReports(ctx.reports) : void 0;
     const request = {
       objective: ctx.objective,
       reports: ctx.reports,
+      ...aggregated !== void 0 ? { aggregated } : {},
       ...ctx.combinedContext.length > 0 ? { context: ctx.combinedContext } : {},
       ...ctx.role ? { role: ctx.role } : {},
+      ...step.constraints !== void 0 && step.constraints.length > 0 ? { constraints: step.constraints } : {},
       ...ctx.pipelineRunId !== void 0 ? { pipelineRunId: ctx.pipelineRunId } : {}
     };
     let planner;
@@ -3078,7 +4449,11 @@ function buildPipelineEngine(config, log = logger) {
     agents,
     roles,
     store: new FileTaskStore(),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
     audit: new FileAuditLog(),
     log
   });
@@ -3136,6 +4511,24 @@ function registerPipelineCommands(program) {
     }
     await runPipelineAction(def.id, objective ?? previous.objective);
   });
+  pipeline.command("cancel <run-id>").description("Request cancellation of a pipeline run (stops scheduling and cancels running tasks).").action(async (runId) => {
+    const config = loadConfig();
+    const engine = buildPipelineEngine(config);
+    await engine.cancel(runId);
+    console.log(`Cancellation requested for run ${runId}.`);
+    console.log("A run executing in another process stops at its next check point.");
+  });
+  pipeline.command("validate <id>").description("Validate a pipeline definition before running it (\xA79.5).").action(async (id) => {
+    const config = loadConfig();
+    const def = findPipeline(config, id);
+    const engine = buildPipelineEngine(config);
+    engine.validate(def);
+    console.log(`Pipeline "${def.id}" is valid (${def.steps.length} step(s)).`);
+    for (const step of def.steps) {
+      const deps = step.dependsOn?.join(", ") ?? "(previous step)";
+      console.log(`  ${step.id}  kind=${step.kind}  depends_on=${deps}`);
+    }
+  });
   pipeline.command("runs <id>").description("List recorded runs of a pipeline.").action(async (id) => {
     const config = loadConfig();
     const engine = buildPipelineEngine(config);
@@ -3145,7 +4538,8 @@ function registerPipelineCommands(program) {
       return;
     }
     for (const run2 of runs) {
-      console.log(`${run2.id}  ${run2.status.padEnd(10)} ${run2.startedAt ?? "?"}`);
+      const note = isInterrupted(run2) ? "  (interrupted \u2014 process gone before finish)" : "";
+      console.log(`${run2.id}  ${run2.status.padEnd(10)} ${run2.startedAt ?? "?"}${note}`);
     }
   });
   pipeline.command("status <run-id>").description("Show the recorded state of a pipeline run.").action(async (runId) => {
@@ -3163,6 +4557,13 @@ function registerPipelineCommands(program) {
     console.log(`  status:     ${run2.status}`);
     console.log(`  started:    ${run2.startedAt ?? "?"}`);
     if (run2.finishedAt) console.log(`  finished:   ${run2.finishedAt}`);
+    console.log(`  attempt:   ${run2.attempt}`);
+    if (run2.cancellationRequested) {
+      console.log(`  cancellation requested at ${run2.cancellationRequestedAt ?? "?"}`);
+    }
+    if (isInterrupted(run2)) {
+      console.log("  note:       this run looks interrupted (no finishedAt) \u2014 retry with `pipeline retry`");
+    }
     if (run2.resultSummary) console.log(`  result:     ${run2.resultSummary}`);
     for (const stepRun of run2.stepRuns) {
       console.log(`  [${stepRun.stepId}] ${stepRun.status}`);
@@ -3204,6 +4605,9 @@ async function runPipelineAction(id, objective) {
 function registerRunAlias(program) {
   program.command("run <id> [objective]").description("Alias of `omninode pipeline run` \u2014 execute a configured pipeline end to end.").action(async (id, objective) => runPipelineAction(id, objective));
 }
+function isInterrupted(run2) {
+  return run2.status === "running" && run2.finishedAt === void 0;
+}
 function findPipeline(config, id) {
   const def = config.project.pipelines.find((p) => p.id === id);
   if (!def) {